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.

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.

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 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 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.

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.

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.

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 TBasicAction TComponent.UpdateAction
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.

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.

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.

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.
Destroy
is 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.

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 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.

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.

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.

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
Text displayed as the caption for the control.

Gets the caption for the control as a text-string (GetText), or stores the new caption (SetText). Updates an internal flag if the 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
The name (as a string) of the field with which the checkbox is to be associated.

DataField is a String property which specifies 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 is redirected to the FieldName property in the internal TFieldDataLink instance used in the class.

The field can use either a Boolean or a String data type. For a String field type, use either the ValueChecked or ValueUnchecked property to define the value stored in the dataset for the corresponding control State.

Use DataSource to specify the linked dataset for the data-aware control.

Use Checked to read or write the control state (and the value for the field) as a Boolean data type.

TDataLink.DataSource
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 at run-time 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.

ReadOnly
- if True, data may be read but not written or modified (doesn't make much sense for a check-box unless the box is NOT Enabled!).
ValueChecked
is the value to use when the box is checked, for example True or 1
ValueUnchecked
is the value to use when the box is unchecked, for example False or 0
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
TCustomDBComboBox
is a data-aware combo-box for displaying information from a database.

TCustomDBComboBox is a TCustomComboBox descendant which specifies a data-aware combo-box control used to display and edit values in a database table. TCustomDBComboBox extends the ancestor class to provide DataField, DataSource, and Field properties needed to control access to the field in a linked dataset.

Methods are provided which enable the database features for the control, and maintain the interaction between the control and the underlying dataset. Internally, a TFieldDataLink class instance is used to maintain the association between the control and it data source and field.

TCustomDBComboBox is used as the ancestor for the TDBComboBox and TDBLookupComboBox controls. Do not create instances of TCustomDBComboBox; use one of the descendent classes.

TCustomComboBox How To Use Data-aware Controls
Gets the value for the DataField property.
Value for the DataField property.
Gets the value for the DataSource property.

GetDataSource is a TDataSource function used to get the value for the DataSource property.

TDataLink.DataSource
Value for the DataSource property.
Gets the value for the Field property.

GetField is a TField function used to get the value for the Field property.

TField
Value for the Field property.
Gets the value for the ReadOnly property.
Value for the ReadOnly property.
Sets the value for the DataField property.
New value for the DataField property.
Sets the value for the DataSource property.
New value for the DataSource property.
Sets the value for the ReadOnly property.
New value for the ReadOnly property.
Implements the message to get the data link for the control.
Control message updated in the the method.
Performs LCL deferred edit messages for events detected in the control.
True if the field was edited in the linked data set.
Performs actions to close the drop down for the combo-box.
Calls Select to trigger the OnSelect event handler.
Calls Change to trigger the OnChange event handler.
Implements the LCL message for a deferred edit.
Message handled in the method.
Deferred messages pending for the control.
Sets deferred events when the drop down for the combo-box is closed.
Checks for the DBCBEVENT_SELECT message in the control.
DataChange
- updates any changes in text.

DataChange is an abstract virtual method in TCustomDBComboBox. It must be implemented in a descendent class to perform the actions needed for the data-aware control.

Checks for mouse wheel events in the control.
Shift state for the mouse wheel event.
Number of clicks that the mouse wheel was moved.
Mouse cursor position for the mouse wheel event.
Change
-if there has been a change to the data the link must be notified.

Change is an overridden method in TCustomDBComboBox. It ensures that the internal data link for the control is notified when the value for the control is changed. This includes posting the DBCBEVENT_CHANGE deferred event message to the handle for the control.

Change does not call the inherited method directly.
TCustomComboBox.Change
Performs actions needed to apply the key down event.

KeyDown is an overridden method in TCustomDBComboBox, and calls the inherited method on entry. It ensures that a virtual key which affects the datasource state is applied to the control. KeyDown handles the following virtual key codes:

VK_ESCAPE
  Editing is cancelled. Calls the Cancel method in the linked dataset when the datasource is in an edit state. Calls the Reset method for the data link if the datasource is not being edited. Calls SelectAll to re-select content in the control. Sets Key to VK_UNKNOWN after applying the original virtual key code.

TDataLink.DataSource TDataLink.DataSet TDataSet.Cancel TCustomComboBox.KeyDown
Virtual key code handled in the method.
Key modifier handled in the method.
UpdateData
- implements any pending changes in the data.

UpdateData is an abstract virtual method in TCustomDBComboBox. It must be implemented in descendent classes, like TDBComboBox or TDBLookComboBox, to perform any actions needed to update the value stored in the Field for the control.

Updates the record in the linked dataset with the value for the control.

UpdateRecord is a procedure used to update the record in the linked dataset with the value for the control. UpdateRecord uses the internal TFieldDataLink instance to checking the editing state for the control. When both Editing and IsModified are True, the UpdateRecord method in the data link is called. No actions are performed in the method if either condition is not met.

TDataLink.UpdateRecord
Handles cut, copy and paste window messages for the control.

WndProc is an overridden method in TCustomDBComboBox. WndProc ensures that LCL Cut, Copy, and Paste window messages are applied when both the control and the dataset can be modified. WndProc uses the internal TFieldDataLink instance to examine the value in CanModify. When it is True, the inherited method is called. Otherwise, the Message result is set to 1 to prevent calling the default window process.

The inherited method is called for LCL window messages other than Cut, Copy, and Paste.

TWinControl.WndProc
LCL window message examined in the method.
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. Create allocates and configures the internal TFieldDataLink instance used in the control. Its OnDataChange and OnUpdateData event handlers are set to the DataChange and UpdateData methods (respectively). Create sets the value used in ControlStyle.

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

Destroy is the overridden destructor for the class instance. Destroy ensures that the internal TFieldDataLink instance for the class is freed prior to calling the inherited destructor.

TCustomComboBox.Destroy
Provides support for TBasicAction in the control.

ExecuteAction is an overridden method in TCustomDBComboBox. 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
Action examined and executed in the method.
True if the action was 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.

TBasicAction TDataLink.UpdateAction TComponent.UpdateAction
Action examined and updated in the method.
True when the action was updated in the method.
EditingDone
- updates data through the link, then calls inherited EditingDone.

EditingDone is an overridden method used to perform actions needed when the control has finished editing its value. EditingDone calls UpdateRecord to post the modified control value to the Field in the linked dataset. EditingDone calls the inherited method to signal the OnEditingDone event handler prior to exit.

EditingDone is called in the implementation of the CloseUp and KeyDown methods.

TCustomComboBox.CloseUp TCustomComboBox.KeyDown TControl.EditingDone
Contains the field definition from the linked dataset.

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

The value in Field is updated when the UpdateField method in TFieldDataLink is called after setting the DataField for the control.

TField
The name of the Field which provides the values displayed in 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.Dataset TDataLink.DataSource
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 is prevented from changing the field value in its 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.

A value assigned to ReadOnly may be overridden by the Field definition from the target database table.
TDataLink.ReadOnly TDataLink.DataSource TDataLink.DataSet
TDBComboBox
- a data-aware version of TComboBox to allow selection of a value from a list of entries into a database field.

TDBComboBox has properties similar to TComboBox and TCustomComboBox. It consists of an Edit Box which is the Data-aware part of the component, and a drop-down list box.

In a typical application a user would be presented with the drop-down list, would make a selection and then this would appear in the edit box and become the data value for that cell in the database.

As an example, a list of countries might be presented, and the selected value from the list would be used to populate the appropriate field ('Country') in that record of the database.

How To Use Data-aware Controls
DataChange
- updates the text if it has changed.

DataChange is an overridden method used to perform actions needed when the value in the linked dataset has been changed. DataChange uses the Field property from the data link (when assigned) to get the current value stored in the Text property for the control. If Field has not been assigned, or the dataset is not active, the value in Text is set to an empty string ('').

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

TField
Object for the event notification.
Applies standard keystrokes to the control.

KeyPress is an overridden method used to apply standard keystrokes to the data-aware control. KeyPress calls the inherited method to process the keystroke character in Key. If the key is not handled in the ancestor, and is in the range #32..#255, it can be potentially applied to the Field in the linked dataset. FieldCanAcceptKey, in the implementation section, is called to to determine if the keystroke can be used and applied to the field type. When valid for the field, Key is set to #0 to suppress further processing of the keystroke.

TField TWinControl.KeyPress
Keystroke character examined in the method.
Applies the changed value for the control to the field in its linked dataset.

UpdateData is an overridden method which implements the abstract virtual method defined in TCustomDBComboBox. UpdateData is used to applying pending changes in the control value to the field in the linked dataset. The value in the Text property for the control is stored to the Field defined in the internal TFieldDataLink instance in the class.

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

Object for the event notification.
Indicates if the drop-down is automatically displayed when the control gets the input focus.

AutoDropDown indicates whether the drop-down list for the control appears as soon as the control receives the input focus. When set to False, the drop-down list appears when the downward triangular glyph for the control is clicked. The default value for the property is False.

TCustomComboBox.AutoDropDown
The maximum length for text entered in the edit box for the control.

MaxLength is an Integer property which contains the maximum length for a value entered in the Text for the control. It controls the number of characters allowed in the edit box, but does not limit the length of the value that can be directly assigned to Text. MaxLength is passed to and read from the widgetset class when a handle has been assigned for the control.

The default value for the property is -1 in TDBComboBox, and forces the widgetset class to update its value for the property. Setting the value for the property does not alter the existing value in Text.

TCustomComboBox.MaxLength
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 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 when a key is released 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 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
TDBLookupComboBox
- a data-aware combo-box for examining a lookup table in a database.

TDBLookupComboBox is a TCustomDBComboBox descendant which implements a data-aware combo-box control that adds lookup capabilities using values from a separate dataset. Like the ancestor class, the DataField and DataSource properties are used to identify the dataset and field where the selected value for the control is stored. The ListSource, KeyField, and ListField properties are added to define the dataset with the values displayed and captured using the drop down for the combo-box control. Internally, a TDBLookUp instance is used to perform lookup operations for the control.

Other important properties used to manage the behavior and appearance of the control include:

- AutoComplete
- AutoDropDown
- AutoSelect
- NullValueKey
- EmptyValue
- DisplayEmpty
- ScrollListDataset

How To Use Data-aware Controls
Implements support for the "unbound" editing mode in the data-aware control.
True if the field was edited in the linked data set.
Indicates if the control lacks a datasource or field name ("unbound" mode).
True if either DataSource or DataField are not assigned in the field data link.
Ensures that the lookup uses the address for the items defined in the control.
Updates the lookup with the address for the items in the control when the control handle is freed.
Handles the Null key shortcut in key down events.

KeyDown is an overridden method used to handle and apply virtual key code messages (

WM_KEYDOWN) received in the control.

Key and

Shift contain the virtual key code and the

Shift-Ctrl-Alt modifiers for the message.

KeyDown ensures that the shortcut in NullValueKey is applied to the TDBLookup and the ItemIndex for the control. KeyDown calls the inherited method prior to exit.

Key examined in the method.
Modifier(s) for the key examined in the method.
Handles UTF-8 characters for the data-aware control.

UTF8KeyPress is an overridden method in TDBLookupComboBox. UTF8KeyPress ensures that the value in Key is cleared when the linked dataset cannot be modified, or the control is being used in the "unbound" mode.

UTF8KeyPress calls the inherited method prior to exit.

TCustomComboBox.UTF8KeyPress
UTF-8-encoded value examined in the method.
UpdateData
- copies the local data from the corresponding entry from the lookup field.
Updates the control when the value in the linked dataset has been changed.
Object for the event notification.
Performs the OnSelect event handler when in drop-down list mode.
Constructor for the class instance.

Create is the overridden constructor for the class instance. Create calls the inherited constructor, and allocates resources for the internal TDBLookup instance used in the class. The ActiveChange method is assigned as the OnActiveChange event handler in the internal TFieldDataLink instance used in the class. Creates sets the default values for the EmptyValue and DisplayEmpty properties.

TCustomComboBox.Create
Value for the key field in the lookup dataset at the position in ItemIndex.

Read and write access for the property value is provided using methods in the internal TDBLookup instance used in the class. Reading the value calls the GetKeyValue method in TDBLookup. Writing the value calls the GetKeyIndex method in TDBLookUp.

KeyField
the name of the field containing the key data.

KeyField is a

String property which contains the name of the field in the lookup dataset which corresponds to the

DataField in the linked dataset. Read and write access to the property value are redirected to the

KeyField property in the internal

TDBLookup instance used in the class. Setting a new value for the property causes the internal field data link to be refreshed, and potentially changes the value and the item index in the control.

Use ListSource to specify the component which provides access to the lookup dataset.

Use ListField to specify the field with values displayed in the drop-down for the combobox control.

ListField
is the name of the field containing the list data displayed in the control.

ListField is a String property which contains the name of the field in the lookup dataset with the values displayed in the drop-down for the combobox control. Read and write access for the property value are redirected to the ListField in the internal TDBLookup instance used in the class. Setting a new value for the property causes the internal TFieldDataLink in the class to be refreshed, and results in a change to the ItemIndex and the current value for the control.

Use ListSource to assign the component which provides access to the lookup dataset for the control.

Use KeyField to specify the field in the lookup dataset stored in DataField when an item is selected in the data-aware control.

Use ListFieldIndex to get the ordinal position in the lookup dataset for current value in the control.

ListFieldIndex
- the index value of the field containing the list.
ListSource
the data source that contains the list.
Indicates if look-up items are cached in the field data link for the control.

LookupCache is a Boolean property which indicates if look-up items are cached in the field data link for the control. The property value is re-directed to the LookupCache property in the internal TDBLookup instance for the control. Changing the property to True causes the value in ItemIndex to be updated to the value in from the look-up cache.

TCustomComboBox.Items TCustomComboBox.ItemIndex
Keyboard shortcut which causes an empty value to be assigned to the field value for the lookup control.

NullValueKey is a TShortCut property which contains the keystroke used to assign a Null value to the data-aware control. Read and write access for the property value are redirected to the NullValueKey property in the internal TDBLookup instance used in the class.

NullValueKey is used in TDBLookup methods, and handled in the KeyDown method for data-aware controls which support the feature. The default value for the property is zero (0) and indicates that the shortcut key is not used for the control.

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 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 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.
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.

TDBMemo
- a data-aware Memo box to process the multi-line text of a single field in a dataset.

TDBMemo is a TCustomMemo descendant which implements a data-aware memo control. Like its ancestor, TDBMemo can be used to display or edit multi-line textual content. It extends the ancestor class to provide properties which define the datasource and field name with the value maintained in the control. For situations where data-awareness is not needed, use the TMemo control.

Internally, the control uses a TFieldDataLink to maintain an association between the control and its datasource, dataset, and field.

Use DataSource to assign the component with the linked dataset for the control.

Use DataField to specify the name of the field in the linked dataset with the value for the control.

Use the AutoDisplay property to control whether the field content is automatically displayed during record navigation in the linked dataset. When AutoDisplay is set to False, the DisplayLabel for the Field is shown in the control and it content must be loaded by calling the LoadMemo method.

TCustomMemo 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.
TCustomEdit.GetReadOnly
Value for the property.
Sets the value for the AutoDisplay property.
New 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.
Implements the CM_GETDATALINK message for the control.
Message handled in the method.
Gets the value for the ReadOnly property.
Value for the property.
Sets the value for the ReadOnly property.
TCustomEdit.SetReadOnly
New value for the property.
DataChange
- if Data changed, loads the new data into the appropriate part of the Field.
Object for the event notification.
Handles the notification when a component is added or removed from the control.

Notification is an overridden method in TDBMemo. It calls the inherited method on entry, and ensures that the DataSource property is Nil'd when the component it is removed from the class instance.

TControl.Notification
Component for the notification.
Operation performed on / for the component.
UpdateData
- if data changed, copy new text via the datalink.
Object for the event notification.
Performs actions needed when the value for the control has been changed.

Change is an overridden method used to perform actions needed when the value for the control has been changed. Change ensures that the linked dataset is notified by calling its Modified method. Change calls the inherited method prior to exit to signal the OnChange event or other handlers implemented in the ancestor class.

TCustomEdit.Change TCustomEdit.OnChange
Handles key down events in the data-aware control.

KeyDown is an overridden method used to handle key down events in the control.

Key is the virtual key code examined and handled in the method. Shift is the Shift-Ctrl-Alt modifier for the virtual key code.

KeyDown calls the inherited method to handle the key down event in the method form ancestor class. If Key is not already applied, it is checked for the following values:

VK_ESCAPE
  Editing is being cancelled. Calls the Reset method in the TFieldDataLink instance used in the class. Call SelectAll to re-select content in the control. Sets Key to VK_UNKNOWN to indicate that it was handled in the method.
VK_DELETE, VK_BACK
  Content is being removed in the control. If the Field in the internal TFieldDataLink is not editable, the value in Key is set VK_UNKNOWN.

TWinControl.KeyDown
Virtual key code examined in the method.
Sift modifier for the key code.
Registers the widgetset class created for new instances of the control.
Constructor for the class instance.

Create is the overridden constructor for the class instance. Create calls the inherited constructor, and allocates resources for the internal TFieldDataLink instance used in the class. The DataChange and UpdateData methods are assigned as the OnDataChange and OnUpdateData event handlers in the TFieldDataLink instance. Create sets the default values for the ControlStyle and AutoDisplay properties.

TCustomMemo.Create TControl.ControlStyle
Owner for the class instance.
Destroy
- destructor for TDBMemo: frees datalinks then calls inherited Destroy.
TCustomMemo.Destroy
Called when editing has been completed in the control.

EditingDone is an overridden method in TDBMemo. It is called when the user has finished editing in the control, and ensures that changes are applied to the field in the linked data set.

In TDBMemo, it calls the UpdateRecord method in the field data link when it can be modified and has been placed in edit mode. The inherited method is called to signal the OnEditingDone event handler (when assigned).

If the field cannot be modified in the linked data set, or the data set is not in Edit mode, the Reset method in the field data link is called. This will signal the OnDataChange event handler (when assigned), but the linked data set is not updated.

EditingDone is called from the KeyUpAfterInterface method when the VK_RETURN key code is handled, and when the focus is changed to another control.

TDataLink.UpdateRecord TCustomEdit.EditingDone TControl.OnEditingDone
Loads the lines of text for the memo from the field in the linked data set.

LoadMemo is a method used to load the text for the control from the field in the linked data set. No actions are performed in the method if the value for the memo has already been loaded, the field in the data link has not been assigned, or the field does not use the TBlobField field type.

LoadMemo signals the OnGetText event handler (when assigned) in the field data link to get the value that is stored in the Lines property. If the event handler has not been assigned, the AsString method in the linked data field is used to get the value for the control.

If an EInvalidOperation exception occurs while getting the value for the control, the exception message is stored in the Lines property.

LoadMemo is called when the value in AutoDisplay is changed to True, when the DataChange method is called, and when the Enter key is handled in the KeyPress method.

Provides support for TBasicAction in the control.

ExecuteAction is an overridden method in TDBMemo. 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 TDBMemo. 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.

TBasicAction TComponent.UpdateAction TDataLink.UpdateAction
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 component with the dataset containing the specified field name.

TField
AutoDisplay
- if True, automatically displays the data when loaded from the linked dataset.

AutoDisplay is a Boolean property which indicates if the content in the control is automatically displayed when it is loaded from the linked dataset. Changing the value in AutoDisplay causes the LoadMemo method to be called to load the content for the control. The default value for the property is True.

AutoDisplay is used in the implementation of the DataChange method called when the content dataset from the dataset has been updated.

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 name of the field in the linked dataset where the value for the control is stored. Read and write access to the property value are redirected to the FieldName property in the TFieldDataLink instance used in the class. Changing the value in DataField causes the value in the Field property to be updated.

Use DataSource to specify the component which provides access to the linked dataset for the 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 that the text in the control cannot be modified.

ReadOnly is a Boolean property which indicates whether the control is prevented from modifying its textual content. When set to False, the control value can be edited.

Read and write access specifiers in TDBMemo are overridden, and to the property value is redirected to the ReadOnly property in the TFieldDataLink instance used in the class. Write access calls the inherited method prior to updating the value in the field data link.

A value assigned to ReadOnly may be overridden by the Field definition from the target database table.
TCustomEdit.ReadOnly TDataLink.ReadOnly
TDBGroupBox
- a data-aware version of TGroupBox, allowing a number of data-aware objects to be grouped together on a form.

TDBGroupBox is a TCustomGroupBox descendant which implements a data-aware container for visual controls. A typical use case would involve using a database table where records contain one field which defines the group box caption, while other fields provide the values for additional data-aware controls.

Like other data-aware controls, TDBGroupBox contains both a DataSource and a DataField property which provides access to the linked dataset and the field with the caption for the control.

TCustomGroupBox How To Use Data-aware Controls
FDataLink
- local variable storing the identity of the Field Data Link.
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.
New value for the property.
CMGetDataLink
implements the control message for finding the data link.
Message where the field data link is stored in the method.
Updates the value for the control when the linked dataset is changed.

DataChange is a procedure used to update the value displayed for the control when its linked dataset has been changed.

DataChange is used as the OnDataChange event handler in the internal TFieldDataLink instance used in the class. It is called after navigating to a different record in the linked dataset, or when the value for the DataField has been changed in program code.

DataChange uses the Field definition (when assigned) to get the value for the Caption in the control. When the Field has not been assigned, the Caption is set to an empty string ('').

Object for the event notification.
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 request notification of the destruction of another object. 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.

TControl.Notification
Component for the notification event.
Operation for the notification event.
Constructor for the class instance.

Create is the overridden constructor for TDBGroupBox. It calls the inherited Create method, and allocates resources for the internal TFieldDataLink used in the control. The current class instance is assigned as the Control for the Field Data Link, and the DataChange method is used as the OnDataChange event handler.

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

Destroy is the overridden destructor for TDBGroupBox. It frees resources allocated to the internal TFieldDataLink instance used in the control, and calls the inherited Destroy method prior to exit.

TWinControl.Destroy
Provides support for TBasicAction in the control.

ExecuteAction is an overridden method in TDBGroupBox. 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 TDBGroupBox. 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.

TBasicAction TComponent.UpdateAction TDataLink.UpdateAction
True if the action was updated in the method.
Action examined and updated in the method.
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 DataField 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.

Read access to the property value is redirected to the Field property in the internal TFieldDataLink instance used in the class.

The DataSource property contains the component which provides access to the Dataset for the data-aware control.

TDataLink.DataSource TDataLink.DataSet
Text displayed as the caption for the control.

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

By default, the Caption is the same as the control Name in the Object Inspector. 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 RealGet/SetText. As long as the Get/SetTextBuf isn't overridden Get/SetText calls RealGet/SetText to avoid PChar copy operations.

For optimal usage, LCL implementations should always override RealGet/SetText. Get/SetTextBuf is only kept for compatibility.

TControl.Caption
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.

TDataLink.DataSource TDataSource
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 being pressed while the control has focus.

OnKeyPress is an event controller signalled when a key is being pressed while the control has focus.

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 up (not pressed) while the control has focus.

OnKeyUp is 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
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
Specifies an event handler signalled to identify the graphic type for a database image.

TOnDBImageRead is the type used for the OnDBImageRead property in TDBImage. It provides a mechanism for identifying the graphic class needed to load image content in the specified stream. In general, it is used when image data in S contains an additional header that must be processed / handled prior to reading the raw image data.

Object (TDBImage) instance for the event notification.
Stream instance with the image data examined in the event handler.
Returns the file extension used for the graphic type, or an empty string when not determined.
Event handler signalled when an image is written to the specified stream.

TOnDBImageWrite is the type used for the OnDbImageWrite property in TDBImage.

Object (TDBImage) for the event notification.
Stream instance where the image is stored.
File extension associated with the image data.
TDBImage
- a data-aware Image box to display a single image from a dataset.

TDBImage is a TCustomImage descendant which implements a data-aware image control. TDBImage is used to retrieve or save a graphic image in a field in a dataset. The field is generally a Binary Large Object (BLOB). The control allows use of clipboard operations, like Copy/Cut/Paste to add or update the content in the image.

If an application doesn't need the data-aware capabilities of TDBImage, use a TImage control.

TDBImage, like most data-aware controls, provides DataSource and DataField properties to connect the control to a dataset and field. Internally, it uses a TFieldDataLink to maintain an association between the control and its database-related configuration settings.

Use the AutoDisplay, AutoSize, Stretch, Proportional, and Transparent properties to determine the display and sizing behavior for the graphic image.

How To Use Data-aware Controls
Gets the value for the DataField property.

Returns the FieldName property from the field data link.

Field name with the data for the control.
Gets the value for the DataSource property.
Value for the DataSource property.
Gets the value for the Field property.
Value for the Field property.
Gets the value for the ReadOnly property.
Value for the ReadOnly property.
Sets the value for the AutoDisplay property.
Value for the AutoDisplay property.
Sets the value for the DataField property.
New value for the DataField property.
Sets the value for the DataSource property.
New value for the DataSource property.
Sets the value for the ReadOnly property.
New value for the ReadOnly property.
Implements the CM_GETDATALINK message for the control.
Message for the handler.
Handles notifications when a component in the class instance is added or removed.

Notification is an overridden method in TDBImage used to handle the notification received when a component for the control is added or removed. It calls the inherited method on entry.

Notification ensures that the Datasource member is set to Nil when its component is removed from the control. Needed when the data link for the control has been assigned.

TComponent.Notification
Component for the notification.
Operation for the notification.
Performs actions needed when the content in the linked dataset has been changed.

DataChange is a procedure used to perform actions needed when the content in the linked dataset has been changed. Such as when the record position has changed when scrolling the dataset.

DataChange ensures that the TGraphic instance in Picture is set to Nil. If AutoDisplay is set to True, the graphic image is loaded by calling the LoadPicture method.

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

TCustomImage.Picture TPicture.Graphic
Object for the event notification.
Performs actions needed to validate and store the content for the image control.

UpdateData is a procedure used to validate and store the content for the image control.

UpdateData examines the Picture in the image control to ensure that it has been assigned, and contains image content. The Field in the linked dataset is cleared if either condition is False, and no additional actions are performed in the method.

Otherwise, a BLOB stream is created and used to write the image content to the field in the linked dataset. The OnDBImageWrite event handler is signalled (when assigned) to write a custom image header to the BLOB stream. If OnDBImageWrite is not used, and WriteHeader is True, the file extension for the graphic format is written to the BLOB stream. Finally, the content for the bitmap graphic is written to the BLOB stream.

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

Object for the event notification.
Performs actions needed when the Picture property in the image control has been changed.

PictureChanged is an overridden method in TDBImage, and calls the inherited method. PictureChanged ensures that the Change method is called if it has not already been executed.

PictureChanged is assigned as the OnChange event handler for the TPicture instance in the Picture property.

TCustomImage.PictureChanged TPicture.OnChange
Object for the event notification.
Register the component class with the widgetset.

WSRegisterClass is a class method used to register the component class with the widgetset.

It is overridden in TDBImage to ensure that the class is registered only once. No actions are performed in the method if the class has already been registered with the widgetset. It calls the inherited method to register ancestor image classes.

TDBImage calls RegisterPropertyToSkip to exclude the Picture property during LCL component streaming. TDBImage loads its Picture data from the data set, and not from an LFM resource. Picture was removed in Lazarus version 0.9.29.

TCustomImage.WSRegisterClass TCustomImage.Picture RegisterPropertyToSkip
Implements the clipboard Copy (Ctrl+C) command.

DoCopyToClipboard is a procedure used to implement the clipboard Copy ( Ctrl+C) command. DoCopyToClipboard assigns the Picture in the control to the Clipboard for the application.

For the Windows platform, the TBitmap format is expected in Picture. For all other platforms, the TPortableNetworkGraphic format is expected. DoCopyToClipboard calls the AddFormat method in Clipboard when needed. If Picture uses a Graphic format other than expected, it is written to a memory stream and loaded into the Clipboard using the newly registered graphic format.

TCustomImage.Picture TClipboard.AddFormat TClipboard TGraphic TBitmap TPortableNetworkGraphic
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor.

Create allocates resources for the internal TFieldDataLink instance used in the class, and configures the data link. The DataChange and UpdateData methods are used as the OnDataChange and OnUpdateData event handlers in the data link.

Create sets the default value for the following properties:

ControlStyle
  Includes csReplicatable in the existing style for the control.
AutoDisplay
  Set to True.
QuickDraw
  Set to True.
WriteHeader
  Set to True.

TCustomImage.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 the internal TFieldDataLink instance is freed, and calls the inherited destructor prior to exiting from the method.

TCustomImage.Destroy
Provides support for TBasicAction in the control.

ExecuteAction is an overridden method in TDBImge. 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 TDBImage. 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.

TBasicAction TComponent.UpdateAction TDataLink.UpdateAction
True if the action was updated in the method.
Action examined and updated in the method.
Definition for the field in the linked dataset where the control value is stored.

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 component with the dataset containing the specified field name.

TField
Notifies the linked dataset when the value in the control is changed.

Change is a procedure used to notify the linked dataset in DataSource when the image in the control has been changed. Change calls the Modified method in the internal TFieldDataLink instance used in the class. This results in the UpdateData method being called to post the new value to the field in the dataset.

TDataLink.DataSource TDataLink.DataSet
Loads the graphic content for the control from a field in the linked dataset.

LoadPicture is a procedure used to load the graphic content into the image control from the field in the linked dataset. DataField contains the field name with the value for the control. DataSource is the component which provides access to the dataset with the specified field name.

LoadPicture uses the internal TFieldDataLink in the class instance to access the dataset and the field definition used in the operation. The Field is assigned to the Picture in the control when it is not already in use. If the Field is a BLOB field type, a BLOB stream is created and used to load the content in Picture.

LoadPicture uses the OnDBImageRead event handler (when assigned) to identify and load the graphic header and content for the image. When OnDBImageRead is implemented, it is assumed that a known graphic type is processed in its entirety in the handler. Otherwise, an invalid graphic type is returned and the remainder of the stream content is the graphic image data. In particular, returning an invalid graphic class while the stream contains an image header will not work.

If OnDBImageRead is not used, the ReadImageHeader method is called and the content for the graphic type is read and assigned to the Picture in the control.

LoadPicture is called when the value in the AutoDisplay property is changed to True, and from the implementation of the DataChange method.

Use PictureLoaded to determine if LoadPicture has already been called for the current record in the linked dataset.

TDataLink.DataSet TDataLink.DataSource TCustomImage.Picture TPicture.Graphic
Performs actions needed for the Clipboard Copy (Ctrl+C) command.
Performs actions needed for the Clipboard Cut (Ctrl+C) command.
Performs actions needed for the Clipboard Paste (Ctrl+V) command.
Indicates if the graphic content for the data-aware control has been loaded from its linked dataset.
AutoDisplay
- if True, automatically displays when focus is given.

AutoDisplay is a Boolean property which indicates if the graphic content for the control is automatically displayed when values become available in the linked dataset. AutoDisplay is used in the implementation of the DataChange method to determine if LoadPicture is called.

Setting the property to True calls the LoadPicture method to retrieve the graphic content from the field in DataField.

The default value for the property is True.

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.

Graphic content read from DataField is stored in the Picture property for display and editing using the control.

TDataLink.DataSource TDataLink.DataSet TCustomImage.Picture
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
Event to read a custom header from image stream.

By default, the TDbImage component expects a header at the start of the image stream. This helps to efficiently identify the image format contained in the data stream. On writing, the header is controlled by the WriteHeader property or the OnDbImageWrite event handler.

When loading image data which was created by external applications, the data stream may not have a header or the header is not a format identifier that the TDbImage component would recognize.

In this case, the OnDbImageRead event can be used to identify the image format in the data stream. In the GraphExt parameter it must return a format identifier corresponding to the registered image format. This format identifier could e.g. be read from the data stream provided in the s parameter. On return, the data stream should start with the raw image data.

If the OnDbImageRead handler was not implemented or if it returns an invalid format identifier, the TDbImage component will try to load the image by checking the data stream content. This means that it is not necessary to write an OnDbImageRead event handler for the most common image formats, For example: jpg, png, gif or bmp.

The TDbImage component will be able to identify the image format even if the data stream doesn't have a header for those TGraphic registered classes that implement the IsStreamFormatSupported method.

Event to write a custom header into image stream.

Use OnDBImageWrite to write a custom header in the image stream. This header could be "decoded" in the handler for the OnDbImageRead event when loading. The header will be followed by the image raw data.

By default, TDbImage will write an image header in order to efficiently identify the image format when loading. This behavior is controlled by the WriteHeader property. If your database will be shared with external applications that do not support this, it is important to not write an image header. This could be achieved by writing an empty handler for OnDbImageWrite. Note that an empty handler has the same effect as setting WriteHeader to False.

OnDbImageWrite has precedence over the WriteHeader property.

QuickDraw
- if True, quick drawing is implemented.

QuickDraw is a Boolean property which indicates if QuickDraw is enabled for the platform or OS. The default value for the property is True.

QucikDraw is not used in the current LCL implementation.
Indicates if the control cannot modify the image in the field for 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.

A value assigned to ReadOnly may be overridden by the Field definition in the target database table.
TDataLink.ReadOnly TDataLink.DataSource TDataLink.DataSet
Write a header in the image stream.

The WriteHeader property controls whether or not a header will be written to the image stream. By default a header will be written. This helps to efficiently identify the image format when loading. The writing of a header in the image stream could be a problem if the database will be shared with external applications that do not expect a header in the image stream. In this case, set WriteHeader value to False in order to skip the header writing.

The default value is True.

Note: The WriteHeader value is ignored if the OnDbImageWrite event is implemented.

TDBCalendar
- a data-aware version of TCalendar, for selecting a date to store in a database field.

TDBCalendar is a TCalendar descendant which implements a data-aware calendar control used to select a date and store its value in a database field. TDBCalendar, like its ancestor, displays a calendar which can be used to navigate through years, months, and days to select the Date value for the control. When Date has been assigned, it is stored in the field identified by the name in DataField.

Use Field to access the definition and metadata for the field where the Date value is stored.

Use DataSource to assign the component with the dataset where the Date value is stored.

Use DisplaySettings to control the visual appearance and content displayed on the calendar control.

Use the OnYearChanged event to perform action required when the navigation arrows in the calendar are used to change the year in the Date value.

Internally, a TFieldDataLink class instance is used to maintain the association between the control, the datasource, and the field. In addition, support for using standard actions is provided in the ExecuteAction and UpdateAction methods.

TCalendar How To Use Data-aware Controls
FDataLink
is a local variable used to hold field information for the linked dataset.
DataChange
- if the link is active, transmit the changed data.
Object for the event notification.
UpdateDate
- implements any pending changes in the date selected.
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.
Gets the value for the ReadOnly property.
Value for the property.
Sets the value for the ReadOnly property.
New value for the property.
Sets the value for the Date property.
New 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.
Updates the value in the Date property.
Value assigned to the Date property.
CMGetDataLink
- control message method for getting the data link.
Implements the CM_GETDATALINK message for the control.
Handles the notification when a component on the control is added or removed.

Notification is an overridden method in TDBCalendar. It ensures that the DataSource is set to Nil when the component is freed.

TControl.Notification
Component for the notification.
Operation for the notification.
Create
- constructor for TDBCalendar: calls inherited Create and forms datalinks and actions.

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

TCustomCalendar.Create
Owner of the class instance.
Destroy
- destructor for TDBCalendar: frees datalinks and calls inherited Destroy.

Destroy is the overridden destructor for the class instance. Destroy frees resources allocated to the internal TFieldDataLink instance in the class, and calls the inherited destructor.

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

EditingDone is an overridden method in TDBCalendar. 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 TFIeldDataLink instance used in the class.

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

TDataLink.UpdateRecord TControl.EditingDone TControl.OnEditingDone
Provides support for TBasicAction in the control.

ExecuteAction is an overridden method in TDBCalendar. 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 TDBCalendar. 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.

TBasicAction TComponent.UpdateAction TDataLink.UpdateAction
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
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.

TDataLink.DataSource TDataSource
Date value for the control as a String type.

Date is a String property that represents the date/time value for the control as a string data type. Write access is re-implemented in TDBCalendar to call the DataChange method after setting the DateTime value in the ancestor.

Use DateTime to access the value for the control as a TDateTime value.

Raises an EInvalidDate exception in the ancestor class when an invalid date value is assigned to Date.
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.

A value assigned to ReadOnly may be overridden by the Field definition from the target database table.
TDataLink.ReadOnly TDataLink.DataSource TDataLink.DataSet
Not used in the current LCL version.
Not used in the current LCL version
Not used in the current LCL version.
Not used in the current LCL version.
TDBNavButtonType.

TDBNavButtonType is an enumerated type with values that represent button types (and their corresponding glyphs) in a database navigation control. TDBNavButtonType enumeration values are used when accessing the Buttons and Images in TDBCustomNavigator, and when accessing the default resource names in DBNavButtonResourceName.

Represents the First button used to navigate to the beginning of a dataset.
Represents the Prior button used to navigate to the previous record in a dataset.
Represents the Next button used to navigate to the next record in a dataset.
Represents the Last button used to navigate to the last record in a dataset.
Represents the Insert button used to create a new record in a dataset.
Represents the Delete button used to delete the current record in a dataset.
Represents the Edit button used to enable edit mode for the current record in a dataset.
Represents the Post button used to apply pending changes to a record in a dataset.
Represents the Cancel button used to cancel pending updates to a dataset.
Represents the Refresh button used to refresh the records in a dataset.
Stores TDBNavButtonType enumeration values.

TDBNavButtonSet is a set type used to store zero or more values from the TDBNavButtonType enumeration. TDBNavButtonSet is the type used to implement the VisibleButtons property in TDBCustomNavigator.

Controls the appearance and behavior of a navigator button.

TDBNavButtonStyle is an set type used to store information which controls the appearance and behavior for a button on a navigation control. TDBNavButtonStyle is the type used to implement the NavStyle property in TDBNavButton.

These style options are not used in the current implementation of the LCL.
Enables use of a timer for the operation performed by a navigator button.
Allows the button to be drawn with a focus rectangle.
Represents the orientation for buttons on a TDBNavigator control.

TDBNavButtonDirection is an enumerated type with values that control the orientation for buttons on a database navigation control. TDBNavButtonDirection is the type used to implement the Direction property in TDBCustomNavigator.

Buttons are displayed horizontally (in a row).
Buttons are displayed vertically (in a column).
Represents options available on a TDBNavigator control.
Navigator has focusable buttons.
Set type used to store values from TDBNavigatorOption.
Alias to the TDBNavButtonType type.

TNavigateBtn is an alias for the TDBNavButtonType type. TNavigateBtn is provided to maintain Delphi compatibility.

Specifies an event handler used to handle click events in a database navigation control.

TDBNavClickEvent is an object procedure type which specifies an event handler signalled for click events in a database navigation control. TDBNavClickEvent is the type used to implement the OnClick and BeforeAction events in TDBCustomNavigator.

Applications must implement and assign an object procedure using the signature for the handler to respond to the event notification.

Object for the event notification.
Navigator button for the click event.
Set with the default buttons displayed on a TDBNavigator control.

DefaultDBNavigatorButtons is an array constant which contains the default buttons available in a database navigation control. DefaultDBNavigatorButtons contain values from the TDBNavButtonType enumeration in the order they are displayed on a TDBCustomNavigator control.

DefaultDBNavigatorButtons is used as the default value for the VisibleButtons property in TDBCustomNavigator.

Default resource names for the buttons displayed in TDBCustomNavigator.

DBNavButtonResourceName is an array constant which contains the resource names used for the buttons displayed in a database navigator control. Elements in the array contain a String with the name assigned to TDBNavButton instances created in a TDBCustomNavigator control. The element also represents the default glyph displayed on the button when the Images property has not been populated for the navigator control.

Each of the String elements in the array can be accessed using a TDBNavButtonType index value.

TComponent.Name
TDBCustomNavigator
- the base class for TDBNavigator, a tool for navigating through the records of a dataset.

TDBCustomNavigator is the parent class for TDBNavigator, an advanced tool for navigating through datasets generated by a query sent to the database. Most of the important properties are defined here in this base class.

It consists of a series of toolbuttons used to perform navigation and maintenance for records in the linked dataset. For example:

Navigation
  First, Prior, Next or Last
Maintenance
  Insert, Delete, Edit, Post, Cancel or Refresh

Use the VisibleButtons property to specify which of the Buttons can be displayed in the control.

If used in conjunction with a data-aware controls, it controls which record is displayed, the position of the record selection cursor, and the initiation of changes to the dataset and ultimately the database.

Most of the functionality of the toolbar is already built-in to the control, but if the programmer needs to specify actions to be associated with individual buttons, there is a procedure BtnClick to which an argument can be sent with the index value of the button clicked, and the procedure chooses which action to call dependent on the button index.

The DataSource property must be assigned to link to the dataset for the control.

How To Use Data-aware Controls
Performs actions needed when the values in the default hints have changed.
Used as the OnChange event handler for the TStringList used in UpdateHints.
Object for the event notification.
Gets the value for the DataSource property.
Value for the property.
Gets the value for the Hints property.
Value for the property.
Sets the value for the DataSource property.
New value for the property.
Sets the value for the Direction property.
New value for the property.
Sets the value for the Flat property.
New value for the property.
Sets the value for the Hints property.
New value for the property.
Sets the value for the Images property.
New value for the property.
Sets the value for the Options property.
New value for the property.
Sets the value for the ShowButtonHints property.
New value for the property.
Sets the value for the VisibleButtons property.
New value for the property.
Handles the CM_GETDATALINK message for the control.
Message handled in the method.
Implements the OnChange event handler for the TChangeLink instance in the class.
Object for the event notification.
The list of Buttons included in the navigator tool.

Buttons is a member which contains an array of TDBNavButton instances available in the control. Values in Buttons are accessed using an TDBNavButtonType index value. TDBNavButton elements in the array are created and destroyed to reflect the current state of the linked dataset in the DataSource property. The elements in the array are updated in the DataChanged, EditingChanged, and ActiveChange methods to use the Enabled and Visible settings needed for the dataset state.

Use FocusableButtons to access the Buttons which can be focused in the control.

Use VisibleButtons to specify the Buttons which can be displayed on the control.

Contains the focusable button for the DB navigator control.

FocusableButtons is a member with an array of TDBNavFocusableButton instances for the control. The buttons are freed and created in the UpdateButtons method as needed, and contains a button for each of the values in the VisibleButtons property. Buttons in the array are accessed using the enumeration values in TDBNavButtonType.

DataChanged
- update status of all the buttons to reflect new data.
EditingChanged
- the status of the buttons is set to CanModify.
ActiveChanged
- if datalink is active, calls DataChanged and EditingChanged.
DataChanged EditingChanged
UpdateButtons
- if the position of the buttons need to be changed, does this, then updates the status of the buttons (see ActiveChanged).
ActiveChanged
UpdateHints
- reloads the default hints and modifies any that have been changed.
HintsChanged
- calls UpdateHints.
UpdateHints
Object for the event notification.
ButtonClickHandler
- performs BtnClick for the appropriate button.
Object for the event notification.
Default size for new instances of the class.
BeginUpdateButtons
- locks the buttons before updating them.
EndUpdateButtons
- unlocks each button in turn and updates it if needed.
Sets the value for the Enabled property.
TControl.Enabled
New value for the Enabled property.
Create
- constructor for TDBCustomNavigator: locks the buttons, calls inherited Create, sets default size, style, forms datalinks, initializes hints, updates the buttons.
TCustomPanel.Create
Owner of the class instance.
Destroy
- destructor for TDBCustomNavigator: frees datalinks and hints, then calls inherited Destroy.
TCustomControl.Destroy
BtnClick
- procedure to respond to button clicks, and select an action from a list according to the value of the Index of the clicked button.
Ordinal position for the button clicked on the navigator control.
Number of visible buttons on the control.
Number of visible buttons on the control.
BeforeAction
- code to be executed before an action is performed.
Indicates if the user is asked to confirm a record deletion.

When set to True, a dialog is displayed to ask for confirmation of the Delete request.

The Data Source to which the control must be linked in order to function.
Contains the orientation for buttons displayed on the control: horizontal or vertical.
Flat
- if True, buttons have no 3-D effect.
A list of hints to be shown if the mouse hovers over a button.
Options enabled for the navigator.
The action to be taken when a navigator button is clicked.
TControl.OnClick
The set of visible buttons (some of them can be suppressed if their function appears redundant).

The VisibleButtons entry in the Object Inspector can be used to set whether or not a particular button is to be visible.

Controls whether button hints are displayed for the control.
Contains the images available for display on the navigator buttons.

Images is a TCustomImageList property which contains the images available for use as glyphs on the navigator buttons. Bitmaps stored in Images should be in the order defined in the TDBNavButtonType enumeration. The enumeration values are used as the image index. When Images has not been assigned, the default glyphs in LCL are used for the purpose.

Setting a new value for Images causes the TChangeLink instance in the class to be notified; existing Images are unregistered, and new Images (if any) are registered. UpdateButtons is called to apply image indexes and event handlers to the Buttons in the control.

TCustomImageList TChangeLink LCLGlyphs
TDBNavButton
implements a SpeedButton displayed on a TDBNavigator control.
Set with the style values for the navigator button.

NavStyle is a TDBNavButtonStyle property which contains the style values used for the navigator button. It contains zero or more values representing the features enabled for the button. See TDBNavButtonStyle for more information about the values in the set type and their meanings.

NavStyle is used in the TDBCustomNavigator.UpdateButtons method to enable the timer used for Previous (nbPrior) and Next (nbNext) buttons.

Index
- the value from the enumerated type that specifies which button is being selected.

Button may be one of the following: nbFirst, nbPrior, nbNext, nbLast, nbInsert, nbDelete, nbEdit, nbPost, nbCancel, nbRefresh.

Implements a button used on a database navigator control.

TDBNavFocusableButton is a TBitBtn descendant which implements a button that can receive focus in a database navigator control. TDBNavFocusableButton is the type maintained in the FocusableButtons member in TDBCustomNavigator.

Contains styles and options that are enabled for the DB navigator button.

NavStyle is a TDBNavButtonStyle property with the set of style or options enabled for the focusable DB navigator button. Its values may be updated in the TDBCustomNavigator.UpdateButtons method.

Indicates the navigation button type for the button.

Index is an TDBNavButtonType value which indicates both the navigation button type for the button, and its ordinal position in the Buttons displayed for a TDBCustomNavigator / TDBNavigator control. The value for the property is assigned when the button is created in the UpdateButtons for the TDBCustomNavigator control.

TDBNavDataLink
- provides a link between a Database Navigator and a DataSet.

TDBNavDataLink is a TDataLink descendant used to maintain an association between a database navigator control, and a datasource with a dataset. It provides additional methods called when values assigned to the data link have been changed. An internal member is maintained with the TDBCustomNavigator control for the association.

TDataLink
EditingChanged
- method to process a change in the Editing property of the navigator.
DataSetChanged
- method to process a change in the data set attached to the navigator.

DataSetChanged is an overridden procedure in TDBNavDataLink which ensures that the DataChanged method in the internal TDBCustomNavigator control is called when the value in DataSet has been changed.

ActiveChanged does not call the inherited method.
ActiveChanged
- method to process a change in the Active property of the navigator.

ActiveChanged is an overridden procedure in TDBNavDataLink used to ensure that the Navigator control is updated when the value for the Active property has been changed.

ActiveChanged does not call the inherited method.
TDataLink.Active
Constructor for the class instance.

Create is the constructor for the class instance, and calls the inherited constructor. Create assigns the value in TheNavigator to an internal member used in the class instance. It also sets the value in the VisualControl property to True.

TDataLink
TDBCustomNavigator control for the data link.
TDBNavigator
- a data-aware Button-Bar to facilitate navigating between records of a dataset.

TDBNavigator is a tool used to navigate local datasets in a response to a query sent to the database. It consists of a series of toolbuttons used to perform navigation and maintenance for records in the linked dataset.

For example:

Navigation
  First, Prior, Next or Last
Maintenance
  Insert, Delete, Edit, Post, Cancel or Refresh

Use the VisibleButtons property to specify which of the Buttons can be displayed in the control.

If used in conjunction with a data-aware controls, it controls which record is displayed, the position of the record selection cursor, and the initiation of changes to the dataset and ultimately the database.

Most of the functionality of the toolbar is already built-in to the control, but if the programmer needs to specify actions to be associated with individual buttons, there is a procedure BtnClick to which an argument can be sent with the index value of the button clicked, and the procedure chooses which action to call dependent on the button index.

The DataSource property must be assigned to link to the dataset for the control.

How To Use Data-aware Controls
Contains the background color for the control.

Color is a TColor property with the background color for the control. The default value for the property is clBackground in TDBNavigator.

If the color is clDefault, the value will need to be resolved using the GetDefaultColor method. Convenience routines which obtain the color by resolving clDefault and ParentColor are also provided in TControl.GetColorResolvingParent and TControl.GetRGBColorResolvingParent.

TCustomPanel.Color TControl.ParentColor TControl.GetDefaultColor TControl.GetColorResolvingParent TControl.GetRGBColorResolvingParent
Enables or disables navigation using the Tab key.

The default value for the property is False in TDBNavigator.

TCustomPanel.TabStop
Performs actions needed when the datasource in a control with the specified data link is changed.

ChangeDataSource ensures that free notification messages are performed for the datasource in Link and the control in AControl. The value in NewDataSource is assigned to the DataSource property in Link.

Control notified in the routine.
Data link updated in the method.
Datasource assigned to the data link in the method.
Registers components in the unit for use in the Lazarus IDE.

Register is a procedure used to register components in the dbctrls.pp unit for use in the Lazarus IDE. Register adds the following components to the 'Data Controls' tab:

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

Register calls the RegisterField routine for each of the database field types in DefaultFieldClasses, as well as the TIntegerField type.

DefaultFieldClasses
HowToUseDataAwareControls
- Hints for accessing databases.

HowToUseDataAwareControls - Hints for accessing databases. A set of Data-Aware components is provided, to make it easier to access information held in databases.

Before using Data-Aware components, it is necessary to make a connection with a database, and this should be done either using a TSQLConnection or a TDbf component, depending on the type of database that is being used. In any case, the components for connection with the database need to be found in $Lazdir/components/sqldb/, $Lazdir/components/tdbf/ or whatever other source is appropriate. They need to be added using the Components Menu Item of the IDE, and compiled ready for adding. The IDE needs to be re-built to include the new components.

To make the connection with the database: first place a DataBase Connection on the Form (invisible at run-time, so put it anywhere convenient); set its properties to connect the user (with name and password) to the appropriate server, database and table (the connection component should deal with all the user-authentication issues, opening and closing the database etc). Then put on a TDataSource from the Data Access tab of the Component Palette, and perhaps items such as TSQLTransaction and TSQLQuery, depending on the particular database you are using. The various database components need to be linked to each other, for example by setting the Transaction property of a database connector to the appropriate transaction component, and linking the DataBase property of the Transaction component back to the database connector; link the DataSource's DataSet property to the appropriate SQLQuery or other set of data, and its Transaction property to the transaction component.

Each Data-Aware control (on the Data Controls tab of the Component Palette) has the usual set of properties to determine its shape and size, position, color and font etc. But there are also special properties to define the data to be displayed or modified. These include the DataSource property which must be set to link to the defined set of data, and often a Field component to determine which of the columns in the database is to be displayed.

Most of the components operate on a single Row or record of the database, but the TDBGrid is capable of displaying and operating on multiple rows and columns, in a StringGrid format, allowing the user to get an overview of what is in the database. The DBGrid will display the contents of the DataSet even at design time, provided the various components are enabled or rendered active; this allows the designer to ensure that all the connections to the database have been correctly made.

The TDBNavigator component is used in conjunction with the Data-Aware components. It consists of a series of buttons to allow browsing through the DataSet, displaying the first, previous, next or last record (or Row), inserting or deleting records, committing the changes back to the database or refreshing the DataSet from the database.

The way database programming works is typically as follows:

- a database is opened for access by the user (Database Connection)
- a command is issued (e.g. by TSQLQuery) to select or extract some or all of the records which are then stored locally in the DataSet
- the contents of the DataSet are acted on by the Data-Aware components, displaying one Row or record at a time from selected Columns, or perhaps the whole DataSet in a DBGrid, editing records, inserting or deleting records, or using the data to perform statistical tests or calculations
- at intervals usually prescribed by the user (sometimes after every change, sometimes after a whole series of changes), the contents of the local DataSet are sent back to the database, causing an update of the database's contents. This process is referred to as 'Commit' or 'Post' or sometimes as 'Update'

The programmer can determine which events are associated with a Commit action by supplying suitable event handlers for OnClick, OnChange, OnFinishedEdit etc.

The following table shows the approximate correspondence between conventional and data-aware control classes:

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

Standard controls can, of course, be used to display information from a database, but they lack the direct link with the DataSet and its navigation aids. The programmer must write explicit code to extract data from the DataSet and put it in the standard control.