Implements a database-aware version of the date/time picker control.

DBDateTimePicker.pas contains an implementation of the database-aware date/time picker control. It contains the TDBDateTimePicker control, descended from TCustomDateTimePicker, which adds properties and methods needed to read and write the date/time value for the control using a DataSource, DataField, and an internal TFieldDataLink class instance.

dbdatetimepicker.pas is part of DateTimeCtrls package for Lazarus.

Original Author:

Zoran Vučenović, January and February 2010. Зоран Вученовић, јануар и фебруар 2010.

LICENSE

Modified LGPL -- see the file COPYING.modifiedLGPL.

NO WARRANTY

There is no warranty whatsoever.

Original documentation is located on the Lazarus Wiki at:

DateTimeCtrls Package

Implements a database-aware version of the TDateTimePicker control.

TDBDateTimePicker is a TCustomDateTimePicker descendant which implements a database-aware date/time picker control.

Like TCustom DateTimePicker, it does not use the native Windows control. It has been tested on Windows with Win32/64 and QT widgetsets, as well as on Linux with QT and GTK2 widgetsets.

Please note that, like TDateTimePicker, the control does not descend from TEdit. As a result, it does not have the unnecessary caret just like its VCL counterpart.

The control allows the user to enter Date, Time, or DateTime values. It incorporates a button on the control to display a drop-down calendar for date values, or up and down buttons to increment and decrement the numeric values in a time. Individual parts in the date/time values can be changed using the Up and Down cursor keys, or by entering the value directly into the control.

It uses locale-specific settings to format and display date / time values by default, but allows these settings to be overridden. It ignores the BiDiMode setting when formatting date and time values, but does use the property to align the button(s) on the control.

TDBDateTimePicker adds properties and methods needed to read and write the date / time value for the control using a DataSource, DataField, and an internal TFieldDataLink class instance. It provides support for displaying and storing a value in a database field which has a null value.

TDBDateTimePicker sets the visibility for properties and events introduced in ancestor classes.

TCustomDateTimePicker
Performs actions needed when the value for the control has been changed.

Change is an overridden method in TDBDateTimePicker. It ensures that the field data link is assigned and changes have occurred in the date/ time value before it is stored to the linked dataset. No actions are performed in the method if either conditions is not met.

Change calls the Edit method in the field link to ensure that the field can be modified in the linked dataset. If Edit returns True, the field is in an edit state and ready for the modification. The inherited Change method is called to signal the OnChange event handlers assigned for the control. If Edit returns False, the Reset method in the data link is called to revert the field to its previous state.

TCustomDateTimePicker.Change TFieldDataLink
Validates and applies a user-specified date/time value for the control.

ConfirmChanges is an overridden method in TDBDateTimePicker. It calls the inherited method on entry to validate a user-specified values in the date / time parts before they are applied to the control.

See TCustomDateTimePicker.ConfirmChanges for the specific actions performed in the ancestor class.

In TDBDateTimePicker, it ensures that the internal field data link (TFieldDataLink) has been assigned before the updated value is written to the DataField. The modified value is not stored if the field data link has not been assigned (or is no longer valid) for the control. An exception which occurs when accessing the data link is caught and re-raised after focusing the control.

ConfirmChanges is called from the EditingDone method, and when the value for the ReadOnly property is changed.

TCustomDateTimePicker.ConfirmChanges TCustomDateTimePicker.DateTime TCustomDateTimePicker.Date TCustomDateTimePicker.Time TFieldDataLink
Reverts changes to the date/time value in the control and its linked dataset.

UndoChanges is an overridden method in TDBDateTimePicker. It calls the Reset method in the internal field data link (TFieldDataLink) when changes to the control have been cancelled or undone. This reloads the date / time value from the DataField in the DataSource.

UndoChanges calls the inherited method prior to exit to update the TDateTime value for the control.

