C++Builder Windows Controls: The Time Picker Control


Introduction to the Date/Time Picker Control



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:

Date-Time Picker Date-Time Picker 

One of the advantages of the date/time picker 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. By default, the date time picker allows a user to see a date or a time on the control. In most cases, unless the control is disabled, the user can also change the value of the control.

ApplicationApplication: Introducing the Date/Time Picker

  1. Start Embarcadero RAD Studio
  2. To create new application, on the main menu, click File -> New -> VCL Forms Application - C++Builder
  3. In the Object Inspector, change the properties of the form as follows:
    BorderStyle: bsDialog
    Caption: Simple Interest Evaluation
    Name: frmEvaluation
    Position: poScreenCenter

Adding a Date/Time Picker

To support the a date/time picker, the VCL provides a class named TDateTimePicker. The TDateTimePicker class implements the TCommonCalendar class, which is also the parent of the month calendar:

TDateTimePicker Inheritance

To visually create a date time picker, in the Win32 section of the Tool Palette, click the TDateTimePicker icon TDateTimePicker and click a form or other container. As mentioned already, the date/time picker can be considered as two controls in one: you just have to choose which one of both controls you want to use.

ApplicationApplication: Adding a Date Picker

  • Design the form as follows:
    Simple Interest
    Control Alignment Text Name
    TGroupBox GroupBox   Loan Preparation  
    TLabel Label   Principal  
    TEdit TextBox taRightJustify 0.00 edtPrincipal
    TLabel Label   Interest Rate:  
    TEdit TextBox taRightJustify 0.00 edtInterestRate
    TLabel Label   %  
    TLabel Label   Loan Start Date:  
    TDateTimePicker DateTimePicker     dtpLoanStartDate
    TLabel Label   Loan End Date:  
    TDateTimePicker DateTimePicker     dtpLoandEndDate
    TLabel Label   Periods:  
    TTEdit TextBox taRightJustify 0 edtPeriods
    TLabel Label   Days  
    TButton Button   Calculate btnCalculate
    TGroupBox GroupBox   Results  
    TLabel Label   Interest Earned:  
    TEdit TextBox taRightJustify 0.00 edtInterestEarned
    TLabel Label   Future Value:  
    TEdit TextBox taRightJustify 0.00 edtFutureValue
    TButton Button   Close btnClose

The Kind of Date/Timer Picker

To let you specify whether you want a date picker or a time picker, the TDateTimePicker class is equipped with a property named Kind, which is of type TDateTimeKind:

__property Comctrls::TDateTimeKind Kind = {read=FKind,write=SetKind};

 The TDateTimeKind enumeration has two members:

enum TDateTimeKind{

Introduction to the Time Picker



As described already, the date time picker is two controls in one object. To transform a date time picker into a time picker control, change its Kind property to a dtkTime value:

Time Picker

Also, if you set the Kind to dtkTime, some characteristics (properties) of the TDateTimePicker class cannot change anymore or their changes have no effect. That's the case for the DateMode property.

ApplicationApplication: Introducing the Time Picker Control

  1. To start a new project, on the main menu, click File -> New -> VCL Forms Application -> C++Builder
  2. In the Object Inspector, change the characteristics of the form as follows:
    Caption: Employees Time Sheet
    Name: frmTimeSheet
    Position: poScreenCenter
  3. Design the form as follows:
    Time Sheet
    Control Caption MaxSelectCount MultiSelect Name
    TGroupBox TGroupBox Employee Identification      
    TLabel TLabel Employee Number:      
    TEdit TSpeedButton       edtEmployeeNumber
    TLabel TLabel Employee Name:      
    TEdit TSpeedButton       edtEmployeeName
    TGroupBox TGroupBox Time Frame      
    TMonthCalendar Month Calendar   14 True calTimeFrame
    TGroupBox TGroupBox Time Worked      
    TButton TButton Submit     btnSubmit
    TButton TButton Close     btnClose
  4. On the form, double-click the month calendar
  5. Implement the event as follows:
    void __fastcall TForm1::calTimeFrameClick(TObject *Sender)
        TDateTime DateStart = calTimeFrame->Date;
        if (DateStart.DayOfWeek() != 2)
    	ShowMessage(L"The first day of your time frame must be a Monday");
    	calTimeFrame->EndDate = DateStart + 13;
    	lblWeek1Monday->Caption    = DateStart;
    	lblWeek1Tuesday->Caption   = DateStart + 1;
    	lblWeek1Wednesday->Caption = DateStart + 2;
    	lblWeek1Thursday->Caption  = DateStart + 3;
    	lblWeek1Friday->Caption    = DateStart + 4;
    	lblWeek1Saturday->Caption  = DateStart + 5;
    	lblWeek1Sunday->Caption    = DateStart + 6;
    	lblWeek2Monday->Caption    = DateStart + 7;
    	lblWeek2Tuesday->Caption   = DateStart + 8;
    	lblWeek2Wednesday->Caption = DateStart + 9;
    	lblWeek2Thursday->Caption  = DateStart + 10;
    	lblWeek2Friday->Caption    = DateStart + 11;
    	lblWeek2Saturday->Caption  = DateStart + 12;
    	lblWeek2Sunday->Caption    = DateStart + 13;

Using the Time Picker

The time picker is meant either to only display a time to the user or to both display time and allow the user to specify a time. The control follows the format of the time values set in the regional settings of Control Panel. By default, in US English, the time is divided in four sections that include the hour value, the minute value, the second value, and the AM/PM side. These sections are separated by standard characters that also are specified in the regional settings of Control Panel.

To change the time, the user can click a section, such as the hour, the minute, the second, or the AM/PM side, then click one of the arrows of the spin button. The up button increases (only) the value of the selected section while the down button decreases (only) the value of the selected section. The user can also use the arrow keys to change the value of a section.

After changing the value of the time, even the change occurs for only one section, the control fires an OnChanged event, which is the default event of the control.

ApplicationApplication: Adding a Time Picker

  1. In the Tool Palette, click Win32
  2. Click the TDateTimePicker icon TDateTimePicker
  3. In the form, click under Time Worked
  4. In the Object Inspector, click Kind, then click the arrow of its combo box and select dtkTime

Characteristics of the Time Picker


The Value of the Time Picker

As mentioned already, the user changes the time by using the various sections of the control. If the user changes the value of a section, it is considered that the whole time has been changed. To let you get the (current) time of the control, the TDateTimePicker class is equipped with a property named Time, which is of type TDateTime:

__property System::TDateTime Time = {read=GetTime,write=SetTime};

Notice that this is a rea-write property, which means you can also enquire about its value to get the current time that the control is displaying. During design, you can access the Time field in the Object Inspector to specify the time. Of course, you can also programmatically use this property either to change the time on the control or to get the time on the control.

Using a Custom Format

By default, the time displays using the H:M:SS AM/PM format. This means that the time uses 1 digit for the hours from 0 to 9, 1 digit for the minutes from 0 to 9, 1 digit for the seconds from 0 to 9 and the AM or PM for morning or afternoon. To customize the way the time displays, use the Format property and apply a combination of the following characters to create a custom format:

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

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.

ApplicationAApplication: Introducing the Month Calendar Control

  1. On the form, click the time picker
  2. In the Object Inspector, click Format
  3. Type hh:mm tt and press Enter (during design, you will right-click the time picker -> Edit Copy, then you will right-click under Time Worked -> Edit Paste)
  4. Complete the design of the form as follows (you will only add controls to the Time Worked section):
    Time Sheet

Home Copyright © 2010-2016, FunctionX