Implements the TValueListEditor grid control.

valedit.pas contains classes and types needed for the TValueListEditor control. It is a specialized 2-column grid control used to display and edit key / value pairs.

The following components are added to the Additional tab in the Lazarus IDE component palette:

TValueListEditor

Indicates the editor style for items in TValueListEditor.

TEditStyle is an enumeration type with values that indicate the editor style used for an item in TValueListEditor. TEditStyle is the type used for the TItemProp.EditStyle property.

TItemProp.EditStyle Displays an editor without decoration for the cell. Displays an ellipsis button next to the cell editor. Displays a pick list for the cell editor. Indicates the sort order for items in TValueListEditor.

TVleSortCol is an enumeration type with values that indicate the sort order for items in TValueListEditor. Values in TVleSortCol refer to the ordinal position of the column used in the TValueListEditor.Sort method.

TValueListEditor.Sort The Key column is used to sort items. The Value column is used to sort items. Represents items in the TValueListEditor control.

TItemProp is a TPersistent descendant that represents items in the TValueListEditor control. TItemProp provides properties and methods to define the editor used for a Key-Value pair. These include the editor style, editing mask, maximum length, pick list values, and read-only status for the item.

TItemProp maintains a reference to the TValueListEditor for the item, and allows access to the properties, methods, and events for the grid control.

TItemProp is the type used for items in the TItemPropList container, and stored in the TValueListEditor.ItemProps property.

TItemPropList TValueListEditor.ItemProps TPersistent Gets the value for the PickList property. Value for the property. Implements the OnChange event handler for the PickList property. Object for the event notification. Sets the value for the EditMask property. New value for the property. Sets the value for the MaxLength property. New value for the property. Sets the value for the ReadOnly property. New value for the property. Sets the value for the EditStyle property. New value for the property. Sets the value for the PickList property. New value for the property. Sets the value for the KeyDesc property. New value for the property. Stores property values to the specified persistent object.

AssignTo is a procedure used to store property values in the class instance to the specified persistent object. AssignTo ensures that Dest is a ItemProp class instance prior to storing the following properties in the target:

EditMask
EditStyle
KeyDesc
PickList
MaxLength
ReadOnly

If Dest is not a TItemProp class instance, the inherited AssignTo method is called.

TPersistent.Assign Persistent object to receive values from the class. Constructor for the class instance.

Create is the constructor for the class instance, and calls the inherited method. Create ensures that the TValueListEditor instance in AOwner is used as the owner of the item.

Owner of the class instance. Destructor for the class instance.

Destroy is the destructor for the class instance. Destroy frees resources allocated for the PickList property, and calls the inherited Destroy method.

Specifies the edit mask used when editing the value for the item.

EditMask is a String property which specifies the edit mask used when editing an item in TValueListEditor. EditMask can contain the edit mask notation used in TMaskEdit, such as:

