lazarus/docs/xml/lcl/dbextctrls.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--

Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus 
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0 
International public license.

https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/docs/cc-by-sa-4-0.txt

Copyright (c) 1997-2025, by the Lazarus Development Team.

-->
<fpdoc-descriptions>
<package name="lcl">

<!-- DBExtCtrls -->
<module name="DBExtCtrls">
<short>Contains extended database controls.</short>
<descr>
<p>
<file>dbextctrls.pp</file> contains extended database-aware controls used in 
the Lazarus Component Library (<b>LCL</b>).
</p>
<p>
The following components are added to the Lazarus IDE component palette:
</p>
<p>
<b>Data Controls</b> Tab
</p>
<ul>
<li>TDBDateEdit</li>
</ul>
<p>
It also registers TFieldClass instances (defined in DefaultFieldClasses) 
associated with FCL database field types, and includes TIntegerField as an 
alias for TLongintField.
</p>
</descr>

<!-- unresolved type reference visibility: default -->
<element name="Classes"/>
<element name="SysUtils"/>
<element name="LCLType"/>
<element name="LMessages"/>
<element name="DB"/>
<element name="DBCtrls"/>
<element name="EditBtn"/>

<!-- class Visibility: default -->
<element name="TDBDateEdit">
<short>
TDBDateEdit implements a data-aware editing control for a date field in a 
dataset.
</short>
<descr>
<p>
<var>TDBDateEdit</var> is a <var>TDateEdit</var> descendant that implements a 
data-aware edit control for a Date field in a dataset. Like its ancestor 
class, TDBDateEdit includes a Button which opens a Date selection dialog 
(calendar).
</p>
<p>
TDBDateEdit extends the ancestor class to provide support for 
<var>TFieldDataLink</var>, <var>TDataSource</var>, and <var>TField</var> 
which provide access to the dataset with the data for the editing control. 
Overridden methods are provided which handle keystrokes and synchronize 
changes in the control with the field in a dataset. Support for 
<var>TBasicAction</var> is also included in TDBDateEdit.
</p>
</descr>
<seealso>
<link id="#lcl.editbtn.TDateEdit">TDateEdit</link>
<link id="#lcl.dbctrls.TFieldDataLink">TFieldDataLink</link>
<link id="#fcl.db.TField">TField</link>
<link id="#fcl.db.TDatasource">TDatasource</link>
<link id="#rtl.classes.TBasicAction">TBasicAction</link>
</seealso>
</element>

<!-- variable Visibility: private -->
<element name="TDBDateEdit.FDataLink" link="#lcl.dbctrls.TFieldDataLink"/>

<!-- procedure Visibility: private -->
<element name="TDBDateEdit.DataChange">
<short>
Gets the value for the control when its Field has changed.
</short>
<descr>
<p>
<var>DataChange</var> is a procedure used to get the value for the control 
when the value in its Field has changed. <var>DataLink</var> must contain a 
value (not Nil) to access the Field. When DataLink is unassigned, the value 
in Text is set to an empty string <var>('')</var>.
</p>
<p>
DataChange stores the value from the <var>TField</var> instance in DataLink 
in the <var>Date</var> property. If the control is Focused and AutoSelect is 
enabled, the SelectAll method is called to select the content in the control.
</p>
<p>
DataChange is assigned as the OnDataChange event handler for DataLink in 
Create.
</p>
</descr>
<seealso>
<link id="TDBDateEdit.Field"/>
<link id="#lcl.dbctrls.TFieldDataLink.Field">TFieldDataLink.Field</link>
<link id="#lcl.dbctrls.TFieldDataLink.OnDataChange">TFieldDataLink.OnDataChange</link>
</seealso>
</element>
<!-- argument Visibility: private -->
<element name="TDBDateEdit.DataChange.Sender">
<short>Class signalling the data change.</short>
</element>

<!-- procedure Visibility: private -->
<element name="TDBDateEdit.UpdateData">
<short>
Updates the field in a dataset when the value for the control has changed.
</short>
<descr>
<p>
<var>UpdateData</var> is a procedure which updates the field in a dataset 
when the value for the control has been changed. UpdateData uses the value in 
Text to determine if the control has no value. When Text contains an empty 
string <var>('')</var>, the Field in DataLink calls its Clear method. 
Otherwise, the value in Date is stored in the Field for the DataLink.
</p>
<p>
UpdateData is assigned as the OnUpdateData event handler for DataLink in 
Create.
</p>
</descr>
<seealso>
<link id="TDBDateEdit.Field"/>
<link id="#lcl.dbctrls.TFieldDataLink.Field">TFieldDataLink.Field</link>
<link id="#lcl.dbctrls.TFieldDataLink.OnUpdateData">TFieldDataLink.OnUpdateData</link>
</seealso>
</element>
<!-- argument Visibility: private -->
<element name="TDBDateEdit.UpdateData.Sender">
<short>Class signalling the update.</short>
</element>

