VCL Controls - Date Time Picker

	VCL Controls: Date Time Picker

The Date and Time Picker

Introduction

The Date and Time Picker is a control that allows the user to select either a date or a time value. This control provides two objects in one:

One of the advantages of the Date and Time Picker control is that it allows the user to select a time or a date value instead of typing it. This tremendously reduces the likelihood of mistakes.

To create a Date or Time Picker control, add a DateTimePicker control to a form or other container.

Practical Learning: Starting the Exercise

Create a new project with its default form
Save the project in a new folder called Payroll1
Save the unit as Main and the project as Payroll
Design the form as follows:
Save All

The Time Picker

After adding a DateTimePicker control to a container, to make it a Timer Picker control, change its Kind property to a dtkTime value. This changes the control into a spin 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.

By default, the time displays using the HH:MM:SS AM/PM format. This means that the time uses two digits for the hours from 00 to 11, 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, set the desired value in the Format property. The possible values 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
nn	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

You can set the format at design time using the Format field on the Object Inspector. To set the format at run time, assign the desired format to the TDateTimePicker::Format property.

By default, after adding the control to the form or container, it assumes the time of the computer when the control was added. If you want to set a different time, apply a Format combination to the Time property. In the same way, at any time you can retrieve the time value on the control by accessing the Time property.

Sometimes the user may want to manually edit the time of the control such as typing the hour, the minute, the second, or AM/PM. Fortunately, the Date 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 he 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. If you want to allow the user to type the value of the date or time of the control, set the ParseInput Boolean property to true.

The Date Picker

After adding the DateTimePicker control to the form, to allow the user to set the dates and not the times on the control, set its Kind property to dtkDate. This would change the control into a combo box. If you do not like the combo box, you can display a spin button instead. This ability is controlled by the DateMode property. The dmComboBox value is used to display a combo box while the dmUpDown value displays a spin button.

If the control displays a combo box, if the user clicks the arrow on the Date control, a calendar object similar to the MonthCalendar control we saw earlier displays:

This calendar displays to the bottom-left or the bottom-right side of the combo box. To control this alignment, change the value of the CalAlignment property.

The displayed MonthCalendar object allows the user to select a date using the same techniques we described for the MonthCalendar control. The MonthCalendar of the DateTimePicker control displays using the same colors and other properties as we saw with the MonthCalendar control. After the user has selected a date, the date value displays in the Edit section of the combo box and the calendar disappears.

If the control displays a spin button, the object is divided in different sections that can each be changed individually:

To change either the day, the month, or the year, the user must click the desired section and use either the arrows of the button or the arrow keys on the keyboard to increase or decrease the selected value.

If you want to control the range of dates the user can select, use the MinDate and the MaxDate properties.

When you add the DateTimePicker control to your form or container, it displays the date of the computer at the time the control was added. If you want the control to display a different date, set the desired value in the Date field using the Object Inspector. At any time, you can find out what value the Date Picker has by retrieving the value of the TDateTimePicker::Date property.

By default, the date displays using either the Short Date or the Long Date formats of Control Panel. This display is controlled by the DateFormat field in the Object Inspector. If you want to customize the way the date is displayed, set the desired string using the Format property. The possible formats are as follows:

Format	Used For	Description
d	Days	Displays the day as a number from 1 to 31
dd	Days	Displays the day as a number with a leading 0 if the number is less than 10
ddd	Weekdays	Displays a weekday name with 3 letters as Mon, Tue, etc
dddd	Weekdays	Displays the complete name of a week day as Monday, etc
M	Months	Displays the numeric month from 1 to 12
MM	Months	Displays the numeric month with a leading 0 if the number is less than 10
MMM	Months	Displays the short name of the month as Jan, Feb, Mar, etc
MMMM	Months	Displays the complete name of the month as January, etc
yy	Years	Displays two digits for the year as 00 for 2000 or 03 for 2003
yyyy	Years	Displays the numeric year with 4 digits

The user may want to edit the date value of the control, including typing the month, day, year, the name of the month or the name of the weekday. The Date Picker object is equipped to control the types of values that can be entered. For example, the user cannot type the name of a month, only a number and the control would display the corresponding name of the month. This is the default scenario where you let this object help you control the values that the user can type. If you want to take matters into your own hands, that is, if you want to allow the user to type the value of the date or time of the control, set the ParseInput Boolean property to true. If you allow the user to manually enter the date value, if the value is incorrect, when the control looses focus, the compiler would make an attempt to convert the date entered into a valid and true date. If the user enters an invalid value, the compiler would throw an EconvertError error:

This means that you should be reluctant to let the users type whatever they want. The less they type, the less checking you need to do.

Practical Learning: Adding Date Picker Controls

Add two labels and two DateTimePicker controls to the label as follows:
Change the Name of the left control to dteStartPeriod
Change the Name of the right control to dteEndPeriod and set its CalAlignment property to dtaRight

Double-click an unoccupied area on the form and implement its OnCreate event as follows:

//---------------------------------------------------------------------------
void __fastcall TfrmMain::FormCreate(TObject *Sender)
{
	dteStartPeriod->CalColors->BackColor = TColor(RGB(230, 245, 255));
	dteStartPeriod->CalColors->MonthBackColor =
		 TColor(RGB(212, 235, 255));
	dteStartPeriod->CalColors->TextColor = clBlue;
	dteStartPeriod->CalColors->TitleBackColor = TColor(RGB(0, 0, 160));
	dteStartPeriod->CalColors->TitleTextColor = clWhite;
	dteStartPeriod->CalColors->TrailingTextColor =
		 TColor(RGB(190, 125, 255));

	dteStartPeriod->Format = "ddd d MMM yyyy";

	dteEndPeriod->CalColors->BackColor = TColor(RGB(255, 236, 218));
	dteEndPeriod->CalColors->MonthBackColor = TColor(RGB(255, 235, 214));
	dteEndPeriod->CalColors->TextColor = TColor(RGB(102, 52, 0));
	dteEndPeriod->CalColors->TitleBackColor = TColor(RGB(176, 88, 0));
	dteEndPeriod->CalColors->TitleTextColor = TColor(RGB(255, 238, 220));
	dteEndPeriod->CalColors->TrailingTextColor = 
		TColor(RGB(230, 115, 0));

	dteEndPeriod->Format = "ddd d MMM yyyy";
}
//---------------------------------------------------------------------------

Test the application
Close the form and return to Bcb

Date Time Picker Events

The Date Time Picker control enjoys some events that the Calendar object does not have. Whenever the user changes the date or time value of the control, an OnChange event fires. You can use this event to take some action such as indicating to the user that the new date is invalid.

If you had allowed the user to enter almost any type of value in the control by setting the ParseInput Boolean property to true, and if he decides to edit the value of the control, while the user is doing this, the OnUserInput event fires. This can be a good place to check what the user is doing and take some action. The syntax of the OnUserInput event is:

void __fastcall DateTimePickerUserInput(TObject *Sender, const AnsiString UserString,
TDateTime &DateAndTime, bool &AllowChange)

The UserString argument is the value that the user is typing. It could be a digit or a letter. The control returns the DateAndTime as the value of the control. If, during your checking, you find out that the user typed a wrong value, you can allow or disallow by setting the value of the AllowChange argument accordingly. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::DateTimePicker1UserInput(TObject *Sender,
		const AnsiString UserString, TDateTime &DateAndTime,
		bool &AllowChange)
{
	if( TDateTime(UserString) < Date() )
	{
		ShowMessage("The cleaning date you entered, " +
				UserString + ", is not valid!");
		AllowChange = False;
	}
	else
	{
		Edit1->Text = DateAndTime;
		AllowChange = True;
	}
}
//---------------------------------------------------------------------------

If the Kind property of the control is set to dtkDate and if the DateMode value is dmComboBox, when the user clicks the arrow of the combo box to display the MonthCalendar, the OnDropDown() event fires. On the other hand, if the user clicks the arrow to retract the Calendar, an OnCloseUp() event fires. Both event are TNotifyEvent type.

Practical Learning: Using Date Time Picker Events

On the form, click the left Date and Time Picker control to select it
On the Object Inspector, click the Events tab and scroll down completely if necessary

Double-click the event side of the OnCloseUp field and implement it as follows:

//---------------------------------------------------------------------------
void __fastcall TfrmMain::dteStartPeriodCloseUp(TObject *Sender)
{
	// Add two weeks to the date selected by the user
	dteEndPeriod->Date = dteStartPeriod->Date + 13;
}
//---------------------------------------------------------------------------

Test the application by changing the date values of the left control and notice that two weeks are always added to set the value of the right control
After using the form, close it and return to Bcb


Home	Copyright � 2004-2007 FunctionX, Inc.