Data-aware controls commonly used for viewing and operating on information held in databases.

dbctrls.pp contains data-aware controls used to access, view, edit, and navigate databases in the Lazarus Component Library (LCL).

The following components are added to the Data Controls tab in the Lazarus IDE Component Palette:

TDBNavigator
TDBText
TDBEdit
TDBMemo
TDBImage
TDBListBox
TDBLookupListBox
TDBComboBox
TDBLookupComboBox
TDBCheckBox
TDBRadioGroup
TDBCalendar
TDBGroupBox

DefaultFieldClasses (defined in the FPC FCL) are registered as database field classes in the IDE. The TIntegerField type (also defined in the FPC FCL) is registered as a database field class, and is aliased to the TLongintField type. For more information about database field classes, see DefaultFieldClasses and TIntegerField.

Maintains an association between a control, an action, and a field in a linked dataset.

TFieldDataLink is a TDataLink descendant which maintains an association between a control, an action, and a field in a linked dataset. TFieldDataLink extends the ancestor class to provide additional properties, methods, and events useful when working with a data-aware control linked to a field in a dataset.

The following key properties are added in the class:

Control
FieldName
Field

The following events are added in the class:

OnDataChange
OnUpdateData
OnEditingDone
OnActiveChange

TFieldDataLink is used in the implementation of several data-aware controls. In most cases, it is used in an internal member and not exposed in the interface for the control. It can, however, be used as a public or published property.

TDataLink Indicates if the Field for the data link can be modified. True when Field is assigned and its CanModify method is also True. Indicates if the specified field is present in the KeyFields for the data link. True when the name for the field is present in KeyFields. Field definition to locate in the KeyFields for the data link. Gets the value for the CanModify property. Value for the property. Sets the value for the FieldName property. Value for the property. Retrieves the value for the Field property from the linked dataset. Checks for FieldName in the linked Dataset, and updates the value in Field. Resets the EditingSource and EditingSourceSet Boolean flags. ActiveChanged - method to process changes in the Active property.

ActiveChanged - method to process changes in the Active property.

Any change to the Active property triggers the ActiveChanged method.

If the method is triggered by a transition into an Active state, then ActiveChanged ensures that this TFieldDataLink's Field is still valid before calling the event handler.

ActiveChanged calls the OnActiveChange event handler if one has been assigned.

TDataLink.DataSource EditingChanged - method for processing changes in the Editing property.

EditingChanged is an overridden method which re-implements the virtual method defined in TDataLink. EditingChanged ensures that the Editing property is updated to reflect actual state for the Field in the linked dataset. If the real editing state does not match the value in the Editing property, internal flags are reset to reflect the new editing state and the OnEditingChange event handler is signalled (when assigned).

EditingChanged is used in the implementation of the LayoutChanged method. It is also called when the value in the FieldName or Active property is changed.

LayoutChanged- called if layout is changed: tests validity of field then calls OnLayoutChange event handler.

LayoutChanged is an overridden procedure called when the field binding in the linked dataset for a data-aware Control has been changed. LayoutChanged calls the ValidateField method to ensure that the Field is valid / up-to-date, or set to Nil when the FieldName does not exist in the linked dataset. If the Field is assigned (not Nil), the EditingChanged and RecordChanged methods are called.

Please note: LayoutChanged does not call the inherited method.

LayoutChanged is used primarily in the implementation of methods in TCustomDBGrid and descendent classes.

TCustomDBGrid RecordChanged - triggered if the contents of the current record change; calls Reset.

RecordChanged is an overridden procedure called when the current record in the linked dataset has been changed.

AField contains the TField definition with the value that has changed in the current record. It may contain Nil when more than one field has been changed in the current record for the linked dataset.

RecordChanged calls the Reset method when any of the following are true:

AField is unassigned (contains Nil)
AField has the same value as the Field property
Field is an assigned key field which uses the fkLookup field kind

Applications should not call this method; it is executed when values are stored by data-aware controls which use the field data link.

Field definition with the value updated in the current record. Signals the OnUpdateData event handler for pending changes to the linked dataset.

UpdateData is an overridden procedure used to post pending updates from a data-aware control to the linked dataset. UpdateData uses the value in the internal IsModified flag to determine if additional actions are required in the method. No actions are performed when the internal IsModified flag has not been set.

UpdateData signals the OnUpdateData event handler when it has been assigned for the class instance. This event handler normally contains a reference to the UpdateData method defined for the associated data-aware Control, such as TCustomDBGrid.UpdateData and TDBEdit.UpdateData.

Please note: UpdateData does not call the inherited method in the ancestor class. FocusControl gives the input focus to the data-aware control in the class instance.

FocusControl is an overridden procedure used to give input focus to the data-aware Control for the class instance.

AField is a reference to the TField which defines the field for the data-aware control. AField must be assigned, and point to the Field used in the class instance. No actions are performed in the method if either condition is not met.

FocusControl can be used for any Control descended from TWinControl where its CanFocus value is True; the SetFocus method in the Control is called to receive the input focus.

TWinControl.CanFocus TWinControl.SetFocus Reference to the field expected for the focused control. Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry to the method. Create sets the value in the VisualControl property to True.

TDataLink.Create Edit - if the field can be modified, performs inherited Edit and shows editing status.

Edit is a Boolean function used to ensure that the field in the linked dataset can be modified. The return value is True when the DataSource is already in an edit state, or if it is successfully changed to an edit state. The return value is False if a dataset is not available, or not in a valid edit state.

Edit calls the inherited method when CanModify is True and the dataset is not already in an edit state. This causes the DataSource to call its Edit method.

TDataLink.DataSource TDataLink.Edit TDataSource.Edit True if the linked dataset is in an edit state. Updates the class when the linked dataset enters an edit state.

Modified is a procedure which updates the class when the linked dataset is placed in an edit state. Modified sets the value in the internal IsModified member to True to track the state change independent of the real state for the linked dataset.

The EditingChanged, UpdateData, and Reset methods reverse the action performed in Modified.

Modified is used in the implementation of methods in data-aware controls, and generally occurs just prior to calling the Change method to signal an update to the value for the control.

Reset - checks that link is active, calls the OnDataChange event handler then sets IsModified to False.

Reset is a procedure used to cancel pending changes in the Control value before they are written to the Field in the linked dataset. Reset signals the OnDataChange event handler (when assigned), but does not store pending changes to the current record in the linked dataset.

The internal IsModified flag is reset in the method, as are flags which track the editing state for the source of the control value. Call the OnDataChange event handler to affect the internal IsModified flag only.

Reset is used in the implementation of methods in data-aware controls which process, apply, or cancel changes to the control value.

The Control to which this datalink is attached.

Controls is a TComponent property which contains the control which provides editing facilities for the value in the linked dataset. The value in control is generally assigned when a data-aware control is created and its data link is configured.

The value in Control is used in the implementation of the FocusControl method to give input focus to the control.

Use the FieldName property to access the name of the field in the linked dataset.

Use the DataSource property to access the component which provides access to the linked DataSet with the Field value.

TDataLink.DataSource TDataLink.DataSet The Field to which the datalink is attached.

Field is a read-only TField property which contains the field definition in the linked DataSet for the database column represented by the FieldName property. Field provides access to the metadata for the database column, such as: field type, size, display values, lookup settings and content, editing mask, et. al.

The value in Field is assigned in the private UpdateField method when the value for the FieldName property is changed. Its value is also accessible to the data-aware Control using the TFieldDataLink instance.

The DataSource and DataSet properties contain the source with the fields and values for the class instance.

TDataLink.DataSource TDataLink.DataSet FieldName - the name of the attached field, stored as a string.

FieldName is a String property which contains the name of the field in the linked Dataset with the value for a data-aware Control. Changing the value for the property causes Field to be updated to reflect the new value. If the data link is marked as Active, the EditingChanged and Reset methods are called to trigger event handlers in the class instance.

Use the DataSource property to assign the component with the linked DataSet which contains the specified FieldName.

TDataLink.DataSource TDataLink.DataSet TDataLink.Active CanModify - True if the linked field is capable of being modified.

CanModify is a read-only Boolean property which indicates if the field in the linked DataSet can be modified. The property value is determined by examining the Field definition in the DataSet.

If Field has not been assigned by setting the FieldName property, the property value is False. If the Field is a lookup field type, the value is True when its list fields can be modified. Otherwise, the value in the CanModify property for the Field and the ReadOnly property in the data link determine the property value.

CanModify is used in the implementation of the EditingChanged and Edit methods.

TDataLink.DataSet TDataLink.DataSource TDataLink.ReadOnly Editing - True if the linked field is being edited.

Editing is a read-only Boolean property which indicates if values in the class instance have been updated in its methods. It is used in methods for data-aware controls, and determines whether a control uses the data link to commit or discard value changes in the control.