<!-- function Visibility: private -->
<element name="TDBDateEdit.GetDataField">
<short>
Gets the value for the DataField property.
</short>
<descr>
<p>
<var>GetDataField</var> is a String function used to get the value for the 
<var>DataField</var> property. GetDataField is the read access specifier for 
the property value. The return value is retrieved from the FieldName property 
in <var>DataLink</var>.
</p>
<p>
Use <var>DataField</var> to read or write the name of the field used to store 
the Date value in the dataset.
</p>
</descr>
<seealso>
<link id="TDBDateEdit.Field"/>
<link id="TDBDateEdit.DataSource"/>
</seealso>
</element>
<!-- function result Visibility: private -->
<element name="TDBDateEdit.GetDataField.Result">
<short>Value for the DataField property.</short>
</element>

<!-- function Visibility: private -->
<element name="TDBDateEdit.GetDataSource">
<short>
Gets the value for the DataSource property.
</short>
<descr>
<p>
<var>GetDataSource</var> is a <var>TDataSource</var> function used to get the 
value for the <var>DataSource</var> property. GetDataSource is the read 
access specifier for the property value. The return value contains the 
<var>DataSource</var> assigned in the DataLink property.
</p>
<p>
Use DataSource to read or write the value in the property.
</p>
</descr>
<seealso>
<link id="#lcl.dbctrls.TFieldDataLink">TFieldDataLink</link>
<link id="#fcl.db.TDatasource">TDatasource</link>
</seealso>
</element>
<!-- function result Visibility: private -->
<element name="TDBDateEdit.GetDataSource.Result">
<short>Value for the DataSource property.</short>
</element>

<!-- procedure Visibility: private -->
<element name="TDBDateEdit.SetDataField">
<short>
Sets the value for the DataField property.
</short>
<descr>
<p>
<var>SetDataField</var> is a procedure used to set the value in the 
<var>DataField</var> property. SetDataField is the write access specifier for 
the property value. SetDataField stores the specified new Value in the 
<var>FieldName</var> property for <var>DataLink</var>.
</p>
<p>
Use <var>DataField</var> to read or write the value for the property.
</p>
</descr>
<seealso>
<link id="TDBDateEdit.DataField"/>
<link id="TDBDateEdit.Field"/>
<link id="TDBDateEdit.DataSource"/>
</seealso>
</element>
<!-- argument Visibility: private -->
<element name="TDBDateEdit.SetDataField.Value">
<short>Value for the DataField property.</short>
</element>

<!-- procedure Visibility: private -->
<element name="TDBDateEdit.SetDataSource">
<short>
Sets the value for the DataSource property.
</short>
<descr>
<p>
<var>SetDataSource</var> is a procedure used to set the value for the 
DataSource property. SetDataSource is the write access specifier for the 
property value. SetDataSource calls ChangeDataSource to store the specified 
new Value in DataLink.
</p>
<p>
Use DataSource to read or write the value in the property.
</p>
</descr>
<seealso>
<link id="#lcl.dbctrls.TFieldDataLink">TFieldDataLink</link>
<link id="#fcl.db.TDatasource">TDatasource</link>
</seealso>
</element>
<!-- argument Visibility: private -->
<element name="TDBDateEdit.SetDataSource.Value">
<short>Value for the DataSource property.</short>
</element>

<!-- procedure Visibility: private -->
<element name="TDBDateEdit.CMGetDataLink">
<short>
Responds to the CM_GETDATALINK control message.
</short>
<descr>
<p>
<var>CMGetDataLink</var> is a procedure which responds to the CM_GETDATALINK 
control message. CMGetDataLink ensures that Message is updated to contain a 
pointer to the DataLink instance in its result.
</p>
</descr>
<seealso>
</seealso>
</element>
<!-- argument Visibility: private -->
<element name="TDBDateEdit.CMGetDataLink.Message">
<short>Message for the control notification.</short>
</element>

