DateControls Package for Lazarus

From Free Pascal wiki
Jump to: navigation, search

These controls are now obsolete. The controls in DateTimeCtrls Package have improved functionality and completely cover the functionality of these!

Author

Zoran Vučenović

Introduction

DateControls package contains two controls:

TDatePicker.PNG TDatePicker and TDBDatePicker.PNGTDBDatePicker

These controls are now obsolete. The controls in DateTimeCtrls Package have improved functionality and completely cover the functionality of these!

Delphi's VCL has a control named TDateTimePicker, which I find very useful for editing dates. LCL, however, does not have this control. Instead, for editing dates LCL has a control named TDateEdit, but I prefer the VCL's TDateTimePicker.


Therefore, I tried to create a cross-platform Lazarus control which would resemble VCL's TDateTimePicker as much as possible.


The TDatePicker control does not use native Win control. It descends from LCL-s TCustomControl to be cross-platform. It has been written and initially tested on Windows XP with Win widgetset, but then tested on Ubuntu Linux 9.10 with gtk2 widgetset, where additional adjustments had been made.

Thanks to Željko Rikalo, its tested on qt and adjusted to be fully functional to qt users.


Note that the TDatePicker control does not descend from TEdit, so it does not have unnecessary caret. The VCL's control doesn't have caret either.


Unlike VCL's control, this control has no time editing feature. It can be used for date editing only. That's why it is named TDatePicker, not TDateTimePicker.

Downloading and installing

Lazarus package DateControls.lpk can be downloaded from here, packed in zip format.

After downloaded, unzip the package.

To install the package in Lazarus IDE follow these steps:

  1. Open the package in Package Editor (in Lazarus' main menu click Package, then Open package file... locate the file datecontrols.lpk and click Open).
  2. Compile the package (click Compile in Package Editor's tool bar).
  3. Install the package in the IDE (click Install – you will be asked if you want to rebuild Lazarus, click Yes. Wait until Lazarus rebuilds and restarts itself. The new tab DateControls appears on the component palette with TDatePicker and TDBDatePicker controls.

TDatePicker TDatePicker.PNG

properties

I'll explain some properties of TDatePicker control:

TheDate: TDateTime

The date displayed on the control. This property is named TheDate, not Date, to avoid name conflict with Date function.

MinDate: TDateTime

The minimal date user can enter.

MaxDate: TDateTime

The maximal date user can enter.

NullInputAllowed: Boolean

When True, the user can set the date to NullDate constant by pressing N key.

CenturyFrom: Word

When user enters the year in two-digit format, then the CenturyFrom property is used to determine which century the year belongs to. The default is 1941, which means that when two digit years is entered, it falls in interval 1941 – 2040. Note that MinDate and MaxDate properties can also have influence on the decision – for example, if the CenturyFrom is set to 1941 and MaxDate to 31. 12. 2010, if user enters year 23, it will be set to 1923, because it can’t be 2033, due to MaxDate limit.

ShowCalendar: Boolean

When set to True, there is a button on the right side of the control. When user clicks the button, the calendar control is shown, allowing the user to pick the date.
ShowCalendar.PNG

ShowCheckBox: Boolean

When set, there is a check box on the left side of the control. When unchecked, the display appears grayed and user interaction with the date is not possible. (The control is still enabled, though, only in sense that the check box remains enabled).
ShowCheckBox.PNG

Checked: Boolean

If ShowCheckBox is set to True, this property determines whether the check box is checked or not. If ShowCheckBox is False, this property has no purpose and is automatically set to True.

DateDisplayOrder: TDateDisplayOrder

type TDateDisplayOrder = (ddoDMY, ddoMDY, ddoYMD, ddoTryDefault);
Defines the order for displaying day, month and year part of the date. When ddoTryDefault is set, then the controls tries to determine the order from ShortDateFormat global variable.
This is similar to DateEdit's DateOrder property.

TheDateSeparator: UTF8String

Defines the string used to separate date, month and year date parts. Setting this property automatically sets the UseDefaultDateSeparator property to False. This property is named TheDateSeparator, not DateSeparator, to avoid name conflict with DateSeparator global variable.

UseDefaultDateSeparator: Boolean

When UseDefaultDateSeparator is set to True, TheDateSeparator property is set to DateSeparator global variable.

TrailingSeparator: Boolean

When set to True, then TheDateSeparator is shown once more, after the last date part. This property exists because in some languages the correct format is 31. 1. 2010. including the last point, after the year.

LeadingZeros: Boolean

Determines whether the date parts are displayed with or without leading zeros.

TextForNullDate: UTF8String

Text which appears when the null date is set and control does not have focus. When control is focused, the text changes to defined format, but displaying zeros, which is appropriate to user input. User can set the date to NullDate by pressing N key, provided NullInputAllowed property is True.


TDBDatePicker TDatePicker.PNG

TDBDatePicker is a data-aware version of TDatePicker, with nice way of handling null database values.

Handling of null values

Displaying null values

When the underlying DB field has null value, then:
If the control is not focused, then it displays the text defined in TextForNullDate property. The default is "NULL".
When the control gets focus, the text changes to defined format, but displaying zeros (for example "00/00/0000"), which is appropriate to user input.

Setting the field value to null

If NullInputAllowed property is True, the user can set the date to null, by pressing N key.

See also