\: Quotes the following character; i. e. '\-' inserts the literal '-' character
<: Converts following characters to upper case
>: Converts following characters to lower case
l: Allows an optional letter value [A-Z][a-z]
L: Requires a letter value [A-Z][a-z]
a: Optional alphanumeric character [A-Z][a-z][0-9]
A: Required alphanumeric character [A-Z][a-z][0-9]
c: Optional UTF-8-encoded character [#32-#255]
C: Required UTF-8-encoded character [#32-#255]
9: Optional numeric value [0-9]
0: Required numeric value [0-9]
#: Optional sign or numeric value [+-][0-9]
:: Inserts the hour/minute time separator [:]
/: Inserts the date separator [/]
h: Optional hexadecimal character [0-9][A-F]
H: Required hexadecimal character [0-9][A-F]
b: Optional binary character
B: Required binary character
!: Trims leading space characters

Changing the value in EditMask causes the TValueListEditor (which owns the item) to be redrawn when its EditorMode property is True.

TCustomStringGrid.EditorMode Identifies the type of editor used for the item value.

EditStyle is a TEditStyle property which indicates the editor style to use for the item value. See TEditStyle for more information about the enumeration values and their meanings.

Changing the value in EditStyle causes the TValueListEditor (which owns the item) to be redrawn when its EditorMode property is set to True.

At run-time, adding values to the PickList overrides use of esSimple in EditStyle; the value esPickList will automatically be used. TEditStyle TItemProp.PickList TCustomStringGrid.EditorMode Describes the Key for the item in TValueListEditor.

KeyDesc is a String property that describes the Key portion of the Key-Value pair in TValueListEditor.

Values that can be selected for the item in TValueListEditor.

PickList is a TStrings property which contains values that can be selected for the item in TValueListEditor. Values in PickList are displayed using a combo-box-style drop down when editing the item.

Reading the value in PickList ensures that a TStringList class instance is assigned for the property. Its OnChange event handler is set to the private PickListChange method which adjusts the EditStyle to match the intended usage for the item. In other words, an EditStyle of esSimple is changed to esPickList when it contains values.

Assigning a new TStringList to PickList causes existing values to be overwritten. The TValueListEditor (which owns the item) is redrawn when its EditorMode property is True.

TItemProp.EditStyle TCustomStringGrid.EditorMode Specifies the maximum length of the item value.

MaxLength is an Integer property that specifies the maximum length of the item value in TValueListEditor. Changing the value in MaxLength causes the TValueListEditor (which owns the item) to be redrawn when its EditorMode property is set to True.

TCustomStringGrid.EditorMode Indicates if the value for the item can be changed.

ReadOnly is a Boolean property which indicates if the value for the item can be changed in TValueListEditor. When ReadOnly is True, the value for the item cannot be changed. Changing the value in ReadOnly causes the TValueListEditor (which owns the item) to be redrawn when its EditorMode is True.

TCustomStringGrid.EditorMode Implements a storage container for items added to TValueListEditor.

TItemPropList is a class which implements a storage container for items added to TValueListEditor. TItemPropList uses a TFPObjectList member to store the TItemProp instances in the list. A TValueListStrings member is used for the owner of the list.

Properties and Methods are provided to add or maintain the items in the list. Use Items (the default property for the container) to read or write the items defined in the list.

TItemProp TItemPropList.Items TValueListStrings Gets the value for the Count property. Value for the property. Gets the value for the indexed Items property. Ordinal position in the container with the property value. Value for the indexed property. Sets the value for the indexed Items property. Ordinal position in the container with the property value. New value for the indexed property. Appends the specified item to the list.

Add is a procedure used to append the specified item to the list. Add appends the TItemProp value in AValue to the internal list for the container. Use Items to access the items in the list by their ordinal position.

Use Insert to insert a new item at a specific ordinal position in the list. Use Delete to remove an item in the container. Use Clear to remove all items in the container.

Item to add to the container. Sets the items in the container to the specified values.

Assign is a procedure which sets the items in the container to the values specified in Source. Assign iterates over the TItemProp instances in Source, and creates new TItemProp instances and calls Assign to update the persistent objects. The newly created items are added to the internal list in the container.

No actions are performed in the method when Source is unassigned (contains Nil).

New values to store in the list for the container. Removes all items in the container.

Clear is a procedure used to remove all items in the container. Clear calls the TFPObjectList.Clear method to remove all TItemProp instances stored in the list.

Use Delete or Insert to append or insert a new item for the list.

Removes an item in the container at the specified position.

Delete is a procedure used to remove an item in the container at the specified position. Index is the ordinal position for the item in the range 0..Count-1.

Use Clear to remove all items in the container.

Use Add or Insert to store an item in the container.

Ordinal position for the item. Swaps the items at the specified positions.

Exchange is a procedure used to swap the items at the specified positions in the list. Exchange calls the corresponding method in TFPObjectList using Index1 and Index2 as arguments. Exchange is used in the implementation of the TValueListStrings.Exchange method.

TFPObjectList.Exchange TValueListStrings.Exchange Ordinal position for the item to be swapped. Ordinal position for the item to be swapped. Inserts the new item at the specified position in the container.

Insert is a procedure used to insert the new item in the container at the specified position. Index specifies the ordinal position in the range 0..Count-1 where the item will be stored. AValue is the TItemProp instance to store at the specified position. Insert calls the corresponding method in TFPObjectList using Index and AValue as arguments.

Use Add to append a new item to the container.

Ordinal position for the new item. New item to insert into the list. Constructor for the class instance.

Create is the constructor for the container. Create stores the value in AOwner as the owner of the container. Create allocates the internal TFPObjectList instance used to store Items in the list; objects in the list are owner by the container.

Owner for the container class instance. Destructor for the class instance.

Destroy is the destructor for the class instance. Destroy ensures that resources allocated to the internal list are freed; the Items in the list are freed as well. Destroy calls the inherited destructor.

Number of items in the list for the container.

Count is a read-only Integer property that indicates the number of Items in the internal list for the container. Count returns the value from the TFPObjectList.Count property.

Provides access to items in the container by their ordinal position.

Items is an indexed TItemProp property that provides access to items in the container by their ordinal position. Index is the ordinal position in the container in the range 0..Count-1.

Items is the default property for the class.

Use Add to append a new item in the container. Use Insert to insert an item in the list at a specific position.

Use Delete to remove an item at a specific position in the container. Use Clear to remove all items in the container.

Stores values and item definitions used in TValueListEditor.

TValueListStrings is a TStringList descendant used to store keys, values, and item definitions used in TValueListEditor. TValueListStrings provides methods needed to add, maintain, and sort the content in the class instance.

TStringList Gets the item definition for the specified key name or index position.

GetItemProp is a TItemProp function used to get an item definition for the specified key name or index position in the AKeyOrIndex argument. AKeyOrIndex is a variant type and contains the string with the name for a key, or the Integer row number for the item.

When a String value is used, the IndexOfName method is called to get the ordinal position for the key name. An Exception is raised if the key name does not exist in the string list.

The item definition in the associated grid control is retrieved using the ordinal position, and stored in the return value. An Exception is raised if the item definition in the list has not been assigned (contains Nil).

No actions are performed in the method when Count is zero (0), or when UpdateCount contains a non-zero value. The return value is Nil for either case.

Raises an Exception if a key with the specified name was not found in the item property list for the grid control.

Raises an Exception if the item property for the key name in unassigned (contains Nil).

Key name or index position for the item definition. TItemProp instance with the definition for the requested key name or index. Performs a quick sort for the string and TItemProp instances in the list.

Duplicates the functionality of TStringList.QuickSort, but also sorts the ItemProps.

Index position for the first value in the sort. Index position for the second value in the sort. Compare function used to implement the sort routine. Indicates if the cell editor for the control is visible but not focused. Index for the non-title row in the associated grid control. True when the cell editor for the control is visible but not focused. Inserts an item with the specified value at the position in Index.

InsertItem is an overloaded procedure used to insert an item with the specified value(s) at the position in Index.

InsertItem hides a visible cell editor in the control during the insert operation. InsertItem calls the TItemPropList.Insert method to insert a new item definition at the position in Index. A visible cell editor is restored after the item has been inserted.

TStringList Ordinal position for the new item and value. Value for the new item. Object with the definition for the new item. Sets the value for the indexed Strings property.

Put is a procedure used to store a value at the specified ordinal position. Put ensures that the TValueListEditor which owns the class instance hides a visible cell editor at the specified ordinal position. Put calls the inherited method to store the value in S at the position in Index. A visible cell editor in TValueListEditor is restored when needed.

TStrings.Strings TStringList Ordinal position for the value. Value to store at the specified position. Constructor for the class instance.

Create is the constructor for the class instance. Create calls the inherited constructor. Create uses the value in AOwner as the owner of the class instance. Create allocates resources need for the internal TItemPropList used for item definitions in the control.

TValueListEditor that owns the class instance. Destructor for the class instance.

Destroy is the destructor for the class instance. Destroy ensures that resources allocated for the internal item definitions are freed. Destroy calls the inherited destructor.

TStringList.Destroy Stores properties from Source in the current class instance.

Assign is an overridden procedure used to store properties from Source in the current class instance.

Assign uses the TValueListEditor which own the class instance to invalidate cached rows in the control. Assign calls Clear to remove any existing values and to prevent an exception when sorting values. Assign calls the inherited method using Source as an argument. If Source is a TValueListStrings instance, its internal item definitions are stored in the current class instance.

TStrings.Assign Persistent object with properties copied into the current class instance. Removes all item values and definitions in the class instance.

Clear is an overridden procedure used to remove all item names, values, and item definitions in the class instance. Clear uses the TValueListEditor which owns the class instance to clear its cached rows, and to hide a visible editor in the control. Clear calls the inherited method, and clears the internal list of item definitions for the class. TValueListEditor restores a visible editor when needed.

TStringList.Clear Provides access to the QuickSortStringsAndItemProps method.

CustomSort is an overridden procedure re-implemented to provide access to the inherited QuickSortStringsAndItemProps method.

Comparison routine for the sorting operation. Deletes the item value and definition at the specified position.

Delete is a procedure used to delete the item value and definition at the specified ordinal position.

Delete uses the TValueListEditor owner to invalidate any cached rows in the control. A visible editor in the control is also hidden. Delete calls the inherited method using Index as an argument. Deletes removes the internal item definition at the position specified in Index. A visible editor in TValueListEditor is restored when needed.

Ordinal position of the value and definition to delete. Swaps the values and item definitions at the specified positions.

Exchange is a procedure used to swap the values and item definitions at the specified positions.

Exchange uses the TValueListEditor that owns the class to invalidate any cached rows in the control. A visible editor in the control is also hidden. Exchange calls the inherited method using the values in Index1 and Index2 as arguments. Exchange swaps the item definitions at the specified positions as well. A visible editor in TValueListEditor is restored when needed.

Position of the item value and definition to swap. Position of the item value and definition to swap. Stores Key and Value information used for items in TValueListEditor.

TKeyValuePair is a record type used to store Key and Value information for the rows in TValueListEditor. TKeyValuePair is used when an editor is activated for a row in TValueListEditor.

Key data a row. Value data for a row. Represents display capabilities in TValueListEditor.

TDisplayOption is an enumeration type with values that define display capabilities available in TValueListEditor. TDisplayOption values are stored in the TDisplayOptions set type.

TDisplayOptions TValueListEditor.DisplayOptions Displays column titles on the associated TValueListEditor control. Automatically resizes the columns to fill the available space on the associated TValueListEditor control. doKeyColFixed prevents the Key column from being automatically resized; only the Value column is resized to fill the client area. Prevents the Key column in TValueListEditor from being resized using the doAutoColResize automatic column resizing algorithm. Uses the ColWidth value assigned to the control instead. Overridden by calls to the AutoSizeColumn or AutoSizeColumns methods in TValueListEditor. goColSizing in TValueListEditor.Options allows the column to be manually resized. Set type used to store TDisplayOption enumeration values.

TDisplayOptions is a set type used to store values from the TDisplayOption enumeration. TDisplayOptions is the type used for the TValueListEditor.DisplayOptions property.

TDisplayOption TValueListEditor.DisplayOptions Represents Key actions used in TValueListEditor.

TKeyOption is an enumeration type with values that control key actions allowed for Key-Value data in TValueListEditor. TKeyOption values are stored in the TKeyOptions set type.

TKeyOptions TValueListEditor.KeyOptions Allows editing of Key data. Allows adding new Key data. Allows deleting Key data. Key data must be unique. Stores values from the TKeyOption enumeration.

TKeyOptions is a set type used to store values from the TKeyOption enumeration. TKeyOptions is the type used to implement the TValueListEditor.KeyOptions property.

TKeyOptions TValueListEditor.KeyOptions Specifies an event handler signalled when loading the PickList for an item in TValueListEditor.

TGetPickListEvent is an object procedure which specifies an event handler signalled when loading the PickList for an item in TValueListEditor. TGetPickListEvent allows the application to provide custom values in the PickList for an item using the esPickList editor style.

TGetPickListEvent is the type used for the TValueListEditor.OnGetPickList event handler.

TValueListEditor.OnGetPickList TValueListEditor for the event notification. Key name for the selected row. Pick list values for the selected row. Specifies an event handler signalled to validate a changed row in TValueListEditor.

TOnValidateEvent is an object procedure type that specifies an event handler signalled when changes to a row in TValueListEditor are validated. Arguments passed to the event handler identify the control, column and row numbers, and the Key name and value.

TOnValidateEvent is the type used to implement the TValueListEditor.OnValidate event handler.

TValueListEditor.OnValidate TValueListEditor instance for the event notification. Column number in the control. Row number on the control. Key name for the modified row. Key data for the modified row. A visual grid control for editing Key-Value pairs.

TValueListEditor is a TCustomStringGrid descendant which implements a grid-style editor control for Key-Value pairs. TValueListEditor displays a two column grid where the first column is read-only, and lists the key names. The second column is for editing the associated values for the key names.

TValueListEditor provides properties with the Keys and Values displayed in the rows and columns for the control. The Cells property allows access using the familiar column and row number mechanism used in grid controls. The Strings property allows access to the strings used for the Key and Value in a row.

Since version 2.2.0, Keys will no longer allow the name/value separator used in the Strings property to be entered as a value in the Key column. When entered, focus is moved to the Value column. If pasted into the Key column, the value is silently discarded.

The ItemProps property is used to configure the cell editors used for the Keys and Values. This includes setting the editor style, edit mask, maximum length for the value, a list of selectable pick list values, and a read-only flag. Descriptive text for the Key name can also be stored in the ItemProps.

Features and behavior for the control can be specified using the Options, DisplayOptions, and KeyOptions properties.

TValueListEditor implements methods used to perform editing actions in the control, including:

Clear
DeleteRow
DeleteColRow
FindRow
InsertRow
InsertRowWithValues
Sort

TCustomStringGrid Gets the value for the indexed ItemProps property. Key name or position for the item definition. Item definition for the specified key name or position. Sets the value for the indexed ItemProps property. Key name or position for the item definition. New value for the property. Implements the OnChange event handler for the Strings property. Control triggering the event notification. Implements the OnChanging event handler in the Strings property. Control triggering the event notification. Gets the value for the Options property. Value for the property. Gets the value for the indexed Keys property. Value for the property. Position for the Key name in Keys. Gets the value for the indexed Values property. Value for the property. Key name to find in the method. Sets the values in the DisplayOptions property. New values for the property. Sets the value in the DropDownRows property. New value for the property. Sets the values in the KeyOptions property. New values for the property. Sets the value in the indexed Keys property. Position of the Key name in the item definitions. New value for the Key name. Sets the value in the indexed Values property. Key name for the specified value. New value for the specified Key name. Sets the values in the Options property. New value for the property. Sets the values in the Strings property. New values for the property. Sets the values in the TitleCaptions property. New values for the property. Updates TitleCaptions with the captions for the key and value columns.

Clears existing values in TitleCaptions.

Caption used for the Key column. Caption used for the Value column. Registers the class type for the widget set. TCustomGrid.WSRegisterClass Sets the value for the FixedCols property.

SetFixedCols is a procedure used to set the value for the FixedCols property.

New value for the property. Assigns and displays the column titles for the Key and Value columns.

ShowColumnTitles is a procedure used to assign and display the column titles for the Key and Value columns in the control. ShowColumnTitles requires column titles to be enabled by including the value doColumnTitles in the DisplayOptions property. No actions are performed in the method if column titles have not been enabled.

The text used in column titles is derived from resource strings, or values in the TitleCaptions property (when assigned). The default column titles are:

rsVLEKey: Resource string with the caption for the Key column
rsVLEValue: Resource string with the caption for the Value column

Values in TitleCaptions are used when the property contains a values at the following ordinal positions:

0: Value used as the caption for the Key column
1: Value used as the caption for the Value column

ShowColumnTitles stores the column titles to the first row in the grid control using the Cells property.

ShowColumnTitles is called automatically when the control is created, and when values in DisplayOptions or TitleCaptions are changed.

TCustomStringGrid.Cells Sets the number of visible rows for the control.

AdjustRowCount is a procedure used to set the number of visible rows for the control. AdjustRowCount uses the Strings property to get the total number of rows needed for the control, including the fixed caption row (if needed). When the value differs from RowCount, the Row and RowCount properties are updated.

AdjustRowCount is called from event handlers when values in Strings or TitleCaptions are changed, and when values are included in or excluded from DisplayOptions.

TCustomDrawGrid.Row Exchanges row values at the specified positions.

ColRowExchanged is a procedure used to exchange row values at the specified positions. ColRowExchanged extends the inherited method by applying the changes to the Strings property after adjusting the index positions for the number of FixedRows in the control. ColRowExchanged calls the inherited method using IsColumn, Index, and WithIndex as arguments.

TCustomDrawGrid.ColRowExchanged Indicates if the exchange applies to the column only or the entire row. First position to be swapped. Second position to be swapped. Performs actions needed when a row is deleted in the control.

ColRowDeleted is an overridden procedure used to perform actions needed when a Key-Value row is deleted in the control. ColRowDeleted ensures that EditorMode is set to False, and deletes the active row in the Strings property. ColRowDeleted calls the inherited method using IsColumn and Index as arguments.

TCustomDrawGrid.ColRowDeleted Indicates the action is for a column (and not a row). Ordinal position of the affected item. Not used in the current implementation. DefineCellsProperty has an empty implementation in TValueListEditor to prevent reading and writing the Cells property as defined in an ancestor class. TCustomStringGrid.DefineCellsProperty Component streamer for the class. Resets the last edited row number for the control.

InvalidateCachedRow is a procedure used to invalidate the internal member variable used to track the last row edited in the control. When Strings contains data, the internal tracker is set to -1. When Strings has no data (length is 0), the internal tracker defaults to the first visible non-fixed row. The editing buffers for both the key and value are cleared.

InvalidateCachedRow is called when the TValueListStrings instance in Strings performs Add, Delete, Insert, and Sort operations.

TValueListEditor.Strings TValueListStrings Gets the display priority for an auto-fill column.

GetAutoFillColumnInfo is used to get the minimum and maximum width, and relative display priority, for an automatically sized column in the grid. GetAutoFillColumnInfo overrides the behavior from the ancestor class to account for the two column limit for the grid.

Index is the column number examined in the method. When Index is 1 (the Value column), the relative priority is set to 1. When Index is 0 (the Key column), DisplayOptions is used to determine if the Key column is fixed. The priority is set to 0 when fixed, or 1 when DisplayOptions does not include the value doKeyColFixed.

Values in the aMin and aMax arguments are not used; they were used in an ancestor class, but are not required in TValueListEditor. TCustomGrid.GetAutoFillColumnInfo Column number examined in the method. Not used in TValueListEditor. Not used in TValueListEditor. Relative display priority for the column. Gets the value used in the editor for the specified cell.

GetEditText is a String function used to get the value used in the editor for the cell at the specified coordinates. The return value contains the content in Cells stored at the coordinates in ACol and ARow.

GetEditText signals the OnGetEditText event handler (when assigned) to allow a custom value to be provided to the cell editor.

Value for the cell editor. Column number. Row number. Gets the value in Cells at the specified row and column numbers.

GetCells is a String function used to get the value in the Cells property at the specified row and column numbers. GetCells extends the behavior from the ancestor class by using the Strings property as the source of data in the control.

When ACol contains 0 (the Key column), the Names property in Strings is used to get the value for the current row. When ACol contains 1 (the Value column), the ValueFromIndex method in Strings is used to get the value for the current row.

The return value is an empty string ('') when ARow is 0 (zero) and column titles are enabled in DisplayOptions. Use the TitleCaptions property to set the values displayed when DisplayOptions includes the value doColumnTitles.

TStrings.Names TStrings.ValueFromIndex Value for the cell at the specified row and column number. Column number to read in Cells. Row number to read in Cells. Gets the editor control for the specified column number.

GetDefaultEditor is a TWinControl function used to get the editor control for the specified column number. The return value is the TWinControl used as the editor for the cell in the specified column number.

GetDefaultEditor saves the current contents in Cells for the selected Row number to allow use of RestoreCurrentRow. GetDefaultEditor calls the inherited method to enable the logic implemented in the ancestor class.

KeyOptions is used to determine if the VK_Delete key needs to be be handled in the editor control. EditorOptions is updated to include or exclude the value EO_HOOKKEYDOWN based on the presence of KeyDelete in KeyOptions.

When Column contains 1 (the Value column), the item definition in ItemProps is used to configure the default editor. Its EditStyle is applied by calling the EditorByStyle method. For a PickList-style editor, pick list values in the item definition are assigned to the combo-box editor control and its drop-down row count is set to the value in DropDownRows. The OnGetPickList event handler is signalled (when assigned) to get user-defined values in the editor control. The read-only status for the editor is updated to reflect the value in the item definition.

When Column contains 0 (the Key column), the editor is marked as read-only when KeyOptions does not include the value KeyEdit.

TCustomGrid.EditorOptions Column number for the editor control. Editor control for the specified column number. Gets the value for the RowCount property. TCustomGrid.RowCount Row count for the grid control. Provides support for special keys used in the control.

KeyDown is a procedure used to provide support for special keys used in the control. KeyDown calls the inherited method. The KeyOptions property is used to determine if actions are performed for keystrokes, including:

KeyAdd (VK_INSERT): Inserts a row at the current position. by calling InsertRow. Key is set to #0.
KeyDelete (Ctrl + VK_DELETE): Deletes the row at the current position by calling DeleteRow. Key is set to #0.
(VK_ESCAPE): Restores the values for the current row by calling RestoreCurrentRow. Key is set to #0.

TValueListEditor.KeyOptions Key code for the key down event. Shift / Ctrl / Alt modifier for the key down event. Handles special key presses for the control.

KeyPress is an overridden method in TValueListEditor which handles key press events for special characters used in the control.

It calls the inherited method on entry to handle the character value in Key. If not handled in the ancestor class, it prevents the name/value separator used in Strings from being entered in the Name column for the control. If detected, Key is set to #0 and the focus is changed to the Value column and its editor is activated.

Key value examined in the method. Loads configuration and content from the specified XML configuration file. XML configuration file with values loaded in the method. Control version for the stored content. Resets grid columns to their default widths.

ResetDefaultColWidths is a procedure used to reset grid columns to their default widths. ResetDefaultColWidths uses values in the AutoFillColumns and DisplayOptions properties to determine the actions needed in the method. When AutoFillColumns is False, the inherited ResetDefaultColWidths method is called to set the default column widths.

Otherwise, DisplayOptions is used to determine if the Key column is displayed as a fixed column. When DisplayOptions contains the value doKeyColFixed, the Key column (column 0) is resized to fit the longest value in the Keys property and the control is redrawn.

No actions are performed in the method when AutoFillColumns is True and DisplayOptions does not include the value doKeyColFixed.

TCustomDrawGrid.AutoFillColumns Saves configuration and content in the control to the specified XML configuration file. XML configuration file where values are stored in the method. Sets the value in the Cells property at the specified position.

SetCells is an overridden procedure used to set the value in the Cells property at the specified row and column position. SetCells ensures that values written to the Cells property are also stored in the Strings property using the "Key=Value" convention used in the control. The new cell value in AValue is applied to either the Key or the Value based on the column number in ACol (0 is for Key, 1 is for Value).

Cells with a row number of 0 (zero) are used for fixed title captions when they are enabled in the DisplayOptions for the control. When DisplayOptions contains the value doColumnTitles, the inherited SetCells method is called to display the new title caption entered at run-time. Use TitleCaptions to set the text for column title captions at design-time.

Use Cells to read or write a value in the property.

TValueListEditor.Strings TValueListEditor.DisplayOptions TCustomStringGrid.Cells TCustomStringGrid.SetCells TCustomGrid.KeyPress Column number for the new cell value. Row number for the new cell value. New value for the cell. Sets the value for the ColCount property.

SetColCount is an overridden method in TValueListEditor used to set the value for the ColCount property. It raises an EGridException exception if the property is set to any value other than 2.

TCustomGrid.ColCount TCustomGrid.SetColCount New value for the ColCount property. Sets the cell value at the specified position.

SetEditText is an overridden procedure used to set the value for the cell at the specified column and row position. SetEditText calls the inherited method, and stores the string in AValue in the Cells property.

TCustomStringGrid.Cells TCustomStringGrid.SetEditText Column number for the new value. Row number for the new value. Value to store in the Cells for the control. Sets the value in the FixedRows property.

SetFixedRows is a procedure used to set the value in the FixedRows property. SetFixedRows is overridden in TValueListEditor to update the DisplayOptions for the control when the property value is changed.

AValue is the number of fixed rows to use for title captions in the control. No actions are performed in the method when AValue contains a value other than 0 or 1.

When AValue is 0, the value doColumnTitles is excluded from the DisplayOptions property. When AValue is 1, the value doColumnTitles is included in the DisplayOptions property.

Use TitleCaptions to set the title captions for columns at design-time. Use DisplayOptions to enable or disable title captions for the control.

TCustomDrawGrid.FixedRows New value for the property. Sets the value in the RowCount property.

SetRowCount is an overridden procedure used to set the value in the RowCount property. AValue contains the new value for the property.

AValue cannot contain a value smaller than the number of FixedRows for the grid control. An EGridException exception is raised when AValue is less than the number of FixedRows for the control.

SetRowCount uses the RowCount value inherited from the grid to determine if any actions are required in the method. No actions are performed in the method when the inherited RowCount contains the same value as AValue.

SetRowCount ensures that the Strings property contains the number of entries needed for the new property value minus the FixedRows for the grid. Lines are added to or deleted from Strings until the number of entries matches the needed value.

Raises an EGridException exception with the message in rsFixedRowsTooBig when the number of FixedRows is larger than the new value for the property. TCustomDrawGrid.FixedRows TCustomDrawGrid.RowCount EGridException New value for the property. Sorts the values in Strings.

Sort is a procedure used to sort the values in Strings. Sort disables an active editor in the control prior to sorting values when Options includes the value goAlwaysShowEditor. The active editor is restored when the sorting operation is completed.

Sort calls the inherited method using the values in Index, IndxFrom, and IndxTo as arguments. Please note that the ColSorting argument is not actually used in the sort operation; True is always used for column sorting.

TCustomGrid.Sort Not used n the current implementation. Event handler signalled when TitleCaptions is changed.

TitlesChanged is a procedure which provides a default implementation for the event handler signalled when values in TitleCaptions are changed. TitlesChanged calls ShowColumnTitles and AdjustRowCount methods, and calls Invalidate to force the control to be redrawn.

TitlesChanged is assigned to the OnChange event handler in TitleCaptions when the control is created.

Control triggering the event notification. Validates data entered in a cell in the control.

ValidateEntry is an overridden Boolean function used to validate data entered in a cell in the control. The return value is True if NewValue is acceptable for use in the cell at the specified coordinates.

ValidateEntry calls the inherited method, which signals the OnValidateEntry event handler (when assigned). ValidateEntry checks for duplicate names in the Key column when the value KeyUnique is included in the KeyOptions property.

The return value is False if a duplicate Key name is found in Strings. A dialog message is displayed with the message in rsVLEDuplicateKey, and the Editor re-selects the content in the control.

Column number for the new value. Row number for the new value. The old value for the cell. The new value for the cell. True if the cell value is valid. Constructor for the class instance.

Create is the constructor for the class instance. Create allocates resources for the Strings and TitleCaptions properties, and calls the inherited constructor. Create sets the event handlers in Strings and TitleCaptions to methods in the class instance. Create sets the default values for the following properties:

ColCount: 2
RowCount: 2
FixedCols: 0
Options: [ goFixedVertLine, goFixedHorzLine, goVertLine, goHorzLine, goColSizing, goEditing, goAlwaysShowEditor, goThumbTracking ]
Col: 1
DropDownRows: 8
AutoFillColumns: True

Create initializes the value for internal member used to track the last row edited in the control.

Owner of the control instance. Destructor for the class instance.

Destroy is the destructor for the class instance. Destroy frees resources allocated to the Strings and TitleCaptions properties, and calls the inherited Destroy method.

Removes the content in the control.

Clear is a procedure used to remove the content in the control. Clear calls the Clear method in Strings to remove all Key / Value information stored in the property. This action also frees the item definitions stored in an internal list in Strings.

Deletes the column or row at the specified position.

DeleteColRow is a procedure used to delete the column or row at the specified position.

IsColumn indicates whether the action is intended for a column or a row. Index is the ordinal position for the column or row removed in the method.

When IsColumn is True, the DeleteCol method is called. This results in an exception being raised in DeleteCol; columns cannot be removed in TValueListEditor. Otherwise, the DeleteRow method is called to remove the specified row number.

True when a column is affected in the method. Position of the row or column in the control. Deletes the row at the specified position.

DeleteRow is an overridden procedure used to delete the row at the specified position in the control. DeleteRow ensures that the row in Index is not a fixed row with title captions, and that Strings contains data. No actions are performed in the method when these conditions are not met.

DeleteRow calls the inherited method to remove the specified row number in the grid.

TCustomDrawGrid.FixedRows TCustomDrawGrid.DeleteRow Position of the row to be deleted. Prevents column deletion in control.

DeleteCol is an overridden procedure in TValueListEditor. Deleting a column is not a valid operation in TValueListEditor, and is overridden to block access to the inherited method.

DeleteCol raises an EGridException exception with the message in rsVLEInvalidRowColOperation.

Raises an EGridException exception with the message in rsVLEInvalidRowColOperation.

Position of the column to be deleted. Locates the row with the specified Key name.

FindRow is a Boolean function used to locate the row with the specified Key name.

aRow contains the relative row number where KeyName was located. The row number is relative to the fixed title caption row (when visible).The value in aRow is not updated if KeyName is not found in Strings.

The return value is True when KeyName exists in the Strings property.

TCustomDrawGrid.FixedRows TStrings.IndexOfName Key name to locate in the method. Relative row number for the specified key name. True when the key name exists in the control. Inserts a column or a row at the specified position.

InsertColRow is a procedure used to add a column or a row at the specified position in the control.

IsColumn indicates if a column is being inserted in the method. When IsColumn contains False, a row is inserted at the specified position. Index contains the row number where a blank item is inserted in Strings. Index is relative the number of FixedRows in the control; ie. when FixedRows = 1 and Index = 1, the item is inserted at position 0 in Strings. When FixedRows = 0 and Index = 1, the item is inserted at position 1 in Strings.

When IsColumn is True, an EGridException exception is raised with the message in rsVLEInvalidRowColOperation. Inserting a column is not a valid operation in TValueListEditor.

Raises an EGridException exception with the message in rsVLEInvalidRowColOperation when adding a column in the control.

TCustomDrawGrid.FixedRows False if the insert operation is for a row. Relative position for the inserted column. Inserts a row at the specified position.

InsertRow is an Integer function used to insert a row with the specified KeyName and Value at the current Row in the control.

Append indicates if the inserted row is added after the current Row in the control. When Append is False, the values in KeyName and Value are inserted at the current row. Row is updated to reflect the row number for the inserted values.

The return value contains the row number relative to the fixed title captions where the KeyName and Value were inserted.

Use InsertRowWithValues to insert a new row with the key and value passed in an array argument.

TCustomDrawGrid.FixedRows TCustomDrawGrid.Row TCustomStringGrid.Cells Key name to use in the new row. Value to use in the new row. True if a row is inserted after the current row. Relative row number for the inserted row. Inserts a row with the specified values at the specified position.

InsertRowWithValues is a procedure used to insert a row with the specified values at the specified row number in the control. Index contains the position in Strings where the new row is inserted.

Values is an array of Strings with the Key name and value for the inserted row. Values should contain two elements in the array. The first is the key name. The second is the item value. The second array element can be omitted, and defaults to an empty string (''). Additional elements present in the array are not used in the method.

InsertRowWithValues inserts the key name and value in Strings at the specified position using the "Key=Value" convention used in the control.

Use InsertRow to insert a new row using separate key and item value parameters.

Position for the inserted row. Array with the key name and value for the inserted row. Swaps the columns or rows at the specified positions.

ExchangeColRow is an overridden procedure used to swap the columns or rows at the specified positions in the control.

IsColumn indicates if the exchanged values are in a column or in a row in the control. The two-column layout in TValueListEditor prevents exchanging column values. When IsColumn is True, an EGridException exception is raised with the message in rsVLEInvalidRowColOperation.

When IsColumn is False, the inherited ExchangeColRow method is called using Index and WithIndex as arguments.

An EGridException exception is raised with the message in rsVLEInvalidRowColOperation when trying to exchange column values in the control.

False when exchanging row values. Position for one of the exchanged values. Position for one of the exchanged values. Indicates if the specified row is empty.

IsEmptyRow is an overloaded Boolean function used to determine the Key name and Value for a row contain empty string values (''). One variant omits the row number parameter, and assumes the current Row is used for the comparison. The other variant includes the row number parameter and performs the check for empty values.

The return value is True when Strings contains no entries, or when Cells for the specified row number have empty string values ('') in both columns.

TCustomDrawGrid.Row TCustomStringGrid.Cells Row number to examine in the method. True if the specified row has empty key name and value cells. Loads the content for the control from the comma-separated values in the specified stream. TStream instance with the values loaded in the method. Delimiter between cell values; default is Comma (','). Indicates whether title captions included as the first row in the CSV data. Initial line number in the stream loaded in the method. Indicates whether empty lines are ignored when loading the content for the control. Moves the specified column or row to the new position.

MoveColRow is a procedure used to move the specified column or row to the new position. IsColumn indicates if the positions are in a column or in a row in the control. The two-column layout in TValueListEditor prevents moving column values. When IsColumn is True, an EGridException exception is raised with the message in rsVLEInvalidRowColOperation.

When IsColumn is False, the values in Strings stored at the relative position in FromIndex are deleted. The values are re-inserted in Strings at the relative position in ToIndex.

True if the operation affects a column. Original position of the row or column. Target position for the row or column. Restores pre-editing values in the current row.

RestoreCurrentRow is a Boolean function used to restore the values for the current row to their state prior to editing in the control. If an editor has been assigned and has focus, it is hidden by calling EditorHide.

Values in the internal TKeyValuePair for the last row edited are restored in the Cells for the current Row. The EditorShow method is called to show the active editor after the row values are restored.

The return value is True if the pre-editing values were successfully restored in the current Row. The return is False if values were not edited, or an editor was not assigned and focused in the control.

True if the values were successfully restored in the current row. Sorts column values in the control.

Sort is an overloaded procedure used to sort column values in the grid control. The overloaded variants provide different parameters for the sort operation.

ACol is a TVleSortCol value that indicates whether key names or values are sorted in the method. When the variant with aACol is used, the SortColRow method is called to perform the sort.

Index contain the position for the column sorted in the method.

IndxFrom and IndxTo specify the starting and ending row numbers affected by the sort operation. When the variant with column and row indexes is used, the inherited Sort method is called to perform the sort.

Sort hides a visible cell editor during the sort operation. The cell editor is restored (when needed) prior to exiting from the method.

TCustomGrid.Sort TCustomDrawGrid.SortColRow Ordinal position of the column sorted in the method. Row with the initial value included in the sort. Row with the final value included in the sort. Column used for the sort operation. Indicates if changes have been made to items in the control.

Modified is a Boolean property which indicates if items in the control have been modified. The value in Modified is updated when the OnChange event handler for the Strings property is signalled.

Use the OnStringsChange event handler to perform actions needed when the property value has been changed. This event occurs after updating Modified and RowCount, and redrawing the control.

Use the OnStringsChanging event handler to perform actions needed prior to storing changes in the Strings property.

TCustomStringGrid.Modified Provides indexed access to Key names in the control.

Keys is an indexed String property which provides access to key names in the control.

Index specifies the ordinal row number in Cells used to read or write the value for the property. The column number in Cells is always 0 (the Key column).

Use Values to access the value for a specific Key name in the control.

Since version 2.2.0, Keys will no longer allow the name/value separator used in the Strings property to be used as a value in the property. TCustomStringGrid.Cells Row number for the Key name in the control. Provides indexed access to Values stored in the control.

Values is an indexed String property which provides access to values for Key names in the control.

Key is a String value with the key name to locate in the Strings for the control. The property value is read from and written to the Cells property in the Value column (1). If Key does not already exist during write access, a new Key/Value pair is added to Strings.

Use Keys to read or write key name values used for the items in the control.

TCustomStringGrid.Cells Key name for the specified value. Provides indexed access to item definitions in the control.

ItemProps is an indexed TItemProp property which provides access to item definitions used in the control. ItemProps provides access to the properties and methods used to define the editor for a Key-Value pair. These include the editor style, editing mask, maximum length, pick list values, and read-only status for the item.

AKeyOrIndex is a Variant value that specifies the key name (String) or the ordinal position (Integer) for the TItemProp instance in the property. Read and write access to instances in ItemProps is redirected to the TItemPropList member in the Strings property.

Key name or position for the item definition. The number of fixed columns on the control.

FixedCols is a published Integer property in TValueListEditor. It contains the fixed column count for the control. The default value for the property is 0, and causes both the Key and Value columns on the control to be displayed using the background color specified in Color (or ParentColor when enabled).

FixedCols can be changed to 1 to force the Key column to be displayed using the FixedColor and TitleStyle for the control. A value other than 0 or 1 assigned to the property is ignored. Fixed columns are normally displayed on the left edge of the grid and become part of the control which is not scrolled horizontally.

When set to 1, a cell in the Key column cannot be edited using a cell editor at run-time. A cell in the Key column cannot be edited if keyEdit has not been included in KeyOptions - even when FixedCols is set to 0. The cell value can be modified using the Keys property for all combinations of FixedCols and KeyOptions.

Setting a new value for the FixedCols property causes several actions to be performed:

The values in FixedCols and FixedRows are verified by calling CheckFixedCount, which can raise an exception if either value is not in range for the grid control.
EditorMode is set to False to hide a visible cell Editor on the control.
If Columns has been Enabled, UpdateSelectionRange is called to refresh the selection rectangle for the control. ColumnsChanged is called to apply the visual change to the control. If Columns has not been Enabled, MoveNextSelectable and UpdateSelectionRange are called to refresh the cells on the control.

Use FixedRows to get or set the number of fixed rows displayed for the grid control.

Use the Keys property to maintain a key name displayed in a specific row on the control. Use Values to maintain the value associated with a specific key name. Or, use Strings to access key / value pairs on the control.

TCustomDrawGrid.FixedCols TCustomDrawGrid.FixedRows TCustomGrid.FixedCols Uses the Color from the Parent control, when enabled.

ParentColor determines if the control should use the Color from the Parent control, when enabled. The default value for the property is False in TValueListEditor.

When this property is True, all changes to the Color of the parent will also be applied to the Color of the control, ensuring that they both contain same value. If the Color of the control is changed by the application, then ParentColor will be automatically set to False.

Using ParentColor when the Color value is clDefault can cause problems in resolving the actual color value. To obtain the Color property of a control while taking into account clDefault and ParentColor, use the GetColorResolvingParent method. This method might return a non-RGB color, but will never return clDefault. To obtain a purely RGB result use the GetRGBColorResolvingParent method.

TControl.ParentColor TControl.GetColorResolvingParent TControl.GetRGBColorResolvingParent Gets the number of rows for the control.

Read and write access specifiers for the RowCount property are re-implemented in TValueListEditor. They are redirected to the inherited property value, and additional validation is performed when setting a new value for the property. See SetRowCount.

TCustomDrawGrid.RowCount Deprecated. Use OnButtonClick instead. Enables or disables display features and behaviors in the control.

DisplayOptions is a TDisplayOptions property which enables or disables display features and behaviors in the control. DisplayOptions is a set type, and can store 0 (zero) or more TDisplayOption values. The default value for the property includes the following enumeration values:

doColumnTitles: Displays column titles
doAutoColResize: Automatically resizes column widths
doKeyColFixed: Displays the Key as a fixed caption column

Changing the value in DisplayOptions may cause updates to the RowCount and FixedRows properties; they are adjusted to reflect use of doColumnTitles in the property. In addition, the AutoFillColumns property is updated to reflect use of doAutoColResize in the property.

The value in DisplayOptions is updated when the value in FixedRows is changed.

TCustomDrawGrid.FixedRows TCustomDrawGrid.AutoFillColumns Number of rows displayed for an item with a PickList editor style.

DropDownRows is an Integer property with the number of rows displayed for an item with a PickList editor style. The default value for the property is 8.

DropDownRows is used in the GetDefaultEditor method to configure the TComboBox control used for the editor style.

Use the indexed ItemProps property to maintain an item definition used in the grid control.

Controls actions that can be performed for Keys in the control.

KeyOptions is a TKeyOptions property used to control actions that can be performed for keys in the control. KeyOptions is a set type, and can contain 0 (zero) or more values from the TKeyOption enumeration. The default value for the property is an empty set ([]).

Settings the values in KeyOptions causes the internal UpdatingKeyOptions flag to be set. Including the value KeyAdd in KeyOptions requires KeyEdit to be added as well. The Options property may also be updated to include or exclude the value goAutoAddRows based on use of KeyAdd in the property. The internal UpdatingKeyOptions flag is cleared prior to exiting from the method.

Values in KeyOptions are used in the GetDefaultEditor method to configure the cell editor for an item.

Specifies the options enabled for the Key-Value grid.

Options is a TGridOptions property used to specify the options enabled for the two-column grid displayed in the control. Options is a set type that can contain 0 (zero) or more TGridOption values. By default, the property includes the following enumeration values:

goFixedVertLine
goFixedHorzLine
goVertLine
goHorzLine
goColSizing
goEditing
goAlwaysShowEditor
goThumbTracking

See TGridOption for more information about values and meanings in the enumeration.

Changing the value in Options causes additional validation to be performed:

goColMoving is always excluded from the property value; column moving is not a valid operation in TValueListEditor.
goAutoAddRowsSkipContentCheck is also excluded from the property.
If the internal UpdatingKeyOptions flag has not been set, and component streaming has completed, the KeyOptions property is updated to include goAutoAddRows.

TGridOption TGridOptions Stores the keys, values, and item definitions in the control.

Strings is a TValueListStrings property which provides storage for the Keys, Values, and item definitions in the control. Strings uses the "Key=Value" convention to store the string data needed for the Keys and Values properties.

Use the Keys property to read and write key names by their ordinal position in the control. Use Values to read or write the data stored for a specific Key name.

Strings also contains an internal TItemPropList member used to store the item definitions for the control. Use ItemProps to maintain the item definitions in the control.

Title captions used for columns in the control.

TitleCaptions is a TStrings property with the title captions used for columns in the control. TitleCaptions should have 2 lines with the titles used for the Key and Value columns in the grid.

When TitleCaptions is empty (0 lines), the values in rsVLEKey and rsVLEValue are used as the captions for the respective columns. If a line is omitted in TitleCaptions, the corresponding resource string is used as the default value for the caption.

TitleCaptions is used in the ShowColumnTitles method to assign and display the column titles. Values in TitleCaptions are updated when LoadContent or LoadFromCSVStream is called. Changing values in TitleCaptions causes the control to be redrawn.

Event handler signalled to load values for the PickList in an item.

OnGetPickList is a TGetPickListEvent property with the event handler signalled to load the PickList for the item with a specific key name. OnGetPickList allows the application to provide custom selectable values for an item which uses the esPickList editor style.

OnGetPickList is signalled from the GetDefaultEditor method when an item definition in ItemProps uses esPickList in its EditStyle property.

An application must implement and assign a routine to the event handler to respond to the notification. The arguments for the event handler include the control instance, the key name for the item, and a TStrings instance where the values for the pick list can be stored. Existing values in the pick list can be modified or replaced entirely.

Event handler signalled when values in the Strings property are changed.

OnStringsChange is a TNotifyEvent property with the event handler signalled when values in the Strings property are changed. Applications can assign a procedure to the event handler to perform actions needed in the control.

OnStringsChange is triggered in the StringsChange method after updating the row count and redrawing the control.

Use OnStringsChanging to perform actions needed prior to setting values in Strings.

Event handler signalled prior to updating the Strings property.

OnStringsChanging is a TNotifyEvent property with the event handler signalled prior to updating values in the Strings property. Applications can assign a procedure to the event handler to respond to the event notification.

OnStringsChanging is triggered in the StringsChanging method.

Use OnStringsChange to perform actions needed after values are updated in Strings.

Not used in the current implementation.

OnValidate is a TOnValidateEvent property that implements the event handler signalled to validate a modified value in the grid. Not used in the current implementation.

TCustomGrid.OnValidateEntry TCustomGrid.ValidateEntry Message displayed when a duplicate Key name is found. Default caption for the Key column; value is 'Key' Default caption for the Value column; value is 'Value' Exception message for an invalid row or column operation. Error message displayed when a row count is not found when loading content in TValueListEditor. Error message displayed when an invalid row number is found when loading content in TValueListEditor. Error message displayed when an invalid column number is found when loading content in TValueListEditor. Error message displayed when an invalid column count is found when loading content in TValueListEditor; column count is always 2 in TValueListEditor. Register components for use in the Lazarus IDE.

Register is the procedure used to register components for use in the Lazarus IDE. Register adds the following components to the Lazarus IDE component palette:

Additional Tab

TValueListEditor