<!-- function Visibility: private -->
<element name="TDBDateEdit.GetField">
<short>
Gets the value for the Field property.
</short>
<descr>
<p>
<var>GetField</var> is a TField function used to get the value for the Field 
property. GetField is the read access specifier for the property value. 
GetField uses the value in the Field property in DataLink as the return value 
for the method.
</p>
<p>
Use Field to read the value in the property.
</p>
</descr>
<seealso>
<link id="TDBDateEdit.Field"/>
</seealso>
</element>
<!-- function result Visibility: private -->
<element name="TDBDateEdit.GetField.Result">
<short>Value for the Field property.</short>
</element>

<!-- procedure Visibility: protected -->
<element name="TDBDateEdit.Notification">
<short>
Handles notifications when a component is added or removed.
</short>
<descr>
<p>
<var>Notification</var> is an overridden procedure used to handle 
notifications performed when aComponent is added or removed. Notification 
calls the inherited method. When Operation contains opRemove, and AComponent 
is the DataSource for the control, the value in DataSource is set to Nil.
</p>
</descr>
<seealso>
</seealso>
</element>
<!-- argument Visibility: protected -->
<element name="TDBDateEdit.Notification.AComponent">
<short>Component for the notification event.</short>
</element>
<!-- argument Visibility: protected -->
<element name="TDBDateEdit.Notification.Operation">
<short>Operation for the notification event.</short>
</element>

<!-- function Visibility: protected -->
<element name="TDBDateEdit.EditCanModify">
<short>
Indicates if the control can modify its contents.
</short>
<descr>
<p>
<var>EditCanModify</var> is an overridden Boolean function which indicates if 
the control can modify the content for the control. EditCanModify is set to 
the value from CanModify in DataLink. The return value is <b>True</b> when 
the control accept new values.
</p>
</descr>
<seealso>
</seealso>
</element>
<!-- function result Visibility: protected -->
<element name="TDBDateEdit.EditCanModify.Result">
<short><b>True</b> when the control value can be changed.</short>
</element>

<!-- procedure Visibility: protected -->
<element name="TDBDateEdit.EditEnter">
<short>
Performs actions required when the Enter key is pressed on the control.
</short>
<descr>
<p>
<var>EditEnter</var> is an overridden procedure used to perform actions 
required when the Enter key is pressed on the control. EditEnter calls the 
inherited method.
</p>
<p>
EditEnter uses the value from Editing in DataLink to determine if there are 
any pending changes in the control value. When Editing contains <b>False</b>, 
the Reset method in DataLink is called to cancel changes to the field. Reset 
also calls the OnDataChange event handler.
</p>
</descr>
<seealso>
</seealso>
</element>

<!-- procedure Visibility: protected -->
<element name="TDBDateEdit.EditKeyDown">
<short>
Handles special keys in the keydown state.
</short>
<descr>
<p>
<var>EditKeyDown</var> is an overridden procedure used to perform actions 
required when special keys are in the down state in the control. EditKeyDown 
handles the following virtual key values:
</p>
<dl>
<dt>VK_ESCAPE</dt>
<dd>
Cancels editing (when active) and calls Reset in DataLink. Key is changed to 
the value VK_UNKNOWN
</dd>

<dt>VK_DELETE or VK_BACK</dt>
<dd>
Removes Delete and Backspace keys if editing is not active.Changes Key to the 
value VK_UNKNOWN when editing is not active.
</dd>
</dl>
</descr>
<seealso>
</seealso>
</element>
<!-- argument Visibility: protected -->
<element name="TDBDateEdit.EditKeyDown.Key">
<short>Numeric value for the key.</short>
</element>
<!-- argument Visibility: protected -->
<element name="TDBDateEdit.EditKeyDown.Shift">
<short>Shift state for the key.</short>
</element>

<!-- procedure Visibility: protected -->
<element name="TDBDateEdit.EditKeyPress">
<short>
Ensures character values are valid for the control.
</short>
<descr>
<p>
<var>EditKeyPress</var> is an overridden procedure which processes the 
character value in Key. EditKeyPress calls the inherited method. EditKeyPress 
checks the value in Key to see if it contains data (as opposed to control 
characters) in the range Decimal 32 to Decimal 255. The Field property in 
DataLink also calls its IsValidChar method to see if Key is valid for the 
data type in the Field.
</p>
<p>
EditKeyPress requires DataLink to have both a valid TField instance in its 
Field property and its Edit property set to <b>True</b>. The value in Key is 
set to <var>#0 (Decimal 0)</var> if either condition is not met.
</p>
</descr>
<seealso>
</seealso>
</element>
<!-- argument Visibility: protected -->
<element name="TDBDateEdit.EditKeyPress.Key">
<short>Character value for the key.</short>
</element>

