ThPrvTable

The ThPrvTable (Private Table) is a specialized version of ThTable designed to create a custom, in-memory table structure for specific tasks.
Its primary feature is the ability to define a collection of fields that can be independent of the main database schema.
Fields in a ThPrvTable can be either:
  • Linked: Acting as a "view" or a data projection of a real schema table (`ThScmTable`), containing a specific subset or reordering of its fields.
  • Private: Existing only within this table instance, useful for temporary calculations or holding UI-specific data.
This makes it ideal for building custom queries, preparing data for reports, or defining the exact data needed for a specific form without altering the global schema.
It is used and instantiated just like a standard ThTable but offers greater flexibility in defining its column structure at design-time or runtime.

rt_VisualName

A string property that allows you to set a custom display caption for a private field at runtime.
When this property is assigned a value, it overrides any `VisualName` that would otherwise be inherited from a linked schema field.
As the `{Single Lang}` comment implies, this caption is for a single language and is not automatically translated.

rt_VisualName: String;

rt_Json_FieldName

A `RawByteString` property used to assign a custom name to a field specifically for JSON serialization.
This runtime name takes precedence over any JSON name defined in the schema.
Assigning the special value `'*'` to this property will cause the field to be excluded from any JSON output.

rt_Json_FieldName: RawByteString;

Get_Enforce_Local_Lang_Combined

A helper function intended for internal use by Delphi dialogs to get a single code representing the field's language enforcement rules.

Function Get_Enforce_Local_Lang_Combined: Byte;

Return Value

Returns a `Byte` code that combines the `LocalLang` and `Enforce_Input_Lang` properties into a single value for easier processing in the UI.

VisualName

Returns the display caption for the private field, suitable for user interfaces.
It prioritizes a custom caption set in `rt_VisualName`. If that is empty, it returns the translated caption from the linked schema field. If there is no linked field, it defaults to the field's `Name`.

Function VisualName: String;

Return Value

Returns a `String` containing the most appropriate display caption for the field.

rt_Add_Val

Adds a new string item to the field's local `ValuesList` at runtime.
This list is single-language and is not automatically translated.

Procedure rt_Add_Val(New: String; Skip_Length_Check: Boolean = False);

Parameters

  • New: String; The new item to add to the list.
  • Skip_Length_Check: Boolean; If `False` (default), the function will check if the new string exceeds the field's `TextLength` and show a warning if it does.

rt_Translate_Values_List

Translates all items in the field's local, single-language `ValuesList` in-place.
It uses the global translation engine, based on the parent `ThPrvTable`'s current language setting.

Procedure rt_Translate_Values_List;

Copy_Def_From_Field_Ptr

A core procedure that copies the properties (like `Kind`, `EditorType`, `ValuesList`, etc.) from a `ThScmField` object into the current private field.

Procedure Copy_Def_From_Field_Ptr(CONST _Fld: ThScmField; CONST WithLimitations: Boolean);

Parameters

  • _Fld: ThScmField; A pointer to the source schema field from which to copy the definition.
  • WithLimitations: Boolean; If `True`, restrictive properties like `DutyField` and min/max value checks are also copied.

rt_Copy_Definition_From

A user-friendly wrapper function that finds a schema field by its table and field name and copies its definition to the current private field.

Function rt_Copy_Definition_From(TableName: String; FieldName: String = ''; WithLimitations: Boolean = False): THPrvField;

Parameters

  • TableName: String; The name of the schema table containing the source field.
  • FieldName: String; The name of the source field. If omitted, the current private field's `Name` is used.
  • WithLimitations: Boolean; If `True`, restrictive properties like `DutyField` are also copied.

Return Value

Returns a pointer to itself (`Self`) for chaining calls.

rt_Disconnect_Live_Link

Breaks the live link between a private field and its schema field.
It does this by first copying all the properties from the schema field, making them static values on the private field, and then clearing the link.

Procedure rt_Disconnect_Live_Link;

rt_Link_To_Field_By_Json_Name & rt_Link_To_Field_By_Customized_Name

These functions dynamically create a link to a schema field at runtime using an alternative identifier instead of the field's `Name`.

Function rt_Link_To_Field_By_Json_Name(CONST FindJsonName: String): Boolean;
Function rt_Link_To_Field_By_Customized_Name(CONST AnyLang_Field_Title: String): Boolean;

Parameters

  • FindJsonName: String; The `Json_Name` of the schema field to link to.
  • AnyLang_Field_Title: String; A custom visual name (in any language) of the schema field to link to.

Return Value

Returns `True` if a matching schema field was found and the link was successfully created, otherwise `False`.

Live_Link_To_Field

A read-only property that provides direct access to the `ThScmField` object that the private field is linked to.
If the private field is not linked to the schema, this property will be `NIL`.