The value in Editing is updated following changes to the DataSource, FieldName, Field, ReadOnly, or Active properties.

TDataLink.DataSource TDataLink.Active TDataLink.ReadOnly Indicates if the data link is changing its source properties.

EditingSource is a read-only Boolean property which indicates if the data link is changing the source properties for the class instance. The source properties include DataSource, FieldName, and Field.

The value in EditingSource is updated when the Edit or EditingChanged methods are called. It is used to prevent multiple calls to the Edit method.

TDataLink.DataSource TDataLink.DataSet OnDataChange - event handler for a change in the data.

OnDataChange is a TNotifyEvent property which contains the event handler signalled when the DataSource or Field has been changed in the class instance. OnDataChange is normally signalled from the DataChange method in a data-aware control which has been assigned to the event handler when the control was initialized. It is also signalled from the Reset method which cancels field updates for the control.

See OnUpdateData for the event handler signalled when pending edits are written to the linked DataSet. See EditingChanged for the event handler signalled for pending changes to the DataSource, Field, or FieldName properties.

TDataLink.DataSet TDataLink.DataSource TNotifyEvent OnEditingChange - event handler for a changed in the Editing property.

OnEditingChange is a TNotifyEvent property which contains the event handler signalled when the value in the Editing property has been changed. OnEditingChange is signalled from the EditingChanged method (when assigned) after Editing has been updated to reflect the current edit state.

OnUpdateData - event handler for updating any pending changes in the data.

OnUpdateData is a TNotifyEvent property which contains the event handler signalled for changes to the data in the control.

OnUpdateData is signalled from the UpdateData method, and normally contains a reference to the UpdateData method in the data-aware control which contains the class instance. The method in the data-aware control is responsible for performing any actions needed before the field value is written to its dataset. This can include validation of the field value, and potentially raising an exception for an invalid field value.

OnActiveChange - event handler for a change in the Active property.

OnActiveChange is a TNotifyEvent property which contains the event handler signalled when the value for the Active property has been changed. OnActiveChange is signalled from the ActiveChanged method, and occurs after the Field property has been updated and the OnDataChange event handler has been executed.

Applications can implement and assign an object procedure to the property to allow responding the event notification.

TDataLink.Active TNotifyEvent TDBLookup - used as source of data by TDBLookupListBox or TDBLookupComboBox, to find data from a lookup table.

TDBLookup component is typically owned by a Lookup control like TDBLookupListBox or TDBLookupComboBox.

The ListSource is the TDataSource for the other Dataset from which lookup values are retrieved.

The KeyField is the lookup key in ListSource which corresponds to the DataField value.

The ListField is the name of the field in ListSource to list into the Items property of the lookup control.

Use EmptyValue to specify a KeyField value automatically added to the ControlItems property when the linked lookup dataset contains no records. No entry is added to Controlitems when the value in EmptyValue is an empty string (''). The value in DisplayEmpty is used for the ListField displayed in the control.

The EmptyValue and DisplayEmpty properties were added in revision 62844, and released in LCL version 2.0.8 and higher. Performs the notification message received for a component in the class instance.

Notification is an overridden method in TDBLookup. It calls the inherited method, and ensures that the ListSource property is set to Nil when the component is being removed.

TComponent.Notification Component for the notification. Operation for the notification. Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor. Create allocates resources needed for internal members in the class instance, and sets the default values for the DisplayEmpty and EmptyValue properties (both are set to an empty string).

TComponent.Create Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy ensures that resources allocated to internal members in the class instance are freed, and calls the inherited destructor prior to exiting from the method.

TComponent.Destroy Initialize makes links between local Fields and the appropriate fields in the remote data source, then fetches the lookup data.

Initialize is called when the value in the Active property for the list dataset is changed to True. No actions are performed in the method if it has already been called, but has not yet finished.

When ScrollListDataset is True, the linked datasets for the control and its lookup list are synchronized. The lookup dataset is positioned to the record with the values in the key fields. When ScrollListDataset is set to False, the datasets are not synchronized.

Link to the dataset with the keys and display values for the control. Contains the keys and display values for the lookup control. Gets the value(s) for one or more key fields defined for the Field in the linked dataset.

KeyFieldValue is a Variant function used to get one or more values for fields which make up the index key for the linked dataset in the control. KeyFieldValue uses the internal TFieldDataLink instance in the class to get the return value for the method. The return value contains the content from the FieldValues property for the linked DataSet.

The return value is Null under the following conditions:

The internal data link has not been assigned
The Dataset in the data link is not Active
The Field in the data link does not have defined key field names

KeyFieldValue is useful for getting the index value for the current record in the linked dataset. It is not, however, used in the implementation of the class or descendants.

TDataLink.DataSet TDataSet.FieldValues Variant value for the key fields in the field definition for the control. Signals the OnUpdateData event handler for pending changes to the linked dataset.

UpdateData is a procedure used to post pending updates from a data-aware control to the specified key field in the linked dataset. ValueIndex contains the ordinal position in the list of key fields for the value updated in the method. No actions are performed in the method when ValueIndex is not a valid position for the list of key fields.

UpdateData uses the value in ScrollListDataset to determine whether the lookup dataset is moved to the new key value. When ScrollListDataset contains True, the linked lookup dataset calls its Locate method to find the record with the key value in its index fields. The lookup dataset is not moved when ScrollListDataset contains False.

The internal TFieldDataLink is used to access the linked dataset where the value for the control is stored. It has not been assigned, is not Active, or already contains the new key value, no additional actions are performed in the method. Otherwise, the new key value is stored in the field for the index key field.

TDataLink.DataSet TDataLink.Active Ordinal position in the key fields located in the method. Gets the value for the key field at the specified ordinal position in the list of values from the lookup dataset.

GetKeyValue is a Variant function used to get a values from an index key field in the linked lookup dataset.

ValueIndex contains the ordinal position in the list of fields defined as key fields in the Field for the linked dataset. When ValueIndex contains a valid position for the list of fields names, the corresponding field value from the lookup dataset is returned. Otherwise, the Null value is used as the the return value for the method.

GetKeyField is called from methods in controls which use TDBLookup in their implementation, such as TDBLookupListBox and TDBLookupComboBox.

TDataSet.Fields TField.KeyFields TField.LookupKeyFields Value for the Key field retrieved from the lookup dataset. Ordinal position in the list of key values from the lookup dataset. Gets the ordinal position in the list for the specified key value. Ordinal position for the specified key value. Key value to locate in the method. Contains the items displayed for the lookup control.

ControlItems is a TStrings property used to store the display values for items in the lookup control. Values in ControlItems are passed as an argument to the Initialize method called when the value in Active is changed. It is updated when values are retrieved from a linked lookup dataset using the ListField defined for the control. ControlItems is cleared if the linked lookup dataset does not contain any records; an empty value is added to the property when EmptyValue and DisplayEmpty have been assigned in the control.

Indicates if look-up information is cached in the field data link for the control.

Used in classes with TDBLookup in their implementation, like TDBLookupComboBox and TDBLookupListBox.

The name of the KeyField used in the lookup search. ListField - the name of the list field displayed for the lookup. ListFieldIndex - the index value of the list field. ListSource - the data source that contains the lookup list. Keyboard shortcut which causes an empty value to be assigned to each of the key fields defined for the lookup control. Indicates if the Dataset in ListSource can be scrolled when loading/locating key and display values.

ScrollListDataset is a Boolean property which indicates if the linked lookup dataset can be scrolled when loading values from the fields identified in KeyField and ListField. The value in ScrollListDataset is used in the implementation of the Initialize and UpdateData methods.

Value stored for the lookup control when a lookup value is not available.

EmptyValue is a String property which contains the value stored in the list of key values when no records are available in the linked lookup dataset, or when the NullValueKey shortcut is pressed.

Use EmptyValue to specify a KeyField value automatically added to the ControlItems property when the linked lookup dataset contains no records. No entry is added to Controlitems when the value in EmptyValue is an empty string (''). The value in DisplayEmpty is used for the ListField displayed in the control.

Use DisplayEmpty to specify the value displayed in the lookup control when no records are available in the linked lookup dataset, or when the NullValueKey shortcut is pressed.

The EmptyValue and DisplayEmpty properties were added in revision 62844, and released in LCL version 2.0.8 and higher. Value displayed in the lookup control when a lookup value is not available.

DisplayEmpty is a String property which contains the value displayed in the lookup when no records are available in the linked lookup dataset, or when the NullValueKey shortcut is pressed.

Use EmptyValue to specify the value stored in the lookup when no records are available in the linked lookup dataset, or when the NullValueKey shortcut is pressed.

