As its name indicates, the date picker either displays a date or it allows the user to specify a date. The control follows the format of the date values specified in the regional settings of Control Panel. Consequently, the date is made of various sections including the name of the day, the name of the month, the numeric day in the month, and the year.

In a later section, we will see that the date picker can display a combo box or a spin button. If the control is displaying as a combo box, to change the date, the user can click the arrow of the combo box. This would display a month calendar:

When the calendar displays, the control throws an OnDropDown event:

//---------------------------------------------------------------------------
void __fastcall TfrmExercise::DateTimePicker1DropDown(TObject *Sender)
{

}
//---------------------------------------------------------------------------

 The OnDropDown event is of type TNotifyEvent, which means that it doesn't carry any significant information, other than to let you know that the calendar of the control has been dropped to display.

While the calendar is displaying, the user can change the month, change the year, or click a date to select one. This would cause the month calendar to close and the control would display the date that was selected. We will see that there are other ways the user can change the value of the control. However it is done, on the text box or on the calendar, when the date of the control has been changed, the control fires an OnChanged event:

//---------------------------------------------------------------------------
void __fastcall TfrmExercise::DateTimePicker1Change(TObject *Sender)
{

}
//---------------------------------------------------------------------------

 The OnChanged event, which is the default event of the control, is of type TNotifyEvent, meaning it does not give you any detail about the date that was selected or about anything the user did. You would use your own means of finding out what date the user had selected or specified. This can easily be done by getting the Value property of the control.

If the control is displaying a calendar, once the user clicks a date, the calendar disappears and the control becomes a combo box again. When the calendar retracts, the control fires an OnCloseUp event:

//---------------------------------------------------------------------------
void __fastcall TfrmExercise::DateTimePicker1CloseUp(TObject *Sender)
{

}
//---------------------------------------------------------------------------

The OnCloseUp event is of type TNotifyEvent, which means it does not carry any particular information other than letting you know that the calendar has been closed.

1. On the form, click the bottom date picker (the End Loan Date control)
2. In the Object Inspector, click the Events tab
3. Double-click the box on the right side of OnCloseUp to generate its event
4. Implement the event as follows:
   

   //---------------------------------------------------------------------------
   void __fastcall TfrmEvaluation::dtpLoanEndDateCloseUp(TObject *Sender)
   {
       double Principal = 0.00, InterestRate = 0.00, Periods = 0.00;
       double InterestEarned, FutureValue;
       TDateTime StartDate, EndDate;
       int Days;
   
       // Get the value of the principal
       try {
   	   Principal = edtPrincipal->Text.ToDouble();
       }
       catch(EConvertError *)
       {
   	ShowMessage(L"Invalid Principal Value");
       }
   
       // Get the interest rate
       try {
           InterestRate  = edtInterestRate->Text.ToDouble() / 100;
       }
       catch(EConvertError *)
       {
   	ShowMessage(L"Invalid Interest Rate");
       }
   
       // Get the start and end dates
       StartDate = dtpLoanStartDate->Date;
       EndDate = dtpLoanEndDate->Date;
   
       // Make sure the end date doesn't occur before the start date
       if(EndDate < StartDate)
       {
   	ShowMessage(L"Invalid Date Sequence: "
   	 	    L"the end date must occur after the start date");
   	dtpLoanEndDate->Date = Date();
   	return;
       }
   
       // Get the difference in days
       // The will be the periods
       Days = EndDate - StartDate;
       edtDays->Text = Days;
       double p = 0.00;
   
       // Because we will allow the user to directly specify
       // the number of days, let's get the period from its text box
       try {
   	p = edtDays->Text.ToDouble();
       }
       catch (EConvertError *)
       {
   	ShowMessage(L"Invalid number of days");
       }
   
       // The actual period is gotten as follows
       Periods = p / 365;
       // Now we can perform the calculations
       InterestEarned = Principal * InterestRate * Periods;
       FutureValue = Principal + InterestEarned;
   
       // Display the values
       edtInterestEarned->Text = FloatToStrF(InterestEarned, ffCurrency, 8, 2);
       edtFutureValue->Text    = FloatToStrF(FutureValue, ffCurrency, 8, 2);
   }
   //---------------------------------------------------------------------------

5. Press F12 to return to the form
6. Click the Periods edit box
7. On the Object Inspector, click Events
8. Double-click the right side of OnExit
9. Implement the event as follows:
   

   //---------------------------------------------------------------------------
   void __fastcall TfrmEvaluation::edtDaysExit(TObject *Sender)
   {
   	dtpLoanEndDateCloseUp(Sender);
   }
   //---------------------------------------------------------------------------

10. Press F12 to return to the form
11. Double-click the Close button
12. Implement the event as follows:
    

    //---------------------------------------------------------------------------
    void __fastcall TfrmEvaluation::btnCloseClick(TObject *Sender)
    {
    	Close();
    }
    //---------------------------------------------------------------------------

13. Press F12 to return to the form
14. In the Object Inspector, click the Properties tab
15. Press F9 to execute the application
     
    
16. Close the form and return to your programming environment

The date picker supports two categories of date values, referred to as long date format and short date format. They are defined in the Region and Language section of the Control Panel:

You can also get the categories in the Date section of the Customize Format dialog box:

To support the type of date, the TDateTimeFormat class is equipped with a UnicodeString property named DateFormat that is of type TDTDateFormat:

__property Comctrls::TDTDateFormat DateFormat = {read=FDateFormat,write=SetDateFormat};

The TDTDateFormat enumeration is defined as follows:

enum TDTDateFormat{
	dfShort,
	dfLong
};

To make the control display long date formats, specify its DateFormat property as dfLong. For a short date format, set the property to dfShort.

1. On the form, click the top date picker control
2. In the Object Inspector, click DateFormat, then click the arrow of its combo box and select dfLong
3. In the same way, on the form, click the second date picker
4. In the Object Inspector, double-click DateFormat to change its value to dfLong

After adding a date time picker control and setting its DateFormat property to either dfLong (the default) or dfShort, the control becomes a combo box (the default):

We saw already how the user can select a date using the combo box. If you don't like the combo box, you can display a spin button instead. The ability to display a combo box or a spin button is controlled by a property named DateMode that is of type TDTDateMode:

__property Comctrls::TDTDateMode DateMode = {read=FDateMode,write=SetDateMode};

The TDTDateMode enumeration has two members:

enum TDTDateMode{
	dmComboBox,
	dmUpDown
};

The default value is dmComboBox. If you want the control to display a spin button, set its DateMode property to dmUpDown:

If the control is displaying a spin button, to change a part of the value, such as the day, the month, or the year, the user must click that part, and it becomes highlighted:

•  The user can type a value
• The user can click the arrows of the spin button to change the value
• The user can press the up or down keys on the keyboard to increase or decrease the value

In reality, the ability to change the value of a section works also if the control is displaying a combo box.

In some cases, you may want to decide when to allow the user to select a date or when to disable it. There are two ways you can do. You can use the TControl's Enabled property that all Windows controls inherit. Another technique you can use is to display a check box on the left side of the text box section of the control. The presence or absence of the check box is controlled by the ShowCheckBox Boolean property:

__property bool ShowCheckbox = {read=FShowCheckbox,write=SetShowCheckbox};

The default value of the ShowCheckBox property is False. If you set it to True, a check box appears:

If the check box is checked, the user can change the displayed date. If the check box is unchecked, the label that displays the value of the control is disabled (the label or value, not the control itself):

• If the control is displaying a combo box:
  • The user cannot click a section to change its value because the label that shows the date is disabled
  • To change the value, the user can click the arrow of the combox. This would enable the value. The user can then select from the month calendar
•  If the control is displaying a spin button, since the label that holds the value of the control is disabled, the user cannot change the value of the control

Since the ShowCheckBox property is read-write, you can also use it to find out whether the control is currently equipped with a check box.

If the date picker control displays like a combo box, as mentioned already, if the user clicks the arrow button, a calendar appears. The calendar shares the same functionality and characteristics as the month calendar control. The colors are managed by the CalColors property that is based on the properties of the TMonthCalColors class:

• The background color of the title bar is represented by the TitleBackColor property
• The color of the text on the calendar is handled by the TextColor property
• The background color of the calendar is set by the BackColor property
• The background color of the current month of the calendar is set by the MonthBackColor property
• The font color of the title bar is controlled by the TitleTextColor property
• The minimum and the maximum dates are specified using the MinDate and the MaxDate properties
• The color of the days of the trailing months is held by the TrailingTextColor property

1. On the form, click the top date picker control
2. In the Object Inspector, click the + button of CalColors
3. Change the following values:
   BackColor: clGradientActiveCaption
   MonthBackColor: clSkyBlue
   TextColor: clBlue
   TitleBackColor: clNavy
   TitleTextColor: clCream
   TrailingTextColor: clYellow
4. Double-click an unoccupied area of the form to generate its OnCreate event
5. Implement the event as follows:

   //---------------------------------------------------------------------------
   void __fastcall TfrmEvaluation::FormCreate(TObject *Sender)
   {
   	dtpLoanEndDate->CalColors->BackColor = RGB(155, 50, 0);
   	dtpLoanEndDate->CalColors->MonthBackColor = RGB(255, 165, 65);
   	dtpLoanEndDate->CalColors->TextColor = RGB(128, 0, 0);
   	dtpLoanEndDate->CalColors->TitleBackColor = RGB(190, 95, 0);
   	dtpLoanEndDate->CalColors->TitleTextColor = RGB(255, 255, 0);
   	dtpLoanEndDate->CalColors->TrailingTextColor = RGB(128, 128, 128);
   }
   //---------------------------------------------------------------------------

6. To execute the application, on the main menu, click Run -> Run
    
7. Close the form and return to your programming environment

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 that is of type TDTCalAlignment:

__property Comctrls::TDTCalAlignment CalAlignment = 
{
    read=FCalAlignment,
    write=SetCalAlignment
};

The TDTCalAlignment enumeration is defined as follows:

enum TDTCalAlignment{
	dtaLeft,
	dtaRight
};

The default value of the CalAlignment property is dtaLeft. value is dtaRight.

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

When you add the date time picker 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 of the Object Inspector. At any time, you can find out what value the date picker has by retrieving the value of the Date property.

If you set the DateFormat property to dfLong, the date displays using the Long Date formats of Control Panel. If you set the DateFormat value to dfShort, the control uses the Short Date value of Control Panel. To let you customize the way the date is displayed, the TDateTimePicker class is equipped with a string property named Format:

__property System::UnicodeString Format = {read=FFormat,write=SetFormat};

Use this property create a custom format. The format is created by combining the following characters:

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.