Property Live_Link_To_Field: ThScmField;

Return Value

Returns a `ThScmField` object pointer if the field is linked, otherwise `NIL`.

Name

A read-write property for the logical name of the private field.
This name is used to identify the field within the `ThPrvTable` and can be different from the schema field it is linked to.

Property Name: String;

Kind

A read-write property that sets the data type for an unlinked private field.
If the private field is linked to a schema field, this property is ignored, and the `Kind` from the schema is used instead.

Property Kind: ThDataType Read FKind Write FKind Default he_String;

LocalLang

A read-write property that specifies whether an unlinked private field should support localization.
If the field is linked to the schema, the `LocalLang` property of the schema field is used instead.

Property LocalLang: Boolean;

TextLength

A read-write property that sets the maximum character length for an unlinked, string-based private field.
If the field is linked to the schema, the `TextLength` from the schema field is used instead.

Property TextLength: Word;

DefStr

A read-write property that sets the default value for an unlinked private field.
If the field is linked to the schema, the default value is inherited from the schema field's `DefStr` property.

Property DefStr: String;

DutyField & DutyField2

Boolean properties that mark an unlinked private field as mandatory.
The framework provides two separate flags to allow for different levels or types of validation logic.
If the field is linked to the schema, the duty properties from the schema field are used instead.

Property DutyField: Boolean;
Property DutyField2: Boolean;

DutyGroup

A `Byte` property that assigns an unlinked private field to a mandatory group.
Fields sharing the same non-zero `DutyGroup` number are treated as a set where at least one of them must be filled.
If the field is linked to the schema, this property is inherited.

Property DutyGroup: Byte;

CheckExtMinValue & ExtMinValue

These properties work together to define a minimum value constraint for an unlinked private field.
These settings are ignored if the field is linked to the schema.

Property CheckExtMinValue: Boolean;
Property ExtMinValue: Double;
  • CheckExtMinValue: A `Boolean` that enables (`True`) or disables (`False`) the minimum value validation.
  • ExtMinValue: A `Double` that specifies the minimum allowed value when the check is enabled.

CheckExtMaxValue & ExtMaxValue

These properties work together to define a maximum value constraint for an unlinked private field.
These settings are ignored if the field is linked to the schema.

Property CheckExtMaxValue: Boolean;
Property ExtMaxValue: Double;
  • CheckExtMaxValue: A `Boolean` that enables (`True`) or disables (`False`) the maximum value validation.
  • ExtMaxValue: A `Double` that specifies the maximum allowed value when the check is enabled.

EditorType

A read-write property that sets the UI editor type for an unlinked private field.
If the field is linked to the schema, the `EditorType` is inherited from the schema field.
A detailed description of `ThEditorType` can be found in the ThScmField documentation. 

Property EditorType: ThEditorType;

ValuesList

A read-write property that holds a multi-line string of predefined values for an unlinked private field.
This list is single-language and is not automatically translated. If the field is linked to the schema, this property is inherited.

Property ValuesList: String;

ReadOnly

A read-write property that sets the read-only status for an unlinked private field.
If the field is linked to the schema, this property is inherited.

Property ReadOnly: Boolean;

Hidden

A read-write property that sets the visibility for an unlinked private field.
If the field is linked to the schema, this property is inherited.

Property Hidden: Boolean;

Link_To_Field

A crucial read-write property that establishes a live link between the private field and a field in the `ThPrvTable`'s associated schema table.
When this property is set to a valid schema field name, the private field inherits most of its properties (like `Kind`, `ReadOnly`, `ValuesList`, etc.) directly from that schema field.

Property Link_To_Field: String;

StrMask

A read-write property that sets the formatting or input mask for an unlinked private field.
This mask provides special formatting rules for UI controls, such as `'@'` for an email field or `'***'` for a password field.
If the field is linked to the schema, this property is inherited.

Property StrMask: String;

Trans_VisualName

A boolean property that, when set to `True`, automatically translates the `Name` of an unlinked private field to generate its `VisualName` (display caption).
This is a convenience feature to avoid manually setting a visual name if the field's logical name is a standard, translatable term.

Property Trans_VisualName: Boolean;

Design_Notes

A read-write string property intended for developers to store design-time notes or comments about an unlinked private field.
It has no effect on the component's runtime behavior and is ignored if the field is linked to the schema.

Property Design_Notes: String Read FDesign_Notes Write FDesign_Notes;

Enforce_Input_Lang

A read-write property that sets the language input restriction rule for an unlinked, string-based private field.
This setting is used by UI controls to validate user input. If the field is linked to the schema, this property is inherited.

Property Enforce_Input_Lang: ThEnforce_Input_Lang;
A detailed description of `ThEnforce_Input_Lang` can be found in the ThScmField documentation.