TCustomDateTimePicker.UndoChanges TCustomDateTimePicker.DateTime TCustomDateTimePicker.Date TCustomDateTimePicker.Time TFieldDataLink.Reset
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. It allocates resources for the internal TFieldDataLink in the class instance, and assigns private methods in the class which implement handler routines to the event handlers in the field link.

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

Destroy is the overridden destructor for the class instance. It clears the event handlers and frees the internal field link used in the class instance. It calls the inherited method prior to exit to free the class instance.

Provides access to the TField instance for the date/time value in the linked dataset.

Field is a read-only TField property which provides access to the field where the date/time value is stored in the linked dataset. The value for the property is read from the Field property in the internal TFieldDataLink instance used in the class.

Name for the field where the date/time value is stored in the linked dataset.

DataField is a String property which contains the name for the field used to read and write the TDateTime value for the control. The property value is read from and written to the internal field data link (TFieldDataLink) used in the class instance.

Changing the value for the property causes the DataSource to be checked for a valid field with the specified name. The dataset in DataSource must be active to validate the TField instance. ReadOnly is updated to reflect whether the dataset is active and the field name is valid. The TDateTime value for the control is set to NullDate if the dataset is closed or field name is not a valid field in the dataset.

TCustomDateTimePicker.DateTime TCustomDateTimePicker.Date TCustomDateTimePicker.Time NullDate TFieldDataLink TDataSource TDataSet TField
Provides access to the dataset and field for the date/time value.

DataSource is a TDataSource property which provides access to the dataset and the field where the TDateTime value for the control is stored. It acts as a mediator to handle communication between the database-aware control and its dataset. The value for the property is read from and written to the internal field data link (TFieldDataLink) instance used in the class.

Changing the value for the property causes the dataset to be checked for a valid field with the specified name. The dataset in DataSource must be active to validate the TField instance. ReadOnly is updated to reflect whether the dataset is active and the field name is valid. The TDateTime value for the control is set to NullDate if the dataset is closed or field name is not a valid field in the dataset.

Use DataField to specify the name of the field where the date / time value is stored.

NullDate TFieldDataLink TDataSource TDataSet TField
Indicates whether the data/time value can be modified using the control.

ReadOnly is a Boolean property which indicates whether the TDateTime value for the control can be changed. It reintroduces the property from the ancestor class with an overridden write specifier to validate the Field and Dataset in the DataSource.

ReadOnly may be automatically set to False if the dataset for the control is not active or does not allow changes. It may also be set to False if a value specified for the DataSource or DataField properties is not valid, and when Active is changed to False.

Set ReadOnly to False to prevent the value from being changes at run-time through interaction with the control.

TFieldDataLink TDataSource TDataSet TField
Set type with the optional features or behaviors enabled for the control.

Options is a published TDateTimePickerOptions in TDBDateTimePicker. It is a set type with the optional features or behaviors enabled for the control.

dtpoDoChangeOnSetDateTime
  Allows the OnChange handler to be called also when DateTime is changed in program code. This option cannot be used for its intended purpose in TDBDateTimePicker. The DateTime, Date, and Time properties are not visible for the database-aware control, and cannot be changed in program code. The linked dataset is used to update the value for the control, and the change event occurs for the dataset and not the control. OnChange is still signalled in the control, but only when the user interacts with the date/time parts on the control.
dtpoEnabledIfUnchecked
  Enables the date time picker if the check box is unchecked.
dtpoAutoCheck
  Auto-checks an unchecked check box when DateTime is changed (makes sense only if dtpoEnabledIfUnchecked is set).
dtpoFlatButton
  Use a flat appearance for the button on the control.
dtpoResetSelection
  When the control receives focus, the selection is always in the first date/ time part (the control does not remember which part was previously selected).

Use properties like ShowCheckBox, AutoButtonSize, ArrowShape, and DateMode to control the appearance for the button(s) on the control.

Added in LCL version 3.0.
TCustomDateTimePicker.ShowCheckBox TCustomDateTimePicker.Options TDateTimePickerOptions TDateTimePickerOption