ThPrvTable

The ThPrvTable (Private Table) is a specialized descendant of ThTable that allows a developer to define a custom, in-memory table structure for specific tasks.
Its primary feature is its flexible collection of fields, which can be either:
  • Linked: Acting as a "view" or data projection of a real schema table, inheriting properties from the schema's fields.
  • Private: Existing only within the ThPrvTable instance, perfect for temporary calculations or holding UI-specific data.
This component is ideal for situations where you need a specific data layout—such as for a UI form, a report, or an intermediate data processing step—without modifying the global database schema.

GlobalInit

The main initialization procedure for the component.
It must be called after setting the `TableName` or programmatically modifying the `Fields` collection.
This procedure links the private fields to their corresponding schema fields and prepares the table's internal data storage for use.

Procedure GlobalInit; Override;

Copy_Design_Notes_To_Fields_Visualname

A design-time convenience procedure that populates the runtime `rt_VisualName` of each field with the content of its `Design_Notes` property.
This is a shortcut for developers to quickly set display captions from their comments.
The procedure will automatically call `GlobalInit` if any changes are made.

Procedure Copy_Design_Notes_To_Fields_Visualname;

FindField

Finds and returns a `THPrvField` object from the collection using different search criteria.

Function FindField(CONST TField: String; CONST Algo: Byte = 0): THPrvField;

Parameters

  • TField: String; The name or caption of the field to find.
  • Algo: Byte; A code that specifies the search method:
    • 0 (Default): Searches by the private field's logical `Name`.
    • 1: Searches by the field's `VisualName` (display caption).
    • 2: Searches by the `Name` of the linked database schema field.
    • 3: First tries to find by `Name` (Algo 0), then by linked schema field `Name` (Algo 2).

Return Value

Returns the `THPrvField` object if found, otherwise `NIL`.

Execute_Configuration_Dialog_OR_HALT

A high-level procedure for managing application settings stored in an INI file.
It loads settings from the specified INI file into the table. If the file doesn't exist or if validation fails, it displays a configuration dialog to the user.
Important: If the user cancels this dialog, the application will terminate (`HALT`).

Procedure Execute_Configuration_Dialog_OR_HALT(Subject: String; InI_FileName: String = '');

Parameters

  • Subject: String; The title to be displayed on the configuration dialog window.
  • InI_FileName: String; The name of the INI file to use. If omitted, it defaults to the application's name with an '.ini' extension.

Update_INI_File_As_Configuration_Dialog

Unconditionally saves the current contents of the `ThPrvTable` to the application's default INI file (`ApplicationName.ini`), overwriting any existing content.

Procedure Update_INI_File_As_Configuration_Dialog;

Calc_Single_Row_SizeInBytes

Calculates the total size of a single row in bytes, as it would be stored in a binary stream.
This method is used internally for data serialization.

Function Calc_Single_Row_SizeInBytes(Only_Real_Table_Fields: Boolean): Cardinal; Override;

Parameters

  • Only_Real_Table_Fields: Boolean; If `True`, the calculation will only include fields that are linked to the database schema, ignoring purely private fields.

Return Value

Returns a `Cardinal` representing the size of one record in bytes.

Fields

The primary property for configuring the structure of the `ThPrvTable`.
It provides access to the `THPrvFields` collection, allowing you to programmatically add, remove, and access the individual private fields (columns) of the table.

Property Fields: THPrvFields;

Live_Fields_Permissions

A boolean property that controls how permission-related properties (like `ReadOnly`, `Hidden`, `DutyField`) are determined for linked fields.
  • When `False` (default), the private field uses its own local property values.
  • When `True`, the private field ignores its local settings and dynamically inherits these properties directly from the linked schema field. This allows for centralized permission control from the main schema.

Property Live_Fields_Permissions: Boolean;

THPrvFields

THPrvFields is the collection class responsible for managing the fields of a ThPrvTable component.
It holds a list of THPrvField objects, which collectively define the custom column structure of the private table.
You do not create an instance of this class directly. Instead, you access it through the `Fields` property of a ThPrvTable component to programmatically add, remove, or modify its columns.

Add

Adds a new `THPrvField` to the collection.
If the optional `Link_To_Field` parameter is provided, the new field will be automatically linked to the specified schema field, inheriting its properties.

Function Add(Link_To_Field: String = ''): THPrvField;

Parameters

  • Link_To_Field: String; (Optional) The name of a field in the parent `ThPrvTable`'s schema to link to.

Return Value

Returns the newly created `THPrvField` object, or `NIL` if the operation fails.

AddNew

A convenience function to add a new, fully configured, unlinked private field in a single call.

Function AddNew(Name, VisualName: String; Kind: ThDataType; LocalLang: Boolean = False; TextLength: Word = 0; EditorType: ThEditorType = he_Edit; Duty: Boolean = False; ReadOnly: Boolean = False; Hidden: Boolean = False): THPrvField;

Parameters

  • Name: String; The logical name for the new field.
  • VisualName: String; The display caption for the new field.
  • Kind: ThDataType; The data type of the new field.
  • LocalLang: Boolean; Sets the localization property.
  • TextLength: Word; Sets the maximum character length for string types.
  • EditorType: ThEditorType; Sets the UI editor type.
  • Duty: Boolean; Sets the mandatory status.
  • ReadOnly: Boolean; Sets the read-only status.
  • Hidden: Boolean; Sets the visibility status.

Return Value

Returns the newly created `THPrvField` object, or `NIL` if the operation fails.

Add_Copy_Field

Adds a new, unlinked private field to the collection by copying the entire definition from an existing `ThScmField` (schema field) object.

Function Add_Copy_Field(CopyFrom: ThScmField): THPrvField;

Parameters

  • CopyFrom: ThScmField; The schema field object whose properties will be copied.

Return Value

Returns the newly created `THPrvField` object, or `NIL` if the operation fails.

Add_Copy_PrvField

Adds a new private field to the collection by copying the definition from another existing `THPrvField` object.

Function Add_Copy_PrvField(CopyFrom: THPrvField): THPrvField;

Parameters

  • CopyFrom: THPrvField; The private field object to clone.

Return Value

Returns the newly created `THPrvField` object, or `NIL` if the operation fails.

Delete_Range

Removes a range of fields (columns) from the private table's structure.

Procedure Delete_Range(FromField, UntilField: Integer);

Parameters

  • FromField: Integer; The starting index of the range of fields to delete.
  • UntilField: Integer; The ending index of the range of fields to delete.

Items

The default indexed property that provides direct access to a `THPrvField` object in the collection by its numerical index.

Property Items[Index: Integer]: THPrvField;

Access

Because it is the default property, you can access a field directly using bracket notation on the collection, for example:
MyPrivateTable.Fields[0].ReadOnly := True;