The EmptyValue and DisplayEmpty properties were added in revision 62844, and released in LCL version 2.0.8 and higher. TDBEdit - a data-aware edit box for processing a single text-string from a dataset.

TDBEdit is a TCustomMaskEdit descendant which implements a data-aware control which allows editing of the value in a database field. Like its ancestor class, TDBEdit displays and edits a single line of text. For multi-line text values, use the TDBMemo control.

TDBEdit extends the ancestor class with additional properties needed to configure the data-aware features in the control, including:

DataSource: Component which provides access to the dataset with the field value
DataField: Name of the field in the dataset edited in the control
Field: Field definition and metadata in the dataset
ReadOnly: Indicates if the value for the control (and its field) cannot be changed

An internal TFieldDataLink class instance is used to maintain an association between the control and its data source. TDBEdit provides methods which support use of TBasicAction with the data link for the control.

TDBEdit extends the masking capabilities from the ancestor to include use of mask-related properties like EditMask and Alignment set in the TField instance for the control. Use the CustomEditMask property to enable an edit mask independent of the value defined in the dataset Field.

How To Use Data-aware Controls Performs actions needed when values in the dataset have been changed. DataChange implements the OnDataChange event handler used in the internal TFieldDataLink instance. Object for the event notification. Performs actions needed to validate the edit control, and update the field in the linked dataset.

UpdateData is assigned to the OnUpdateData event handler in the internal TFieldDataLink instance used in the control.

Object for the event notification. Gets the value for the DataField property. Value for the property. Gets the value for the DataSource property. Value for the property. Gets the value for the Field property. Value for the property. Sets the value for the DataField property. New value for the property. Sets the value for the DataSource property. Calls the ChangeDataSource routine to perform free notifications and update the TFieldDataLink used in the class instance. New value for the property. Implements the CM_GETDATALINK control message. Message examined and updated in the method. Gets the value for the ReadOnly property.

GetReadOnly is a Boolean function used to get the value for the ReadOnly property. Read access for the property value redirected to the ReadOnly property in the internal TFieldDataLink instance used in the class.

TCustomEdit.GetReadOnly TDataLink.ReadOnly Value for the property. Sets the value for the ReadOnly property.

SetReadOnly is a procedure used to set the value for the ReadOnly property. SetReadOnly calls the inherited method. Write access for the property value is redirected to the ReadOnly property in the internal TFieldDataLink instance used in the class.

TDataLink.ReadOnly TCustomEdit.SetReadOnly New value for the property. Handles key down events in the control.

KeyDown is an overridden method in TDBEdit. KeyDown calls the inherited method, and ensures that the specified virtual key code and modifier are applied in the manner needed for the data-aware control. KeyDown handles the following virtual key codes:

VK_ESCAPE: Cancels an active edit and resets the state for the DataSource. Calls the Reset method in the internal TFieldDataLink, and re-selects the content in the control. Sets Key to the value VK_UNKNOWN.
VK_DELETE or VK_BACK: Sets the value in Key to VK_UNKNOWN when the control is used on a field that cannot be edited.
VK_RETURN: Calls the UpdateRecord method in the internal TFieldDataLink instance when it is in an edit state.

TDataLink.DataSource TDataLink.UpdateRecord TWinControl.KeyDown Virtual key code examined and applied in the method. Key modifier examined and applied in the method. Handles UTF-8 characters for the data-aware control.

UTF8KeyPress is an overridden method in TDBEdit. UTF8KeyPress calls the inherited method, and performs actions needed to handle the UTF-8-encoded character specified in the UTF8Key argument.

UTF8KeyPress checks the value in UTF8Key to determine the number of bytes required for the code point. A single-byte code point is converted to a Char type, and passed to the FieldCanAcceptKey routine to validate its content for the Field in the control. Multi-byte Unicode code points are ignored, and the Extended ASCII NbSp character (Decimal 255) is passed to FieldCanAcceptKey. The value in UTF8Key is set to an empty string if it is valid for the Field.

Use the OnUTF8KeyPress event handler to handle/convert specific multi-byte character values.

TCustomMaskEdit.UTF8KeyPress TCustomMaskEdit.HandleKeyPress TWinControl.UTF8KeyPress TWinControl.OnUTF8KeyPress TField.IsValidChar UTF-8 character examined in the method. Handles notifications when a component is added or removed from the control. Notification is overridden in TDBEdit to ensure that the DataSource for the data link in the control is set to Nil when the component is freed. Notification calls the inherited method. TDataLink.DataSource TComponent.Notification Component for the notification. Operation for the notification. Indicates if the control can modify the text for the control value.

EditCanModify is an overridden Boolean function in TDBEdit. The return value contains the value for the CanModify property in the TFieldDataLink instance in the control.

Please note: EditCanModify does NOT call the inherited method which always returns True. In addition, it is provided to maintain Delphi code compatibility; it is not referenced directly by any methods in the implementation of the control or its descendants. TCustomMaskEdit.EditCanModify True when the control can modify the value for the field in the linked dataset. Performs actions needed when the value for the control has been changed.

Change is an overridden procedure in TDBEdit used to ensure that the internal TFieldDataLink instance for the control is notified when the value for the control has been modified. Change calls the Modified method in TFieldDataLink to perform the notification, and calls the inherited Change method.

TCustomMaskEdit.Change TDataLink.UpdateRecord Cancels pending changes to the linked dataset.

Reset is an overridden method in TDBEdit which ensures that the internal TFieldDataLink instance in the control is reset when pending changes to the control value are cancelled. Reset calls the Reset method in TFieldDataLink to perform the notification, signal its OnDataChange event handler, and to reset the state for its DataSource. Reset calls the inherited method prior to exit.

TCustomMaskEdit.Reset TDataLink.DataSource Ensures that the control has the input focus.

WMSetFocus is an overridden method in TDBEdit. WMSetFocus ensures that the text for the control is updated before calling the inherited method. This includes applying an edit mask assigned to the control when it has input focus.

TCustomEdit.WMSetFocus Window message handled for the control. Ensures that the liked dataset is updated when the modified control loses input focus. TCustomEdit.WMKillFocus Window message handled for the control. Handles the specified LCL message for the control.

WndProc is an overridden method in TDBEdit. It is used to process the specified LCL message for the control. WndProc ensures that the message is applied to the linked dataset when it can be modified, and handles the following LCL messages:

LM_CLEAR
LM_CUT
LM_PASTE

The Edit and Modified methods in the internal TFieldDataLink instance are called, and the DataChange method is called to post changes for the control. No actions are performed on the dataset when it cannot be modified, but the result value in Message is set to 1 to prevent calling the default procedure for the window.

WndProc calls the inherited method prior to exit.

TLMessage LM_CLEAR LM_CUT LM_PASTE TCustomEdit.WndProc LCL message examined and applied in the method. Constructor for the class instance.

Create is the overridden constructor for the class instance. Create calls the inherited constructor, then creates and configures the internal TFieldDataLink instance used in the control. The DataChange and UpdateData methods are assigned to the OnDataChange and OnUpdateData event handlers in the TFieldDataLink instance.

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

Destroy is the overridden destructor for the class instance. Destroy ensures that resources allocated to members in the class instance are freed prior to destruction of the class instance. Destroy calls the inherited destructor prior to exit.

TCustomEdit.Destroy Provides support for TBasicAction in the control.

ExecuteAction is an overridden method in TDBEdit. It calls the inherited method, and when the action is not handled in the ancestor, executes AAction using the ExecuteAction method in the internal TFieldDataLink instance in the class.

The return value is True if the action was executed in the method.

TComponent.ExecuteAction TBasicAction True if the action was executed in the method. Action examined and executed in the method. Updates the specified action to reflect the current state in the linked dataset.

UpdateAction is an overridden Boolean function in TDBEdit. UpdateAction is called when the Application enters an idle state to ensure that the action reflects the current state for a linked dataset.

AAction is the TBasicAction updated in the method.

UpdateAction calls the inherited method, and when the internal dataset link has been assigned, executes its UpdateAction method. The return value is True when AAction is updated using either the inherited method, or the method in the linked dataset. The return value is False when AAction could not be updated in the method.

TDataLink.UpdateAction TComponent.UpdateAction TBasicAction True if the action was updated in the method. Action examined and updated in the method. Provides access to the field definition for the data-aware control.

Field is a read-only TField property which provides access to the field definition to which the data-aware control is linked. Read access for the property is redirected to the Field property in the internal TFieldDataLink class instance. The value in Field is updated when a new value is assigned to the Field in the TFieldDataLink instance.

Use DataField to read or write the field name used for the data-aware control. Use DataSource to specify the data source with the dataset containing the specified field name.

TField Indicates if a custom edit mask is used in the control.