<!-- procedure Visibility: protected -->
<element name="TDBDateEdit.ButtonClick">
<short>
Actions performed when the button for the control is clicked.
</short>
<descr>
<p>
<var>ButtonClick</var> is an overridden procedure which performs
actions when the button for the control is clicked. ButtonClick ensures that 
the control is Focused, and calls SetFocus when necessary. The CanModify 
property in DataLink is checked to see if the Edit method in DataLink is 
needed. ButtonClick calls the inherited method.
</p>
</descr>
<seealso>
</seealso>
</element>

<!-- procedure Visibility: protected -->
<element name="TDBDateEdit.EditChange">
<short>
Signals the control changed state.
</short>
<descr>
<p>
<var>EditChange</var> is an overridden procedure which which signals the 
control is changed. EditChange ensures that the control updates its DataLink 
to indicate the change status. EditChange uses the Editing property in 
DataLink to see if the Modified method in DataLink is needed. EditChange 
calls the inherited method.
</p>
</descr>
<seealso>
<link id="#lcl.dbctrls.TFieldDataLink">TFieldDataLink</link>
<link id="#lcl.dbctrls.TFieldDataLink.Editing">TFieldDataLink.Editing</link>
<link id="#lcl.dbctrls.TFieldDataLink.Modified">TFieldDataLink.Modified</link>
</seealso>
</element>

<!-- procedure Visibility: protected -->
<element name="TDBDateEdit.EditExit">
<short>
Performs actions needed when the exiting the control.
</short>
<descr>
<p>
<var>EditExit</var> is an overridden procedure performs actions needed when 
the exiting the control. EditExit calls the inherited method. EditExit 
ensures that the value in the control is applied to DataLink. When Editing is 
set in DataLink, its UpdateRecord method is called to apply the new value. If 
Editing is not set, its Reset method is called restore its value and state.
</p>
</descr>
<seealso>
<link id="#lcl.dbctrls.TFieldDataLink">TFieldDataLink</link>
<link id="#lcl.dbctrls.TFieldDataLink.Editing">TFieldDataLink.Editing</link>
<link id="#lcl.dbctrls.TFieldDataLink.Reset">TFieldDataLink.Reset</link>
</seealso>
</element>

<!-- procedure Visibility: protected -->
<element name="TDBDateEdit.Reset">
<short>
Restores the control to its value in the dataset.
</short>
<descr>
<p>
<var>Reset</var> is a procedure used to restore the control to its value in 
the dataset. Reset calls the Reset method in DataLink to get the value stored 
in its Field and to clear the Editing flag. Reset calls the inherited method 
prior to exit.
</p>
</descr>
<seealso>
<link id="#lcl.dbctrls.TFieldDataLink">TFieldDataLink</link>
<link id="#lcl.dbctrls.TFieldDataLink.Editing">TFieldDataLink.Editing</link>
<link id="#lcl.dbctrls.TFieldDataLink.Reset">TFieldDataLink.Reset</link>
</seealso>
</element>

<!-- constructor Visibility: public -->
<element name="TDBDateEdit.Create">
<short>Constructor for the object instance.</short>
<descr>
<p>
<var>Create</var> is the overridden constructor for the object instance. 
Create call the inherited constructor using AOwner as the owner for the 
object instance. Create allocates resources needed for the DataLink property, 
and sets the event handlers for its OnDataChange and OnUpdateData properties 
to the DataChange and UpdateData methods in the class instance.
</p>
</descr>
<seealso>
<link id="#lcl.dbctrls.TFieldDataLink">TFieldDataLink</link>
<link id="#lcl.dbctrls.TFieldDataLink.OnDataChange">TFieldDataLink.OnDataChange</link>
<link id="#lcl.dbctrls.TFieldDataLink.OnUpdateData">TFieldDataLink.OnUpdateData</link>
</seealso>
</element>
<!-- argument Visibility: public -->
<element name="TDBDateEdit.Create.AOwner">
<short>Owner of the object instance.</short>
</element>

<!-- destructor Visibility: public -->
<element name="TDBDateEdit.Destroy">
<short>
Frees the object instance.
</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the object instance. 
Destroy frees resources allocated for the DataLink property, and calls the 
inherited Destroy method.
</p>
</descr>
<seealso>
</seealso>
</element>

