|
Characteristics of the Time Picker Control
|
|
The time picker control is a spin button made of
different sections: the hours value, the minutes value, the optional seconds
value, and the optional AM/PM string. To change the time, the user clicks a
section and uses either the mouse or the keyboard to increase or decrease
that particular value. To change another value, the user must first click it
and then use the spin button.
To use the time picker, the user must first give it
focus. This is done by clicking either one of the sections of the control or
by directly clicking one of the arrows of the spin button portion. You also
can programmatically give focus to the control by sending an
NM_SETFOCUS message.
Once the control has focus, it is primarily meant to let
the user set a time (on the control). To support this, it allows the user to
manually edit the time of the control such as typing the hour, the minute,
the second, or AM/PM. The time picker control is equipped to natively allow
or disallow some values. For example, the user cannot type anything else
than a digit for the hours, minutes, or second portions and she can type
only a, A, p, or P for the AM/PM section. This is the default scenario where
you let this object help you control the values that the user can type. To
perform these operations, the user can click the portion to change and then
click the arrows of the spin button. When the user changes the value of the
control, the time picker fires a DTN_DATETIMECHANGE
message.
Instead of using the mouse to change the time, the user
can click a portion of the control and press the arrow keys to change the
value of that portion. Whenever the user presses one of the arrow keys, the
control fires a DTN_WMKEYDOWN message.
After using the time picker control, the user can click
somewhere else, which causes the control to loose focus. To programmatically
change focus from the control, you can send an NM_KILLFOCUS
message.
By default, the time displays using the H:MM:SS AM/PM
format. This means that the time uses one digit for the hours from 0 to 9,
two digits for the minutes from 00 to 59, two digits for the seconds from 00
to 59 and the AM or PM for morning or afternoon. To control how the time
displays, call the CDateTimeCtrl::SetFormat() member
function whose syntax is:
BOOL SetFormat(LPCTSTR pstrFormat);
The letters used to set the format for a time value are:
| Format |
Used For |
Description |
| h |
Hour |
For 12-hour basis: Used to display the hour with one digit
if the value is less than 10 |
| hh |
Hour |
For 12-hour basis: Used to display the hour with a leading 0
if the value is less than 10 |
| H |
Hour |
For 24-hour basis Used to display the hour with one digit if
the value is less than 10 |
| HH |
Hour |
For 24-hour basis: Used to display the hour with a leading 0
if the value is less than 10 |
| m |
Minute |
Used to display the minute with one digit if the value is
less than 10 |
| mm |
Minute |
Used to display the minute with a leading 0 if the value is
less than 10 |
| t |
AM/PM |
Displays the letter A or P for the AM or PM section |
| tt |
AM/PM |
Displays the letters AM or PM for the last section |
By default, after adding the control to the dialog box
or container, it assumes the time of the computer when the control was
added. If you want to set a different time, call the
CDateTimeCtrl::SetTime() member function. It is overloaded with
three versions whose syntaxes are:
BOOL SetTime(const COleDateTime& timeNew);
BOOL SetTime(const CTime* pTimeNew);
BOOL SetTime(LPSYSTEMTIME pTimeNew = NULL);
To retrieve the time value on the control, you can call
the CDateTimeCtrl::GetTime() member function. It also is
overloaded with three versions and their syntaxes are:
BOOL GetTime(COleDateTime& timeDest) const;
DWORD GetTime(CTime& timeDest) const;
DWORD GetTime(LPSYSTEMTIME pTimeDest) const;
|
Practical
Learning: Introducing the Date Picker