CustomEditMask is a Boolean property which indicates if an edit mask other than the one defined for the Field in the linked dataset is used in the control.

When set to True, the features from the ancestor class are used to provide the editing mask. Set the value in the EditMask property when CustomEditMask is set to True.

When set to False, the EditMask defined in the internal TFieldDataLink instance (and loaded from the database field definition) is used in the control.

TCustomMaskEdit.EditMask Contains the name of the field with the value for the control.

DataField is a String property which contains the name for the field in the linked dataset where the value for the control is read and written. Read and write access to the property value are redirected to the FieldName property in the internal TFieldDataLink instance for the control. Changing the value in DataField causes the value in Field to be updated.

Set the value in DataSource to the component which provides access to the dataset for the data-aware control.

TDataLink.DataSource TDataLink.DataSet Provides access to the dataset with content for the control.

DataSource is a TDataSource property which provides access to the content for the data-aware control. DataSource is used in conjunction with the Field property to determine the dataset and field definition used when reading the value for the control.

Read and write access to the property value is redirected to the DataSource property in the internal TFieldDataLink instance used in the control. Assigning a new value to the property causes the ChangeDataSource routine to be called to apply the value to the internal TFieldDataLink instance.

Use the DataField property to specify the field name accessed in the linked dataset.

TDataSource TDataLink.DataSource Indicates if the control cannot modify the field in the linked dataset.

ReadOnly is a Boolean property which indicates if the control cannot modify its DataField in the linked dataset. When set to True, the underlying field value cannot be modified using the control.

Read and write access for the property value are redirected to the ReadOnly property in the TFieldDataLink instance used in the control.

Please note: A value assigned to ReadOnly may be overridden by the Field definition from the target database table. TCustomEdit.ReadOnly TDataLink.ReadOnly TDataLink.DataSource TDataLink.DataSet Event handler signalled when a key is down while control has focus.

OnKeyDown differs from the method in TWinControl in that the key may have already been down when the control received focus; with OnKeyPress the key needs to become pressed while the control has focus.

TWinControl.OnKeyDown Event handler signalled when a key is being pressed while the control has focus.

OnKeyPress differs from the method in TWInControl in that the key needs to become pressed while the control has focus; with OnKeyDown the key may have already been down when the control received focus.

TWinControl.OnKeyPress Event handler signalled when a key becomes up (not pressed) while the control has focus.

OnKeyUpis an event handler signalled when a key is up (not pressed) while the control has focus. The key may already have been up when the control received focus, or a pressed key may become released during the time the control has focus.

TWinControl.OnKeyUp Displays a string value stored in a dataset field.

TDBText is a TCustomLabel descendant which implements a component to display the text content in a dataset field in the manner used for a label control. The stored field value is not editable in the control - just like a label component.

Use the Field property to access the field definition used to provide the value for the control.

TField How To Use Data-aware Controls Updates the control display value when the linked dataset is changed.

DataChange is used to perform actions needed when the linked dataset for the control has been changed. In TDBText, this requires setting the Caption property for the control. DataChange uses the Field property (when assigned) to get the display text for the field. At design--time, the Name property is used when Field is unassigned. At run-time, an empty string ( '') is used when Field is unassigned.

DataChange is assigned as the OnDataChange event handler in the internal TFieldDataLink instance.

TControl.Caption TComponent.Name Object for the event notification. Gets the name of the field in the linked dataset with the value for the control. Value for the property. Gets the value for the DataSource property. Value for the property. Gets the value for the Field property. Value for the property. Sets the value for the DataField property. New value for the property. Sets the value for the DataSource property. New value for the property. Handles the CM_GETDATALINK message for the control. Message handled and updated in the method. Handles a notification when a component is added to or removed from the control.

