This document covers the following topics:
A date and time picker (DTP) control is used to simplify the input of date or time information for the user. A DTP control appears and behaves similarly to a spin control for the input of times and optionally as either a spin control or selection box for the input of dates. In the latter case, a month calendar appears instead of the typical list box when the user clicks on the button displaying the down arrow.
By default, the date and time information is displayed according to the date and time
formats defined for the current regional settings. Because Windows provides two
alternative date formats, one long and one short (both of which may be changed by the
user), and because the short date format may not contain century information, one of three
STYLE flags determines which of the standard
date formats should be used. These (mutually exclusive) formats are:
"Short date (s)", implying that the standard short date format for the current regional settings should be used.
"Century date (c)", implying that the standard short date format for the current regional settings should be used, but extended to provide century information if this is not already the case. Note that in many cases, the short date format already includes century information, in which case this style does not change the appearance of the date.
"Long date (d)", implying that the standard long date format for the current regional settings should be used
In addition. The "Time (t)" style flag is provided in order to indicate that the control should display time (instead of date) information.
If these standard formats are not sufficient, they can be overridden by proving a custom
format string using the EDIT-MASK attribute. Note, however, that
the format string specifiers do not correspond to those used for edit masks elsewhere
within Natural. The following table lists the available specifiers and their meanings:
| Specifier | Description |
|---|---|
| d | The one- or two-digit day. |
| dd | The two-digit day. Single-digit day values are preceded by a zero. |
| ddd | The three-character weekday abbreviation. |
| dddd | The full weekday name. |
| h | The one- or two-digit hour in 12-hour format. |
| hh | The two-digit hour in 12-hour format. Single-digit values are preceded by a zero. |
| H | The one- or two-digit hour in 24-hour format. |
| HH | The two-digit hour in 24-hour format. Single-digit values are preceded by a zero. |
| m | The one- or two-digit minute. |
| mm | The two-digit minute. Single-digit values are preceded by a zero. |
| s | The one- or two-digit second. |
| ss | The two-digit second. Single-digit values are preceded by a zero. |
| M | The one- or two-digit month number. |
| MM | The two-digit month number. Single-digit values are preceded by a zero. |
| MMM | The three-character month abbreviation. |
| MMMM | The full month name. |
| t | The one-letter AM/PM abbreviation (that is, AM is displayed as A). |
| tt | The two-letter AM/PM abbreviation (that is, AM is displayed as AM). |
| yy | The last two digits of the year (that is, 2005 would be displayed as 05). |
| yyyy | The full year (that is, 2005 would be displayed as 2005). |
In addition, any characters in quotes are displayed exactly as specified. To specify the quote character itself within a quoted string, two consecutive single quote characters should be used. Spaces and punctuation marks (such as the comma) do not need to be quoted.
For example, in order to display the string "John's birthday is Friday,
December 31, 1969", the DTP control's EDIT-MASK attribute would be set to
"John' 's birthday is' dddd, MMMM d, yyyy".
The DTP control provides several ways of modifying the specified information:
By the user, by entering numerical information (day numbers, etc.) directly.
By the user, by incrementing or decrementing the selected field (e.g. day number, month name) via the + or - keys, respectively.
By the user, if the DTP control has either the "Time (t)" or "Up-down (u)" style, by selecting the required field and incrementing or decrementing the value via the up-down ("spin") control.
By the user, if the DTP control is using a month calendar, by pressing the down arrow to open the month calendar and navigating to the required date. Unlike the above method, this method updates all date fields simultaneously.
Programmatically, by updating the TIME attribute with the required date
or time.
For example, to set the date or time in a DTP control to the current date or time, use the following assignments:
#DTP-1.TIME := *DATX
or
#DTP-1.TIME := *TIMX
respectively, where #DTP-1 is assumed to be the handle of the DTP
control.
Note that the DTP control stores both date and time information, even though it only allows editing of the date or time component, depending on the control's style.
If the DTP control's date or time is modified by the user, a CHANGE
event is raised for the control (if not suppressed). This does not happen if the DTP control is
modified programmatically.
If the "Allow 'no value' (n)" style is specified for the DTP
control, the control displays a check box. If this check box is unchecked, the
interpretation is that there is no date or time associated with the control. The
application can test for this state by querying the control's CHECKED attribute. It can also revert the
control to the "no value" state by setting the CHECKED attribute back to
UNCHECKED. Note that it is, however, not possible to
explicitly set the CHECKED attribute to CHECKED,
as this is done implicitly whenever a date or time is applied to the control. Furthermore,
the CHECKED attribute may not be set at all for
DTP controls without the "Allow 'no value' (n)" style.
The colors and font used by the month calendar (if any) associated with the DTP control
may be changed by use of the SET-AUX-COLOR and SET-AUX-FONT actions, respectively.
