ThRuntime_Field_Settings
This class acts as a powerful helper object for accessing the properties of a table's columns at runtime.The main purpose of this class is to provide a single, unified interface for querying field metadata.
It abstracts the complexity of the underlying table, allowing you to get information like a field's `VisualName`, `Kind` (data type), `ReadOnly` status, and `ValuesList` without needing to know if you are working with a standard `ThTable` or a custom `ThPrvTable`.
You do not create an instance of this class directly. Instead, you access it through the read-only `FldSet` property of a `ThTable` or `ThPrvTable` component.
Name
Returns the logical name of a field at a specific column index. For a standard `ThTable`, this is the field name from the schema.For a `ThPrvTable`, this is the name of the private field, which may be different from the database field it is linked to.
Function Name(CONST Index: Integer): String;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns a `String` containing the logical name of the field.DB_Fld_Name
Returns the actual database schema field name for a column at a specific index.For a `ThPrvTable`, this function always returns the name of the underlying schema field it is linked to, ignoring the private field's custom name.
If the field is not linked to the database schema, it returns an empty string.
Function DB_Fld_Name(CONST Index: Integer): String;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns a `String` containing the true schema name of the field.VisualName
Returns the display caption for a field, suitable for use in user interfaces.The function is language-aware and will return the appropriate translation based on the table's language setting or the optional `AtLanguage` parameter.
It prioritizes custom captions set at runtime before falling back to the schema's translated captions.
Function VisualName(CONST Index: Integer; CONST AtLanguage: ThTranslation_Language = he_Unknown): String;
Parameters
- Index: Integer; The zero-based column index of the field.
- AtLanguage: ThTranslation_Language; An optional parameter to request the caption in a specific language. If omitted, the table's current language is used.
Return Value
Returns a `String` containing the translated display caption for the field.VisualName2
A convenience function that returns the display caption for a field, identifying the field by its name instead of its index.It is a wrapper for the `VisualName` function.
Function VisualName2(CONST FldName: String; CONST AtLanguage: ThTranslation_Language = he_Unknown): String;
Parameters
- FldName: String; The name of the field for which to retrieve the visual caption.
- AtLanguage: ThTranslation_Language; An optional parameter to request the caption in a specific language. If omitted, the table's current language is used.
Return Value
Returns a `String` containing the translated display caption for the field.Kind
Returns the data type of the field at a specific column index.For a `ThPrvTable` field linked to a schema, it returns the data type from the underlying database field.
Function Kind(CONST Index: Integer): ThDataType;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns a `ThDataType` enumerated value (e.g., `he_String`, `he_Integer`, `he_Date`).EditorType
Returns the user interface editor type for a field, which determines how it should be displayed and edited in data-aware controls like `ThDataGrid` and `ThFieldsArea`.In `he_Fixing_Data_Interface` access mode, the function may return a more advanced editor type to facilitate data maintenance.
Function EditorType(CONST Index: Integer): ThEditorType;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns a `ThEditorType` enumerated value (e.g., `he_Edit`, `he_Select`, `he_Memo`).TextLength
Returns the maximum allowed length (in characters) for a string-based field.This function is only applicable to fields with a string-based `Kind` (`he_String`, `he_Name`, etc.).
Function TextLength(CONST Index: Integer): Word;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns a `Word` indicating the maximum number of characters allowed in the field.AnyDuty
Checks if a field is considered mandatory by either of the schema's two duty flags (`DutyField` or `DutyField2`).
Function AnyDuty(CONST Index: Integer): Boolean;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns `True` if the field is marked as mandatory by `DutyField` or `DutyField2` in the schema.Duty
Checks if a field is mandatory, taking the table's `rt_DutyLevel2` property into account.If `rt_DutyLevel2` is `False`, it only checks the `DutyField` schema property.
If `rt_DutyLevel2` is `True`, it checks both `DutyField` and `DutyField2`, behaving like the `AnyDuty` function.
Function Duty(CONST Index: Integer): Boolean;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns `True` if the field is considered mandatory based on the current duty level.DutyGroup
Returns the mandatory group number for a field.Fields that share the same non-zero `DutyGroup` number belong to a set where at least one of them must be filled to pass validation.
Function DutyGroup(CONST Index: Integer): Byte;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns a `Byte` representing the duty group number. A value of 0 indicates the field is not part of a duty group.Hidden
Checks if a field should be considered hidden from the user.It considers the field's `Hidden` property from the schema, dynamic access control flags, and the table's current `TableAccess` mode.
Function Hidden(CONST Index: Integer; CONST ExportProtection: Boolean = False): Boolean;
Parameters
- Index: Integer; The zero-based column index of the field.
- ExportProtection: Boolean; If `True`, the function will also consider a field hidden if its `StrMask` property is set to '***' (password).
Return Value
Returns `True` if the field should be treated as hidden, otherwise `False`.ReadOnly
Checks if a field should be considered read-only.The result depends on the table's `TableAccess` mode, the field's `ReadOnly` property in the schema, and any dynamic access control flags.
Function ReadOnly(CONST Index: Integer): Boolean;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns `True` if the field is not editable, otherwise `False`.ReadOnly_ACF
Checks specifically if a field has been made read-only by a dynamic access control flag (`ACF_Field_Is_Readonly`).This function is primarily for web development to determine if a field was blocked by dynamic authorization rules, ignoring the static schema setting.
Function ReadOnly_ACF(CONST Index: Integer): Boolean;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns `True` only if the field has been marked as read-only by the dynamic access control system.Spare_Field
Checks if a field is designated as a "spare" field in the database schema.Spare fields are typically generic columns intended for future or custom use.
Function Spare_Field(CONST Index: Integer): Boolean;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns `True` if the field is a spare field, otherwise `False`.LocalLang
Checks if a field is designated to support localization and translation.When this property is `True` for a field, its visual elements (like captions or dropdown lists) will be translated according to the table's current language setting.
Function LocalLang(CONST Index: Integer): Boolean;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns `True` if the field is marked for localization, otherwise `False`.Enforce_Input_Lang
Returns the input language restriction rule for a string-based field.This rule is used by UI controls to validate user input and ensure it conforms to the required language(s).
Function Enforce_Input_Lang(CONST Index: Integer): ThEnforce_Input_Lang;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns a `ThEnforce_Input_Lang` enumerated value, which can be `he_No_Filter`, `he_Acceptable`, or `he_EnglishOnly`.A detailed description of `ThEnforce_Input_Lang` can be found in the ThScmField documentation.
Language
Determines and returns the specific language that should be used for displaying the content of a field.If the field's `LocalLang` property is `True`, this function returns the table's current language setting. Otherwise, it defaults to `he_English`.
Function Language(CONST Index: Integer): ThTranslation_Language;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns a `ThTranslation_Language` enumerated value indicating the appropriate language for the field.StrMask
Returns the formatting or input mask string defined for a field in the schema.This mask provides special formatting rules for UI controls.
For example, `'@'` indicates an email field, `'***'` indicates a password field, and `'###,##0.00'` defines numeric formatting.
Function StrMask(CONST Index: Integer): String;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns a `String` containing the mask defined for the field.DefStr
Returns the default value for a field as a `String`. This default value is defined in the field's `DefStr` property in the schema.
Function DefStr(CONST Index: Integer): String;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns a `String` containing the field's default value.ValuesList
Returns a multi-line string containing the list of predefined, acceptable values for a field.This list is typically used to populate dropdowns or selection controls.
The function is language-aware and will return a translated list if available.
Function ValuesList(CONST Index: Integer; CONST AtLanguage: ThTranslation_Language = he_Unknown): String;
Parameters
- Index: Integer; The zero-based column index of the field.
- AtLanguage: ThTranslation_Language; An optional parameter to request the list in a specific language. If omitted, the table's current language is used.
Return Value
Returns a `String` where each line represents an item in the values list.ValuesList2
A convenience function that returns the list of predefined values for a field, identifying the field by its name instead of its index.It is a wrapper for the `ValuesList` function.
Function ValuesList2(CONST FldName: String; CONST AtLanguage: ThTranslation_Language = he_Unknown): String;
Parameters
- FldName: String; The name of the field for which to retrieve the values list.
- AtLanguage: ThTranslation_Language; An optional parameter to request the list in a specific language. If omitted, the table's current language is used.
Return Value
Returns a `String` where each line represents an item in the values list.Get_ValuesList_SpecificItems
Retrieves the full `ValuesList` for a field and then filters it, returning only the items at the indexes specified in an array.
Function Get_ValuesList_SpecificItems(CONST FldName: String; CONST ReqItems: Array OF Integer; CONST AtLanguage: ThTranslation_Language = he_Unknown): String;
Parameters
- FldName: String; The name of the field from which to get the values list.
- ReqItems: Array OF Integer; An array of zero-based indexes specifying which items to extract from the full list.
- AtLanguage: ThTranslation_Language; An optional parameter to request the list in a specific language before filtering.
Return Value
Returns a multi-line `String` containing only the requested items from the values list.Check_MaxValue & Check_MinValue
These functions check whether a maximum or minimum value constraint is enabled for a numeric field.
Function Check_MaxValue(CONST Index: Integer): Boolean;
Function Check_MinValue(CONST Index: Integer): Boolean;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns `True` if the respective maximum or minimum value check is enabled for the field in the schema, otherwise `False`.MaxValue & MinValue
These functions return the defined maximum or minimum allowed numeric value for a field.
Function MaxValue(CONST Index: Integer): Double;
Function MinValue(CONST Index: Integer): Double;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns a `Double` representing the maximum or minimum boundary value defined for the field in the schema.Design_Notes
Returns the developer notes associated with a field.These notes are stored in the `Design_Notes` property in the schema and are intended for documentation purposes.
Function Design_Notes(CONST Index: Integer): String;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns a `String` containing the design-time notes for the field.Json_Name
Returns the field name that should be used when serializing the table to JSON format.It prioritizes a runtime-assigned JSON name over the one defined in the schema.
If no specific JSON name is set, one is generated from the field's standard `Name`.
A special return value of `'*'` indicates that the field should be excluded from JSON output.
Function Json_Name(CONST Index: Integer): RawByteString;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns a `RawByteString` containing the field's name for JSON serialization.Skip_Spare_Field
Determines if a `SpareField` should be skipped during certain operations, like data serialization or UI generation.A spare field is skipped only if it is marked as a spare field in the schema AND it has not been dynamically customized at runtime.
Function Skip_Spare_Field(CONST Index: Integer): Boolean;
Parameters
- Index: Integer; The zero-based column index of the field.
Return Value
Returns `True` if the spare field should be skipped, otherwise `False`.Field_Exist
Checks if a field with the specified name exists in the table's collection of fields.
Function Field_Exist(CONST FldName: String): Boolean;
Parameters
- FldName: String; The name of the field to check for.
Return Value
Returns `True` if the field exists, otherwise `False`.Get_Index
Returns the zero-based column index for a field specified by its name.For a `ThPrvTable`, it first searches for a private field with that name, and if not found, it searches for a linked schema field with that name.
Function Get_Index(CONST FldName: String; Alert_On_Error: Boolean = True): Integer;
Parameters
- FldName: String; The name of the field to find.
- Alert_On_Error: Boolean; If `True` (default) and the field is not found, an error message will be posted.
Return Value
Returns the `Integer` index of the column if found; otherwise, returns -1.Get_Index_By_Json
Returns the zero-based column index for a field by searching for its assigned `Json_Name`.This is primarily used when deserializing JSON data into the table.
Function Get_Index_By_Json(CONST FindJsonName: RawByteString): Integer;
Parameters
- FindJsonName: RawByteString; The JSON name of the field to find.
Return Value
Returns the `Integer` index of the column if found; otherwise, returns -1.Get_Index_Combined
Provides a flexible way to find a column's index by first searching for its standard `Name`, and if that fails, searching for its `Json_Name`.
Function Get_Index_Combined(CONST FldName: String; Alert_On_Error: Boolean = True): Integer;
Parameters
- FldName: String; The standard name or JSON name of the field to find.
- Alert_On_Error: Boolean; If `True` (default) and the field is not found, an error message will be posted.
Return Value
Returns the `Integer` index of the column if found by either name; otherwise, returns -1.Get_Index_By_Title
Returns the zero-based column index for a field by searching for its `VisualName` (display caption).The search is language-aware and uses the table's current language setting.
Function Get_Index_By_Title(CONST Find_VisualName: String): Integer;
Parameters
- Find_VisualName: String; The display caption of the field to find.
Return Value
Returns the `Integer` index of the column if a matching caption is found; otherwise, returns -1.Set_Duty
Programmatically sets the mandatory status and group for a specific field at runtime.
Function Set_Duty(CONST FldName: String; CONST Level1, Level2: Boolean; CONST Group: Byte): Boolean;
Parameters
- FldName: String; The name of the field to modify.
- Level1: Boolean; Sets the primary mandatory flag (`DutyField`).
- Level2: Boolean; Sets the secondary mandatory flag (`DutyField2`).
- Group: Byte; Sets the mandatory group number (`DutyGroup`).
Return Value
Returns `True` if the operation was successful.Set_ReadOnly
Programmatically sets the read-only status of a specific field at runtime.
Function Set_ReadOnly(FldName: String; Value: Boolean): Boolean;
Parameters
- FldName: String; The name of the field to modify.
- Value: Boolean; Set to `True` to make the field read-only, or `False` to make it editable.
Return Value
Returns `True` if the operation was successful.Set_Hidden
Programmatically sets the visibility of a specific field at runtime.
Function Set_Hidden(FldName: String; Value: Boolean): Boolean;
Parameters
- FldName: String; The name of the field to modify.
- Value: Boolean; Set to `True` to hide the field, or `False` to make it visible.
Return Value
Returns `True` if the operation was successful.Set_VisualName
Programmatically sets a custom display caption for a field at runtime.This allows you to override the default schema caption for a specific language.
Function Set_VisualName(FldName, NewCaption: String; CONST AtLanguage: ThTranslation_Language = he_Unknown): Boolean;
Parameters
- FldName: String; The name of the field to modify.
- NewCaption: String; The new display caption for the field.
- AtLanguage: ThTranslation_Language; The specific language for which to set the caption. If omitted, the table's current language is used.
Return Value
Returns `True` if the operation was successful.Set_ValuesList
Programmatically sets or replaces the list of predefined values for a field at runtime.This is useful for dynamically populating dropdown lists based on application logic.
Function Set_ValuesList(FldName, NewList: String; CONST AtLanguage: ThTranslation_Language = he_Unknown; CONST Skip_Length_Check: Boolean = False): Boolean;
Parameters
- FldName: String; The name of the field to modify.
- NewList: String; A multi-line string where each line represents an item in the new list.
- AtLanguage: ThTranslation_Language; The specific language for which to set this list. If omitted, the table's current language is used.
- Skip_Length_Check: Boolean; If `False` (default), it will check if any item in the new list exceeds the field's `TextLength` and show a warning if it does.
Return Value
Returns `True` if the operation was successful.Set_Minimal_Value & Set_Maximal_Value
These functions programmatically set the minimum or maximum value constraints for a numeric field at runtime.
Function Set_Minimal_Value(FldName: String; Limit: Boolean; MinValue: Double): Boolean;
Function Set_Maximal_Value(FldName: String; Limit: Boolean; MaxValue: Double): Boolean;
Parameters
- FldName: String; The name of the field to modify.
- Limit: Boolean; Set to `True` to enable the constraint, or `False` to disable it.
- MinValue: Double; The minimum allowed value for the field.
- MaxValue: Double; The maximum allowed value for the field.
Return Value
Returns `True` if the operation was successful.Set_Numeric_MinMax
A convenience function that calls both `Set_Minimal_Value` and `Set_Maximal_Value` to enable and define both boundaries of a numeric range constraint at once.
Function Set_Numeric_MinMax(FldName: String; MinValue, MaxValue: Double): Boolean;
Parameters
- FldName: String; The name of the field to modify.
- MinValue: Double; The minimum allowed value for the field.
- MaxValue: Double; The maximum allowed value for the field.
Return Value
Returns `True` if both operations were successful.Convert_String_To_Cell
A core conversion function that takes a raw string and converts it into a `ThDataCell` record, which is the table's internal cell storage format.The conversion logic is based on the field's `Kind` (data type), correctly parsing strings, numbers, dates, booleans, and status values.
Function Convert_String_To_Cell(CONST Index: Integer; CONST New: String; CONST KeepValInRange: Boolean): ThDataCell;
Parameters
- Index: Integer; The column index of the field, which defines the conversion rule.
- New: String; The input string to be converted.
- KeepValInRange: Boolean; If `True`, the resulting numeric value will be clamped to the field's defined `MinValue` and `MaxValue`.
Return Value
Returns a `ThDataCell` record populated with the converted data.
ThDataCell is a packed record, not a class, that represents the fundamental storage unit for a single cell within a ThTable.
Each cell in the table's in-memory grid is an instance of this record.
| Field | Description |
|---|---|
| Text: String | Used to store the value for string-based data types (e.g., `he_String`, `he_Name`). |
| Data: ThNumeric | Used to store the value for all numeric and date/time data types (e.g., `he_Integer`, `he_Real`, `he_Date`). |
| Flag: Boolean | Flag for general-purpose use, often for marking a row or cell for a specific operation. |
| Width, Height: Word | Used by visual controls to cache the calculated pixel dimensions of the cell for rendering. These fields are only available in UI applications. |
Status_Flds_Error_List
A read-only property that returns a `ThStringList` containing any errors that occurred during the conversion of strings to status values (`he_Status`).When `Convert_String_To_Cell` encounters a string that does not match an item in the status field's `ValuesList`, it adds the invalid string to this list.
This property may be `NIL` if no errors have occurred.
Property Status_Flds_Error_List: ThStringList Read Status_Errors_List;