Notification is called whenever a child component is destroyed, inserted or removed from the list of owned component. Components that were requested to send a notification when they are freed ((with FreeNotification) will also call Notification when they are freed.

The AComponent parameter specifies which component sends the notification, and Operation specifies whether the component is being inserted into or removed from the child component list, or whether it is being destroyed.

Descendants of TComponent can use FreeNotification to handle notifications when objects are freed. By overriding the Notification method, they can do special processing (typically, set a reference to this component to Nil) when this component is destroyed. The Notification method is called quite often in the streaming process, so speed should be a consideration when overriding this method.

TCustomLabel.Notification Registers the class type used to create new instance of the control for the Widgetset.

WSRegisterClass is an overridden method used to register the widgetset class type used to create new instances of the control. WSRegisterClass calls the inherited method, and excludes loading the Caption property during LCL streaming.

The Caption property was included in LCL component streaming prior to LCL version 0.9.29. TCustomLabel.WSRegisterClass Performs actions when LCL component streaming has been completed.

Loaded is called by the streaming system when a root component was completely read from a stream and all properties and references to other objects have been resolved by the streaming system. Descendants of TComponent should override this method to do some additional processing of properties after all published properties have been set from values obtained from the stream.

Application programmers should never call Loaded directly; this is done automatically by the LCL streaming system.

TControl.Loaded Component affected by the notification. Operation for the component. Constructor for the class instance.

Create is the overridden constructor for TDBText. It calls the inherited Create method, and sets up the internal TFieldDataLink member used in the component.

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

Destroy is the overridden destructor for TDBText. It frees the internal field data link in the class instance, and calls the inherited Destroy method.

TGraphicControl.Destroy Implements support for standard actions in the control.

ExecuteAction is an overridden Boolean function used to implement support for TBasicAction in the control. ExecuteAction extends the inherited method by using the internal field data link (when assigned) to perform the requested action.

AAction is the TBasicAction instance examined and potentially executed in the method.

The return value for the method is True when the action in AAction was executed for the control.

TDataLink.ExecuteAction TComponent.ExecuteAction TBasicAction Returns True when the standard action was executed for the control. Standard action examined in the method. Updates the specified action to reflect the current state in the linked dataset.

UpdateAction is an overridden Boolean function in TDBText. UpdateAction is called when the Application enters an idle state to ensure that the action reflects the current state for a linked dataset.

AAction is the TBasicAction updated in the method.

TDataLink.UpdateAction TBasicAction TComponent.UpdateAction Provides access to the field definition for the data-aware control.

Use DataField to read or write the field name used for the data-aware control. Use DataSource to specify the data source with the dataset containing the specified field name.

TField The name of the field, as a string (i.e. cannot be referred to as an Index).

DataField is a String property which contains the field name in the linked dataset with the value displayed in the control. Read and write access for the property value is redirected to the FieldName property in the internal TFieldDataLink instance used in the control.

Use DataSource to specify the datasource with the linked dataset for the control. Use Field to access the definition and metadata for the field in the linked dataset.

Provides access to the content displayed in the control.

Read and write access to the property value is redirected to the DataSource property in the internal TFieldDataLink instance used in the control. Assigning a new value to the property causes the ChangeDataSource routine to be called to apply the value to the internal TFieldDataLink instance.

Use the DataField property to specify the field name accessed in the linked dataset.

TDataLink.DataSource TDataSource Enables or disables drawing of accelerator or shortcut keys for the label.

ShowAccelChar controls if an underlined character in the label is drawn for the accelerator or shortcut key. Changing the value for the property causes the WidgetSetClass to be notified of the potential change to the Caption and size for the control.

The default value for the property is True.

TCustomLabel.ShowAccelChar Indicates if the control is displayed.

The Visible property represents the ability to see a visual control. If Visible is set to True the control is shown, otherwise it is hidden. Calling Show sets Visible to True. Setting Visible to False is equivalent to calling the Hide method.

The Visible property does not depend on control's parent visibility. Use IsVisible method to consider this and get the real visibility. TControl.Visible Indicates if text is wrapped at the right edge of the control.

WordWrapindicates whether a word is to be wrapped to the next line if the text is about to become too long for the width available in the control.

The default value for the property is False.

TCustomLabel.WordWrap Specifies a data-aware listbox control.

TCustomDBListBox is a TCustomListBox descendant which specifies the base class for a data-aware listbox control. The control allows selection and storage of a value from a scrolling list of choices to the current record in a linked dataset.

TCustomDBListBox is the ancestor class for TDBListBox. Applications should create instances of the derived class.

Use the Items property to define the list of choices displayed in the listbox control.

The DataSource property provides access to the linked dataset where the selected value is stored. Field contains the field definition for the column in the dataset where the selected value is stored. Use the DataField property to specify the name for the Field.

TCustomListBox.Items How To Use Data-aware Controls GetDataField - returns the name of the data field as a string. Value for the DataField property. GetDataSource - returns the identity of the data source. Value for the DataSource property. GetField - returns the identity of the field. Value for the Field property. GetReadOnly - fetches the ReadOnly status from the field datalink rather than using the inherited ReadOnly status. Value for the ReadOnly property. SetReadOnly - changes the datalink ReadOnly property as well as the local property, to that specified by Value. New value for the ReadOnly property. SetDataField - links to the field in the datalink with the given name. New value for the DataField property. SetDataSource - changes the attached data source to the one specified by AValue. New value for the DataSource property. CMGetDataLink - control message method for obtaining the data link. Message examined and updated in the method. FDataLink - local variable holding the identity of the field data link. Performs actions needed when the linked dataset is repositioned.

DataChange is an method used to perform actions needed when the control needs to be refreshed after a positioning the linked dataset. DataChange is an abstract virtual method in TCustomDBListBox, and must be implemented in a descendent class to perform the actions required for the control.

DataChange is assigned to the OnDataChange event handler in the TFieldDataLink instance used in data-aware controls.

Object for the event notification. Handles key down events for the control.

KeyDown is an overridden method in TCustomDBListBox which applies the specified virtual key code and modifier to the control. KeyDown calls the inherited method, and ensures that the linked dataset is updated as needed for the key down event. The following actions are performed for the corresponding keys:

VK_ESCAPE: Calls the TFieldDataLink.Reset method to cancel the edit operation. Key is set to VK_UNKNOWN.
VK_DOWN, VK_UP: Calls the TFieldDataLink.Edit method after changing the selected item in the control.

TWinControl.KeyDown Virtual key code applied in the method. Modifier for the key code applied in the method. Handles notifications when a component is added to or removed from the control.

Notification is an overridden method in TCustomDBListBox. Notification calls the inherited method, and ensures that an assigned DataSource is set to Nil when Operation contains opRemove.

TComponent.Notification UpdateData - method for applying any pending changes to the data.

UpdateData is a virtual abstract method in TCustomDBListBox, and must be implemented in a descendent class (such as TDBListBox or TDBLookupListBox) to perform the actions needed to update a linked dataset using the current selection in the control.

UpdateData is assigned to the OnUpdateData event handler in the TFieldDataLink instance for data-aware controls.

Object for the event notification. SetItems - copies the specified Values into the Items property.

SetItems is overridden in TCustomDBListBox to ensure that the DataChange method is called when the new Values are assigned to the Items property.

TCustomListBox.Items New values for the property. Constructor for the class instance.

Create is the overridden constructor for the class instance. Create calls the inherited constructor, and allocates and configures the internal TFieldDataLink used in the class instance. The DataChange and UpdateData methods are assigned as the OnDataChange and OnUpdateData event handlers in the TFieldDataLink instance.

TCustomListBox.Create Destructor for the class instance. Destroyis the overridden destructor for the class instance. Destroy frees resources allocated to internal members in the class instance, and calls the inherited destructor prior to exiting from the method. CustomListBox.Destroy Implements support for standard actions in the control.

AAction is the TBasicAction instance examined and potentially executed in the method.

The return value for the method is True when the action in AAction was executed for the control.

TDataLink.ExecuteAction TDataLink.UpdateAction TComponent.ExecuteAction TBasicAction True when the action is performed in the method. Action examined and executed in the method. Updates the state for the specified action.

UpdateAction is an overridden Boolean function used to update the state of the TBasicAction (or descendant) instance in AAction. The return value is True when the action is updated in the method.

UpdateAction calls the inherited method. When the return value is False and a linked dataset is available in the class instance, the UpdateAction method in TFieldDataLink is called to update the action.

TDataLink.UpdateAction TDataLink.ExecuteAction TComponent.UpdateAction TBasicAction True if the action was updated in the method. Action updated in the method. Field definition in the linked dataset for the control.

Field is a read-only TField property which contains the field definition used to access a column defined in the linked dataset for the control. Read access to the property is redirected to the Field property in the internal TFieldDataLink instance used in the control.

Use the DataField property to specify the field name updated when a value is selected using the control. Use DataSource to specify the datasource component for the linked dataset.

TField Name for the field in the linked dataset used in the control.

DataField is a String property which contains the name of the field in the linked dataset for the control. It is the destination where a value selected in the control is stored.

Read and write access for the property value is redirected to the FieldName property in the internal TFieldDataLink instance used in the control. Use Field to access the field definition and metadata for the column in the linked dataset.

Use DataSource to specify the datasource component which provides access to the linked dataset for the control.

Provides access to the linked dataset for the control.

DataSource is a TDataSource property which contains the component used to access the linked dataset for the control. Read and write access for the property value are redirected to the DataSource property in the internal TFieldDataLink instance for the control. Changing the value in DataSource causes the ChangeDataSource routine to be called to perform notification events and assignments for the TFieldDataLink instance.

Use DataField to specify the name of the field in the linked dataset used to store the value selected in the control. Use Field to access the field definition and metadata for the column represented by DataField.

TDataLink.DataSource TDataSource Indicates if the linked dataset for the control cannot be modified.

ReadOnly is a Boolean property which indicates if the linked dataset for the control cannot be modified. Read and write access for the property value are redirected to the ReadOnly property in the internal TFieldDataLink instance for the control.

The default value for the property is False.

The value in the property may be changed during the course of editing. For example, setting ReadOnly to False when the linked dataset cannot actually be modified. Eventually, the property value gets updated to reflect the real read-only state for the linked dataset. TDataLink.ReadOnly Implements a data-aware version of TListBox.

TDBListBox implements a data-aware version of TListBox. The control allows selection and storage of a value from a scrolling list of choices to the current record in a linked dataset.

TDBListBox extends the TCustomDBListBox ancestor class to implement abstract/virtual methods, and to set the visibility for properties in the control.

Use the Items property to define the list of choices displayed in the listbox control.

How To Use Data-aware Controls Implements the event handler signalled when data in the linked dataset has been changed.

DataChange is an overridden procedure in TDBListBox. It implements the abstract virtual method defined in the ancestor class, and updates ItemIndex to reflect the current value in the linked dataset (when available).

When DataField is an empty string, the value in ItemIndex is set to -1 to indicate that no item is selected in the control. Otherwise, the field value in the linked dataset is located in Items and its ordinal position is used in ItemIndex.

DataChange is used as the OnDataChange event handler in the TFieldDataLink instance for the control.

TCustomListBox.ItemIndex TDataLink.DataSource Object for the event notification. Performs actions needed when the current selection in the listbox control is changed.

DoSelectionChange is an overridden procedure in TDBLIstBox. It provides support for changing the modified status for the linked dataset when a new item is selected in the listbox.

User indicates if the change was performed by user interaction with the listbox, as opposed to a programmatic change from methods or messages in the class. When User is True, the internal TFieldDataLink instance is used to edit and set the Modified property in the linked dataset. When User is False, the inherited DoSelectionChange method is called.

DoSelectionChange is used in the implementation of methods in the ancestor class, like LMSelChange and SelectAll.

TCustomListBox.DoSelectionChange Indicates if the change results from user interaction with the control. Performs actions needed to update the linked dataset when the value for the control has changed.

UpdateData is an overridden method in TDBLIstBox. It implements the abstract virtual method defined in the ancestor, and provides support for updating the linked dataset when the value for the control has been changed.

UpdateData stores the value from Items located at the position in ItemIndex to the field for the linked dataset. No actions are performed in the method when ItemIndex is -1 (no item is selected in the control).

UpdateData is used as the OnUpdateData event handler in the internal TFieldDataLink instance for the control.

TCustomListBox.ItemIndex Object for the event notification. EditingDone - what to do when you have finished editing.

Called when user has finished editing. This procedure can be used by data links to commit the changes.

For example:

When focus switches to another control (default)
When user selected another item

It's up to the control to perform the actions needed when the method is called.

Event handler signalled to draw an Item on the data-aware list box.

OnDrawItemis an event handler used to draw an Item on the data-aware list box.

For example, selecting an item may require it to be highlighted or have its font or background changed.

TCustomListBox.OnDrawItem Event handler signalled when a key is pressed while the control has focus.

OnKeyPress differs from OnKeyDown in that the key needs to become pressed while the control has focus; with OnKeyDown the key may have already been down when the control received focus.

TWinControl.OnKeyPress Event handler signalled when a key is down while the control has focus.

OnKeyDown differs from OnKeyPress in that the key may have already been down when the control received focus; with OnKeyPress the key needs to become pressed while the control has focus.

TWinControl.OnKeyDown Event handler signalled when a key is up (not pressed) while the control has focus.

In OnKeyUp, the key may already have been up when the control received focus, or a pressed key may become released during the time the control has focus.

TWinControl.OnKeyUp Indicates if the control is visible on the parent.

The Visible property represents the ability to see a visual control. If Visible is True the control is shown, otherwise it is hidden. Calling Show sets Visible to True. Setting Visible to False is equivalent to calling Hide method.

The Visible property does not depend on control's parent visibility. Use IsVisible method to consider this and get the real visibility. TControl.Visible Implements a data-aware listbox control with database lookup capabilities.

TDBLookupListBox is a TCustomDBListBox descendant which implements a data-aware listbox with database lookup capabilities.

TDBLookupListBox allows selection of a value from a list of items, and stores the value to a field in a linked dataset. The database lookup feature allows a separate dataset to be used which contains the values for the items available in the control. Individual fields can be specified for both the stored value and the the associated display value. Internally, it uses a TDBLookup component to enable the database lookup feature.

In addition, the control can be used in an unbound mode where either the DataSource or the DataField is not defined for the control. This allows the lookup dataset to synchronized when the current selection in the control is changed, but prevents the selected value from being stored in the linked dataset.

Use ListSource to provide access to the lookup dataset used in the control. Use ListField or ListFieldIndex to specify the field name or ordinal position in the lookup dataset displayed in the listbox. Use KeyField to specify the field name in the lookup dataset with the value stored in the DataField for the control. Use KeyValue to read or write the value for the KeyField in the lookup dataset.

Performs actions needed when a new DataField value is selected using the lookup dataset.

DataChange is an overridden method in TDBLookupListBox. It implements the abstract virtual method defined in the ancestor class, and provides support for setting the value in ItemIndex when the value for KeyField in the lookup dataset has changed.

DataChange uses the internal TFieldDataLink instance in the control to determine if the linked dataset has been opened. If the dataset is active, the value in ItemIndex is set to the key index position from the lookup dataset. If the linked dataset is not active, the value in ItemIndex is set to -1 (indicating no item is selected in the control).

DataChange is used as the OnDataChange event handler for the internal TFieldDataLink instance in the control, and called from the DoSelectionChange method.

TCustomListBox.ItemIndex Performs actions needed when the selected item in the listbox is changed.

DoSelectionChange is an overridden method in TDBLookupListBox. It extends the inherited method to provide support for the "unbound" usage model - where either the DataField or the DataSource is not defined for the control. This allows the lookup dataset to be synchronized to the current item selection in the listbox, but does not include storing the new value in the linked dataset.

User indicates if the selection change is a result of user interaction with the listbox control, as opposed to a programmatic change from methods or messages in the class. When both User and IsUnbound are True, the UpdateData method is called to reposition the lookup dataset to the new value for the control.

When User is True and IsUnbound is False, the internal TFieldDataLink is notified of the new value by calling its CanModify, Modified, and UpdateRecord methods. If the linked dataset cannot be modified, the DataChange method is called.

DoSelectionChange calls the inherited method prior to exit.

TDataLink.UpdateRecord TCustomListBox.DoSelectionChange TCustomListBox.ItemIndex Indicates if the selection change is due to user interaction with the control. Initializes the window handle for the control.

InitializeWnd is an overridden procedure in TDBLookupListBox, and calls the inherited method to initialize the window handle and the Items used for the control. InitializeWnd ensures that the Items property is also assigned to the control items in the TDBLookup instance used in the control.

TCustomListBox.InitializeWnd TCustomListBox.Items Frees the window handle and updates the address used for the Items in the controls. TCustomListBox.DestroyWnd Applies the specified virtual key code to the control.

KeyDown is an overridden procedure used to apply the specified virtual key code and modifier to the control.

Key is the virtual key code examined in the method. Shift is the modifier for the virtual key code.

KeyDown ensures that the NullValueKey shortcut defined for the control is applied to the control and its lookup dataset in the internal TDBLookup instance. This causes the value in ItemIndex to be set to -1 to clear the selection in the listbox.

KeyDown calls the inherited method prior to exit.

TDataLink.Active TCustomListBox.ItemIndex Virtual key code examined in the method. Modifier for the virtual key code. Performs actions needed when the control has loaded using the LCL streaming mechanism.

Loaded is an overridden procedure in TDBLookupListBox. It calls the inherited method, and calls the UpdateLookup method to initialize the internal TDBLookup instance used in the control.

TComponent Updates the data in the lookup dataset for the control.

UpdateData is an overridden procedure in TDBLookupListBox. It implements the abstract virtual method defined in the ancestor class. UpdateData uses the value in ItemIndex to update the internal TDBLookup instance for the control. When ItemIndex contains a positive non-zero value, the UpdateData method in TDBLookup is called to apply the ItemIndex value.

Please note: No actions are performed in the method when ItemIndex contains a negative non-zero value.

UpdateData is called from the DoSelectionChange method when IsUnbound returns True.

TCustomListBox.ItemIndex Object for the event notification. Indicates if the control is being used in the "unbound" mode.

IsUnbound is a Boolean function which indicates if the control is being used in the "unbound" mode - where either the DataField or DataSource are not assigned for the control. This mode allows the control to synchronize the lookup dataset to the current item selection in the control, but does not post the control value to its linked dataset.

IsUnBound is used in the DoSelectionChange method to determine if the UpdateData method needs to be performed.

TDataLink.DataSource True when the control does not store the current selection in the linked dataset. Constructor for the class instance.

Create is the overridden constructor for the class instance. Create calls the inherited constructor, and allocates resources needed for the lookup dataset used in the control. Create sets the default values for properties, and assigns the OnActiveChange event handler used for the linked dataset where the selected value is stored.

TCustomDBListBox.Create Owner of the class instance. Accesses the value for the KeyField in the lookup dataset.

KeyValue is a Variant property used to access the value for the KeyField in the lookup dataset for the control. It is a Variant type because the KeyField may be represented as any of the valid field types supported in the lookup dataset.

Read and write access to the value is redirected to the internal TDBLookup instance used in the control. Read access uses the value in ItemIndex to call the GetKeyValue method in the lookup component. Write access calls the GetKeyIndex method in the lookup component.

TCustomListBox.ItemIndex Field name in the lookup dataset with the value for the control.

KeyField is a String property which contains the name of the field in the lookup dataset which provides the value stored in the data-aware control. Changing the value in KeyField causes the internal TDBLookup component to be updated, and calls the UpdateLookup method.

Use ListField to set the field name with the values displayed in the list of items for the control. Use ListFieldIndex to specify the list field by its ordinal field position in the lookup dataset.

Field name with the descriptive value displayed in the listbox.

ListField is a String property which contains the name of the field in the lookup dataset displayed in the listbox for the control. ListField normally contains a more descriptive textual value associated the KeyField.

Use ListFieldIndex to specify the list field by its ordinal position in the lookup dataset. Use KeyField to specify the name of the field with the value stored in the DataField for the linked dataset. Use ListSource to specify the datasource component with the lookup dataset for the control.

Ordinal position of the field in the lookup dataset with the descriptive value displayed in the control.

ListFieldIndex is an Integer property which contains the ordinal position of the field in the lookup dataset with the descriptive textual value displayed in the control.

Read and write access to the property value is redirected to the ListFieldIndex property in the internal TDBLookup instance used in the control. Assigning a new value to the property causes the UpdateLookup method to be called to re-initialize the TDBLookup instance and the value in the ItemIndex property.

The default value for the property is zero (0), and indicates that the first field in the lookup dataset is used as the list field.

Use ListSource to specify the datasource component used to access the lookup dataset for the control. Use ListField to specify the list field by its field name. Use KeyField to specify the field with the value stored in the DataField for the control.

Datasource with the lookup dataset for the control.

ListSource is a TDataSource property which contains the datasource component used to access the lookup dataset for the control.

Read and write access to the property value is redirected to the DataSource property in the internal TDBLookup instance used in the control. Assigning a new value to the property causes the UpdateLookup method to be called to re-initialize the TDBLookup instance and the value in the ItemIndex property.

Use ListField or ListFieldIndex to specify the field with the descriptive value displayed in the control. Use KeyField to specify the field with the value stored in the DataField for the control.

TCustomListBox.ItemIndex Indicates if caching is enabled for fields in the lookup dataset. Keyboard shortcut used to assign the empty key value to the control. Value used as the empty field value in the DataField for the control. Descriptive text displayed for the EmptyValue in the control. Indicates if the look-up data set is scrolled for a new value in the control.

Indicates if the look-up data set is searched and scrolled when a new value is selected in the control. The default value for the property is False.

TDBRadioGroup - a data-aware version of TRadioGroup, providing a series of mutually exclusive buttons to select an entry to insert into a database field.

The properties of TDBRadioGroup are similar to those of TRadioGroup (and TCustomRadioGroup). Access is obtained to members of the group by selecting (in the Object Inspector) the ellipsis (...) next to the entry Items, and then editing the stringlist.

At run-time, selecting one of the radiobuttons makes the corresponding ItemIndex available to the programmer, and the corresponding string Item gets selected and appears as the string value for the record in that field.

How To Use Data-aware Controls Signals the OnChange event handler when assigned. Change is used to signal the OnChange event handler (when assigned). Sets the DataSource to Nil when the control is destroyed.

Notification is an overridden method in TDBRadioGroup, and calls the inherited method. Notification ensures the DataSource for the control is set to Nil when Operation contains opRemove and AComponent is the DataSource component.

TComponent Component for the notification. Operation generating the notification. Updates the control display value when the linked dataset is repositioned.

DataChange is used to perform actions needed when the linked dataset for the control has been repositioned. In TDBRadioGroup, this requires setting the Value property for the control. DataChange uses the Field property (when assigned) to get the display text for the field. Value is set to an empty string ('') when Field has not been assigned.

DataChange is used as the OnDataChange event handler in the internal TFieldDataLink instance in the class. It is called directly when values are assigned to the Items and Value properties, and when UpdateRadioButtonStates is used to update tab navigation and the current selection index in the control.

Object for the event notification. Updates the linked dataset using the current selection in the control.

UpdateData us used to perform the actions needed to update a linked dataset using the current selection in the control.

In TDBRadioGroup, this involves assigning the content from the Value property to the field for the linked dataset. UpdateData uses the internal TFieldDataLink instance for the control to access the Field for the linked dataset. No actions are performed when the field in the TFieldDataLink instance has not been assigned.

UpdateData is assigned to the OnUpdateData event handler in the TFieldDataLink instance for the data-aware control.

Object for the event notification. Provides access to properties, methods, and events for the data-aware control.

DataLink is a read-only TFieldDataLink property which provides access to properties, methods, and events needed to implement the data-aware control. It maintains references to the Control and its associated DataSource, DataSet, and Field.

Read and Write access to many of the properties in the control are redirected to this member in the class instance, including: DataField, DataSource, Field, ReadOnly, et. al. It is used in the implementation of methods to synchronize the actions and state for the control and its database-related components.

Methods, such as DataChange and UpdateData, are used as event handlers in the property.

Gets the value for the radio button at the specified position in the control.

GetButtonValue is a String function used to get the value for the Radio Button at the ordinal position specified in Index.

When Index is a negative non-zero value, the return value is an empty string (''). Otherwise, the return value contains the content at the specified index position in Values. If no corresponding entry is available in Values, the content from Items at the specified position is used.

Use the Items property to define the Radio Buttons displayed in the control. Use Values to define the content stored in DataField when the radio button in ItemIndex is selected.

GetButtonValue is used in the implementation of the UpdateRadioButtonStates method.

The value stored for the specified radio button. Ordinal position in Items for the requested radio button. Updates the linked dataset to reflect the current radio button selected in the control.

UpdateRadioButtonStates is an overridden method in TDBRadioGroup used to update the the linked dataset for the data-aware control when the value in ItemIndex has been changed.

UpdateRadioButtonStates ensures that the Value for the radio button in ItemIndex is applied to the linked dataset when it can be modified. The Edit and Modified methods in DataLink are called to place the linked dataset in an edit state. Value is updated to apply the new content to the field in the linked dataset.

If the dataset cannot be modified, the DataChange method is called directly to update the control. Value is changed to 'X' character to indicate that the linked dataset could not be modified.

TCustomRadioGroup.UpdateRadioButtonStates Constructor for the class instance.

Create is the overridden constructor for TDBRadioGroup. It calls the inherited Create method, and allocates resources needed for the DataLink and Values properties. The DataChange and UpdateData methods are assigned to event handlers in DataLink.

TCustomRadioGroup.Create Owner of the class instance. Destroy is the destructor for the class instance.

Destroy is the destructor for TDBRadioGroup. It frees resources allocated to the DataLink and Values properties, and calls the inherited destructor prior to exiting from the method.

TCustomRadioGroup.Destroy Performs actions needed when the user has finished editing.

EditingDone is an overridden method in TDBRadioGroup. It is used to perform actions needed when the user has finished editing using the control. It occurs when the focus changes to another control, or when the user selects another item using the mouse.

EditingDone extends the behavior from the ancestor class to update the linked dataset by calling the UpdateRecord method in DataLink.

EditingDone calls the inherited method to signal the OnEditingDone event handler (when assigned).

TDataLink.UpdateRecord TControl.EditingDone TControl.OnEditingDone Implements support for standard actions in the control.

ExecuteAction is an overridden Boolean function used to implement support for TBasicAction in the control. ExecuteAction extends the inherited method by using the DataLink (when assigned) to perform the requested action.

AAction is the TBasicAction instance examined and potentially executed in the method.

The return value for the method is True when the action in AAction was executed for the control.

TDataLink.ExecuteAction TBasicAction TComponent.ExecuteAction True when the action was executed in the method. Action examined and executed in the method. Updates the specified action to reflect the current state in the linked dataset.

UpdateAction is an overridden Boolean function in TDBRadioGroup. UpdateAction is called when the Application enters an idle state to ensure that the action reflects the current state for a linked dataset.

AAction is the TBasicAction updated in the method.

UpdateAction calls the inherited method, and when DataLink has been assigned, executes its UpdateAction method. The return value is True when AAction is updated using either the inherited method, or the method in DataLink. The return value is False when AAction could not be updated in the method.

TDataLink.UpdateAction TComponent.UpdateAction TBasicAction True when the action was updated in the method. Action examined and updated in the method. The DataSet Field relevant to the data being selected.

Field is a read-only TField property which contains the definition used to access the field in the linked dataset where the Value for the data-aware control is stored. Read access for the property value is redirected to the Field property in DataLink.

Use DataSource to assign the component which provides access to the linked dataset.

Use DataField to access the name of the field in the linked dataset.

TField Ordinal position for the selected radio button in the group.

ItemIndex is an Integer property with the ordinal position for the selected radio button in the group. The default value for the property is -1, and indicates that no radio button is selected for the group. Changing the value for the property causes the widgetset control to be updated when its Handle has been assigned.

ItemIndex must be in the range -1..Items.Count-1. An Exception is raised with the message in rsIndexOutOfBounds if ItemIndex is set to a value less than -1 or greater than or equal to the number Items for the control.

ItemIndex is a public property in TDBRadioGroup.

Some widgetsets do not allow a radio button group to have an unselected item index. To provide cross-platform compatibility, a hidden radio button is created for this purpose. When ItemIndex is set to -1, it actually selects the hidden radio button. TCustomRadioGroup.ItemIndex The value for the selected radio button in the control.

Value is a String property which contains the text for the radio button at ItemIndex in the control. It is given the string value from the Values property stored at the position in ItemIndex. It may contain an 'X' character when the linked dataset has not been assigned, or when Values does not have a string stored at the requested position.

Assigning a new string to Value causes the Values property to be searched to locate the radio button with the specified content. ItemIndex is updated with the new position for the radio button, which initiates a call to UpdateRadioButtonStates to update the linked dataset and refresh the control. The Change method is called to signal the OnChange event handler (when assigned).

Text displayed as the caption for the control.

Gets caption as a text-string (GetText), or stores the new caption (SetText). Shows flag if caption is stored (IsCaptionStored).

By default, the Caption appears the same as the control Name in the Object Inspector, and the developer needs to set it explicitly to some new text.

The VCL implementation relies on the virtual Get/SetTextBuf to exchange text between widgets and VCL. This means a lot of (unnecessary) text copies.

The LCL uses strings for exchanging text (more efficient). To maintain VCL compatibility, the virtual RealGet/SetText is introduced. These functions interface with the LCLInterface.

The default Get/SetTextBuf implementation calls the RealGet/SetText. As long as the Get/SetTextBuf isn't overridden Get/SetText calls RealGet/SetText to avoid PChar copying.

To keep things optimal, LCL implementations should always override RealGet/SetText. Get/SetTextBuf is only kept for compatibility.

TControl.Caption Number of columns displayed for the radio buttons on the control.

Don't confuse this with the Columns entity in a DBGrid, nor with the COLUMNS entity in a SQL database - it simply refers to the number of columns of radiobuttons to be displayed.

TCustomRadioGroup.Columns Name of the Field in the linked dataset where the control Value is stored.

DataField is a String property which contains the name of the field in the linked dataset where the Value for the data-aware control is stored. Read and write access to the property value are redirected to the FieldName property in DataLink.

Use DataSource to access the component which provides the linked dataset where DataField is located.

Provides access to the linked dataset and the field definition used in the control.

DataSource is a TDataSource property which contains the component used to provide access to the linked dataset and the field used in the data-aware control.

Read and write access to the property value are redirected to the DataSource property in DataLink. Assigning a new value for the property causes the ChangeDataSource routine to be called to perform notification messages and update the DataLink property in the control.

Use the DataField property to get or set the name for the field in the linked dataset where the Value for the control is stored.

TDataLink.DataSource TDataSource Contains the string values used as captions for radio buttons in the grouped data-aware control.

Items is a published TStrings property in TDBRadioGroup. The write access specifier ( SetItems) is re-implemented in the class to perform the DataChange method after assigning the new values(s) in the property.

Use the Values property to define the strings that can be stored as the Value for the DataField in the control.

Use Value to access the element in Values for the current selection (ItemIndex) in the control.

TCustomRadioGroup.Items Event Handler signalled when the Value for the control is changed.

OnChange is a TNotifyEvent property which contains the event handler signalled when the Value for the control is changed. OnChange can be used in an application to perform actions needed after Value (and ItemIndex) has been updated, and the corresponding radio button has been set to the checked state.

OnChange is signalled from the Change method.

ReadOnly - if True, data can only be read, not written or modified. (Doesn't really make sense for a RadioGroup!).

ReadOnly is a Boolean property which indicates if the control, and its linked dataset can be modified. Read and write access for the property value are redirected to the ReadOnly property in DataLink.

The default value for the property is False.

The values of the strings in Items.

Values is a TStrings property which contains strings entries that can be stored as the Value for the control. Values is used in conjunction with the Items property, which defines the captions displayed for the radio buttons in the grouped control.

Assigning a new value to the property causes the DataChange method to be called after assigning the new property value.

Indicates if the control is visible on its parent.

The Visible property represents the ability to see a visual control. If Visible is True the control is shown, otherwise it is hidden. Calling Show sets, among others, Visible to True. Setting Visible to False is equivalent to calling Hide method.

The Visible property does not depend on control's parent visibility. Use IsVisible method to consider this and get real visibility. TControl.Visible Implements a data-aware checkbox control.

TDBCheckBox implements a data-aware checkbox control for use with a logical field in a database. The dataset field can be represented using either a Boolean or a String data type.

TDBCheckBox is a TCustomCheckBox descendant, and provides support for a linked dataset with the value for the control. Internally, it uses a TFieldDataLink instance to maintain an association between the control and its DataSource and DataField.

Support for TBasicAction is also implemented in the control using its Action property.

Use the following properties to configure and control the data-aware checkbox control:

DataSource
DataField
Field
Checked
ValueChecked
ValueUnchecked
Caption
ReadOnly
State

How To Use Data-aware Controls Gets the value for the DataField property. Value for the property. Gets the value for the DataSource property. Value for the property. Gets the value for the Field property. Value for the property. Gets the value for the ReadOnly property. Value for the property. Sets the value for the DataField property. New value for the property. Sets the value for the DataSource property. New value for the property. Sets the value for the ReadOnly property. New value for the property. Sets the value for the ValueChecked property. New value for the property. Sets the value for the ValueUnchecked property. New value for the property. Implements the CM_GETDATALINK control message for the data-aware control. Message examined and updated in the method. GetFieldCheckState - returns the checkbox state for the current field.

GetFieldCheckState is a TCheckBoxState function used to get the current state for the checkbox. GetFieldCheckState uses the internal TFieldDataLink instance in the class to access the Field in the linked dataset represented by DataField.

The field value is examined to get the return value for the method. The return value can be one of the following:

cbChecked: Used when the Boolean value in the Field is True.
cbUnchecked: Used when the Boolean value in the Field is False, or the String value matched ValueChecked. Also used when the Field has not been assigned (contains Nil).
cbGrayed: Used when the value in Field is NULL, and when none of the previous conditions are True.

The return value is assigned to the State property when the DoOnChange and DataChange methods are executed.

Current TCheckBoxState for the control. Updates the control display value when the linked dataset is changed.

DataChange is used to perform actions needed when the linked dataset for the control has been changed. In TDBCheckBox, this requires setting the State property for the control. DataChange calls the GetFieldCheckState method to get the value for the State property.

DataChange is assigned as the OnDataChange event handler in the internal TFieldDataLink instance.

Object for the event notification. Performs actions needed when the control is clicked.

DoOnChange is an overridden method in TDBCheckBox. It ensures that the internal TFieldDataLink is notified of a change to the control value. The Edit, Modified, and UpdateRecord methods in the field data link are called to store the new value for the control. If the linked dataset cannot be edited, the GetFieldCheckState is called to get the value stored in the State property.

DoOnChange calls the inherited method prior to exit.

No actions are performed in the method when the internal TFieldDataLink does not have an assigned OnDataChange event handler. TButtonControl.DoOnChange TDataLink.UpdateRecord UpdateData - examines the State to see whether it has changed.

UpdateData is a procedure used to update the linked dataset for the control when the value in the State property has been changed.

When State contains cbGrayed, the Field in the linked dataset is cleared. For other values, the Field data type determines whether one of the values in Checked, ValueChecked, or ValueUnchecked is used. If the Field is a Boolean data type, the value in Checked is stored to the linked dataset. Otherwise, the text for the field is updated using the value from ValueChecked (when Checked is True) or ValueUnchecked (when Checked is False).

UpdateData is used as the OnUpdateData event handler in the internal TFieldDataLink instance for the class.

TDataLink.DataSource Object for the event notification. Handles notification events for components used in the class instance.

Notification is an overridden procedure in TDBCheckBox, and calls the inherited method. Notification ensures that an assigned value in DataSource is cleared (set to Nil) when the DataSource component is destroyed.

TComponent.Notification Component for the notification. Operation for the notification. Constructor for the class instance. Create is the constructor for TDBCheckBox. It calls the inherited Create method, and forms the logical connections for checked and unchecked, sets initial style and state, forms datalinks and actions. TCustomCheckBox.Create Owner of the class instance. Destructor for the class instance. Destroy is the destructor for TDBCheckBox. It frees links and calls inherited Destroy method. TWinControl.Destroy Implements support for TBasicAction in the data-aware control.

ExecuteAction is an overridden Boolean function in TDBCheckBox. It extends the method from the ancestor class to include support for use of the internal TFieldDataLink to execute the action.

AAction is the TBasicAction examined and potentially executed in the method.

The return value is True when AAction is executed in in the method.

ExecuteAction calls the inherited method. If AAction is not handled in the ancestor class, the internal TFieldDataLink is used to execute the action. No actions are performed in the method when the field data link has not been assigned, or when the action is not supported for the data link.

Use Action to set the TBasicAction assigned to the ActionLink for the control, and executed in the Click method for the control.

TDataLink.ExecuteAction TDataLink.UpdateAction TControl.Action TControl.Click TBasicAction TComponent.ExecuteAction True if the action was executed in the method. Action examined an executed in the method. Updates the state for the specified action.

UpdateAction is overridden in TDBCheckBox, and checks the action specified in AAction to ensure that the current control is a target for the action.

UpdateAction calls the inherited method to determine if the control is a target for the action. If it is not handled (or updated), the internal TFieldDataLink instance calls its UpdateAction method. The action is supported when the DataSource is the target for the action.

No actions are perfomed in the method, and the return value is False, when the field data link has not been assigned. The return value is True when the action is supported for the control, and successfully updated in the method.

TDataLink.UpdateAction TControl.Action TComponent.UpdateAction TBasicAction True when the action is supported and updated in the method. Action examined and updated in the method. Provides access to the field definition for the data-aware control.

Field is a read-only TField property which provides access to the field definition to which the data-aware control is linked. Read access for the property is redirected to the Field property in the internal TFieldDataLink class instance.

Field can be used to access properties, methods, and events for the field definition in the linked dataset. This includes the data type, field kind, size, current value, display labels, key fields, lookup information, constraints, etc. There are also properties which handle conversion of the field value to different data types.

Use DataField to read or write the field name used for the data-aware control. Use DataSource to specify the data source with the dataset containing the specified field name.

TField

See TCheckBoxState for possible values of State.

TCheckBoxState

Standard Control	Data-Aware Control	Comment
TCalendar	TDBCalendar	Select a date from pop-up calendar
TCheckBox	TDBCheckBox	Check a box to show an option has been selected
TComboBox	TDBComboBox	Select an option from a list and return it (or some custom text) in the main edit box
TEdit	TDBEdit	Single-line text editing box
TGroupBox	TDBGroupBox	A container for several related controls
TImage	TDBImage	A Picture
TListBox	TDBListBox	A list of string items
TMemo	TDBMemo	Multiple-line text editing box
TRadioGroup	TDBRadioGroup	A group of mutually exclusive Radio Buttons; only one at a time may be checked and selected. Note there is no data-aware equivalent of the isolated TRadioButton
TText	TDBText	A simple text-string, usually read-only
TStringGrid	TDBGrid	A grid to display information in Rows and Columns