This document covers the following topics:
A spin control consists of a pair of vertically-opposed arrow buttons known as an "up-down" control, optionally with an associated input field control known as a "buddy" control. The spin control has an associated integer range and current position. The buddy control (if present) displays the contents relating to the current position. The current position may be changed either by using the arrow buttons, the up and down cursor keys, or by typing the value directly into the buddy input field (if available and modifiable).
The up-down control allows the user to explicitly scroll through the
spin control's integer range. The up-down control's buttons can also be
implicitly selected by using the up arrow and down arrow cursor keys. Holding
down the button or key causes the value to be incremented or decremented
repeatedly, cycling round to the opposite end of the range when the
corresponding limit is reached, if the control's "Wrap
(w)" style is set. Initially, the incrementation or
decrementation step is 1, but this increases after a few seconds. This
acceleration may be disabled or modified via the
SET-ACCELERATION
action.
The control's range may be defined by setting its
MIN and
MAX
attributes. The control's current position within this range may be
programmatically set or obtained by setting or querying the
POSITION
attribute value, respectively.
Whenever the current position is changed by the user, a
CHANGE
event is raised for the control (if not suppressed). This event is
not raise if the control's value is changed programatically. Alternatively, if
a buddy input field control is present, the
CHANGE
event of the buddy control can be used.
If the control's "Left align (l)" or "Right align (r)" style flag is set, the spin control contains an input field, known as the buddy control, which on the right or left of the up-down control respectively (the alignment relates to the up-down control, not to the buddy control).
The buddy control is a child of the spin control, and appears as a standard Natural input field control. This gives the Natural programmer access to all the features available for standalone input field controls. For example, the buddy control can be made to accept only digits and/or be made non-modifiable, for example.
If the spin control's "Set buddy (s)" style
is set, the buddy control is automatically updated with the current position of
the up-down control when the current position is changed. Otherwise, the
contents of the buddy control mus be updated manually in response to the spin
control's CHANGE event.
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 "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.
