VCL Controls: Date Picker

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.

1. Create a new VCL Forms Application - Delphi for Win32 project with its default form
2. Save the project in a new folder called Payroll2
3. Save the unit as Main and the project as Payroll2
4. Design the form as follows:
    

   Control Name Caption Other Properties Form frmMain Employee Payroll BorderStyle: dsDialog ShowHint: True Panel    None

5. Save All

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:

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.

1. Add two labels and two DateTimePicker controls to the label as follows:
    
   
2. Change the Name of the left control to dtpStartPeriod
3. Change the Name of the right control to dtpEndPeriod and set its CalAlignment property to dtaRight
4. Double-click an unoccupied area on the form and implement its OnCreate event as follows:
    

   procedure TfrmMain.FormCreate(Sender: TObject); begin dtpStartPeriod.CalColors.BackColor := TColor(RGB(230, 245, 255)); dtpStartPeriod.CalColors.MonthBackColor := TColor(RGB(212, 235, 255)); dtpStartPeriod.CalColors.TextColor := clBlue; dtpStartPeriod.CalColors.TitleBackColor := TColor(RGB(0, 0, 160)); dtpStartPeriod.CalColors.TitleTextColor := clWhite; dtpStartPeriod.CalColors.TrailingTextColor := TColor(RGB(190, 125, 255)); dtpStartPeriod.Format := 'ddd d MMM yyyy'; dtpEndPeriod.CalColors.BackColor := TColor(RGB(255, 236, 218)); dtpEndPeriod.CalColors.MonthBackColor := TColor(RGB(255, 235, 214)); dtpEndPeriod.CalColors.TextColor := TColor(RGB(102, 52, 0)); dtpEndPeriod.CalColors.TitleBackColor := TColor(RGB(176, 88, 0)); dtpEndPeriod.CalColors.TitleTextColor := TColor(RGB(255, 238, 220)); dtpEndPeriod.CalColors.TrailingTextColor := TColor(RGB(230, 115, 0)); dtpEndPeriod.Format := 'ddd d MMM yyyy'; end;

5. Test the application
6. Close the form and return to Delphi 

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 whether 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 the user 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:

type TDTParseInputEvent = procedure(Sender: TObject; const UserString: string; var DateAndTime: TDateTime; var AllowChange: Boolean) of object;
property OnUserInput: TDTParseInputEvent;

This means that the OnUserInput event is of type TDTParseInputEvent.

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 it by setting the value of the AllowChange argument accordingly. Here is an example:

procedure TfrmMain.DateTimePicker1UserInput(Sender: TObject;
  const UserString: String; var DateAndTime: TDateTime;
  var AllowChange: Boolean);
begin
     if StrToDate(UserString) < Date() then
     begin
        ShowMessage('The cleaning date you entered, ' +
                    UserString + ', is not valid!');
        AllowChange := False
     end
     else
         Edit1.Text := DateToStr(DateAndTime);
         AllowChange := True;
end;

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.

1. On the form, click the left Date and Time Picker control to select it
2. In the Object Inspector, click the Events tab and double-click the event side of the OnCloseUp field
3. Implement the event as follows:
    

   procedure TfrmMain.dtpStartPeriodCloseUp(Sender: TObject); begin // Add two weeks to the selected date dtpEndPeriod.Date := dtpStartPeriod.Date + 13; end;

4. 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
5. After using the form, close it and return to Delphi