<!-- function Visibility: public -->
<element name="TDBDateEdit.ExecuteAction">
<short>
Perform the default action for the control.
</short>
<descr>
<p>
<var>ExecuteAction</var> is an overridden Boolean function which implements 
support for using TBasicAction to perform the default action for the control. 
ExecuteAction calls the inherited method using the value in AAction. If the 
action is not handled in the ancestor, DataLink is used (when assigned) to 
performs its ExecuteAction method with the specified action value. The return 
value is <b>True</b> if the action is handled by the ancestor or DataLink.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TBasicAction">TBasicAction</link>
<link id="#lcl.forms.TApplication.OnActionExecute">TApplication.OnActionExecute</link>
</seealso>
</element>
<!-- function result Visibility: public -->
<element name="TDBDateEdit.ExecuteAction.Result">
<short><b>True</b> if the action is successfully handled.</short>
</element>
<!-- argument Visibility: public -->
<element name="TDBDateEdit.ExecuteAction.AAction">
<short>Action to perform.</short>
</element>

<!-- function Visibility: public -->
<element name="TDBDateEdit.UpdateAction">
<short>Updates the action when it handles the specified operation.</short>
<descr>
<p>
<var>UpdateAction</var> is an overridden Boolean function which implements 
support for using TBasicAction to update the value in the control from its 
dataset. UpdateAction calls the inherited method using the value in AAction. 
If the action is not handled in the ancestor, DataLink is used (when 
assigned) to perform its UpdateAction method with the specified action value. 
The return value is <b>True</b> if the action is handled by the ancestor or 
DataLink.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TBasicAction">TBasicAction</link>
</seealso>
</element>
<!-- function result Visibility: public -->
<element name="TDBDateEdit.UpdateAction.Result">
<short><b>True</b> if the action is successfully handled.</short>
</element>
<!-- argument Visibility: public -->
<element name="TDBDateEdit.UpdateAction.AAction">
<short>Action to perform.</short>
</element>

<!-- property Visibility: public -->
<element name="TDBDateEdit.Field">
<short>
TField class which reads and writes data for the control.
</short>
<descr>
<p>
<var>Field</var> is a read-only TField property which reads and writes data 
for the control in its dataset. Field is a convenience method which returns 
the TField instance from the DataLink for the control. GetField is the read 
access specifier for the property.
</p>
<p>
The value in Field cannot be assigned directly; use DataField to specify the 
field name for the editing control. Use DataSource to set the dataset used 
for data in the control.
</p>
</descr>
<seealso>
<link id="TDBDateEdit.DataField"/>
<link id="TDBDateEdit.DataSource"/>
<link id="#lcl.dbctrls.TFieldDataLink">TFieldDataLink</link>
<link id="#fcl.db.TField">TField</link>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TDBDateEdit.DataField">
<short>
Name of the field in the dataset.
</short>
<descr>
<p>
<var>DataField</var> is a String property that provides the name of the field 
used to store the Date value in its Dataset. GetDataField is the read access 
specifier for the property value. SetDataField is the write access specifier 
for the property value. These methods read and write the value in FieldName 
for the DataLink.
</p>
<p>
Use DataSource and DataField to provide the dataset and field name for the 
control.
</p>
</descr>
<seealso>
<link id="TDBDateEdit.DataField"/>
<link id="TDBDateEdit.DataSource"/>
<link id="#lcl.dbctrls.TFieldDataLink">TFieldDataLink</link>
</seealso>
</element>

<!-- property Visibility: published -->
<element name="TDBDateEdit.DataSource">
<short>
Provides access to the dataset used for the editing control.
</short>
<descr>
<p>
<var>DataSource</var> is a TDataSource property which provides access to the 
dataset used for the editing control. GetDataSource is the read access 
specifier for the property, and uses the DataSource in DataLink as the 
property value. SetDataSource is the write access specifier for the property, 
and sets the DataSource in DataLink to the specified value.
</p>
</descr>
<seealso>
<link id="#lcl.dbctrls.TFieldDataLink">TFieldDataLink</link>
<link id="#fcl.db.TDatasource">TDatasource</link>
</seealso>
</element>

<element name="Register">
<short>Registers components for use in the Lazarus IDE.</short>
<descr>
<p>
The following components are added to the Lazarus IDE component palette:
</p>
<p>
<b>Data Controls</b> Tab
</p>
<ul>
<li>TDBDateEdit</li>
</ul>
</descr>
</element>

</module>
<!-- DBExtCtrls -->

</package>
</fpdoc-descriptions>