The Date/Time Picker Control

Introduction to the Date/Time Picker Control

Description

The date/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/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/time picker control, from the Common Controls section of the Toolbox, click DateTimePicker and click the form or another container. The DateTimePicker control is based on the DateTimePicker class. Therefore, to programmatically, declare a variable of type DateTimePicker and initialize it appropriately. Here is an example:

Imports System.Drawing
Imports System.Windows.Forms

Module Exercise

    Public Class Starter
        Inherits Form

        Private DateOrTime As DateTimePicker

        Dim components As System.ComponentModel.Container

        Public Sub New()
            InitializeComponent()
        End Sub

        Public Sub InitializeComponent()
            DateOrTime = New DateTimePicker

            Controls.Add(DateOrTime)
        End Sub

    End Class

    Function Main() As Integer

        Dim frmStart As Starter = New Starter

        Application.Run(frmStart)

        Return 0
    End Function

End Module

In reality, the DateTimePicker control can be considered as two controls in one: you just have to choose which one of both controls you want to use.

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 Format property either to Long or to Short. If you are working programmatically, use the DateTimePickerFormat enumeration to select Long or Short and assign it to the Format property of the control. Here is an example:

Imports System.Drawing
Imports System.Windows.Forms

Module Exercise

    Public Class Starter
        Inherits Form

        Private Calendar As DateTimePicker

        Dim components As System.ComponentModel.Container

        Public Sub New()
            InitializeComponent()
        End Sub

        Public Sub InitializeComponent()
            Calendar = New DateTimePicker
            Calendar.Format = DateTimePickerFormat.Long

            Controls.Add(Calendar)
        End Sub

    End Class

    Function Main() As Integer

        Dim frmStart As Starter = New Starter

        Application.Run(frmStart)

        Return 0
    End Function

End Module

1. Start a new Window Application named SimpleInterest2
2. In the Solution Explorer, right-click Form1.vb and click Rename
3. Type SimpleInterest.vb and press Enter
4. Design the form as follows:
    

   Control Text Name TextAlign GroupBox Loan Preparation     Label Principal     TextBox 0.00 txtPrincipal Right Label Interest Rate:     TextBox 0.00 txtInterestRate Right Label %     Label Loan Start Date:     DateTimePicker   dtpStartDate   Label Loan End Date:     DateTimePicker   dtpLoandEndDate   Label Periods:     TextBox 1 txtPeriods Right Label days     Button Calculate btnCalculate   GroupBox Results     Label Interest Earned:     TextBox 0.00 txtInterestEarned Right Label Future Value:     TextBox 0.00 txtFutureValue Right Button Close btnClose

5. Right-click the form and click View Code

After adding a date time picker control and setting its Format to either Long (the default) or Short, the control becomes a combo box (the default). If you do not like the combo box, you can display a spin button instead. This characteristic is controlled by the ShowUpDown Boolean property. When its value is set to False (the default), the control appears as a combo box. It you set it to True, it appears as a spin button:

Of course, you can also set it programmatically:

Public Sub InitializeComponent()
            Calendar = New DateTimePicker
            Calendar.Format = DateTimePickerFormat.Long
            Calendar.ShowUpDown = True

            Controls.Add(Calendar)
End Sub

If the control displays a combo box and if the user clicks the arrow on the Date control, a calendar object similar to the month calendar control displays:

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 Control's Enabled property that all other 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 whose default value is False. If you set it to True, a check box appears:

When the check box is checked, the user can change the displayed date. When the check box is unchecked, the control is displayed and the user cannot change the date. The user must first put a check mark in the check box in order to be able to change the date.

The state of the check box is controlled by the Boolean Checked property. If the user clicks the check box to put a check mark in it, this property's value becomes true. 

As its name indicates, the date picker either displays a date or 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.

If the control is equipped with a spin button, to change the month, the user can click the month and then click one of the arrow buttons of the spin control. The user can also use the arrow keys to get the same effect. In the same way, the user can change the values of the day or the year.

If the control appears as a combo box, the user can click the arrow button. This would display a calendar:

When the calendar displays, the control throws a DropDown event. The DropDown event is of type EventArgs. This means that this event does not 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. T user can still change the date in the text box side 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 a ValueChanged event. The ValueChanged event, which is the default event of the control, is of type EventArgs, 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 a CloseUp event. The CloseUp event is of type EventArgs, which means it does not carry any particular information other than letting you know that the calendar has been closed.

1. In the form Class Name combo box, select dtpEndDate
2. In the Method Name combo box, select CloseUp and implement the event as follows:
    

   Private Sub dtpEndDate_CloseUp(ByVal sender As Object, _ ByVal e As System.EventArgs) _ Handles dtpEndDate.CloseUp Dim Principal As Double Dim InterestRate As Double Dim Periods As Double Dim InterestEarned As Double Dim FutureValue Dim StartDate As DateTime Dim EndDate As DateTime Dim spnPeriods As TimeSpan ' Get the value of the principal Try Principal = CDbl(txtPrincipal.Text) Catch MsgBox("Invalid Principal Value") End Try ' Get the interest rate Try InterestRate = CDbl(txtInterestRate.Text) / 100 Catch MsgBox("Invalid Interest Rate") End Try ' Get the start and end dates StartDate = dtpStartDate.Value EndDate = dtpEndDate.Value ' Make sure the end date doesn't occur before the start date If EndDate < StartDate Then MsgBox("Invalid Date Sequence: " & _ "the end date must occur after the start date") dtpEndDate.Value = DateTime.Today Return End If ' Get the difference in days ' The will be the periods spnPeriods = EndDate.Subtract(StartDate) Dim days As Integer = spnPeriods.Days txtPeriods.Text = CStr(days) Dim p As Double ' Because we will allow the user to directly specify ' the number of days, let's get the period from its text box Try p = CDbl(txtPeriods.Text) Catch ex As Exception MsgBox("Invalid number of days") End Try ' 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 txtInterestEarned.Text = FormatCurrency(InterestEarned) txtFutureValue.Text = FormatCurrency(FutureValue) End Sub

3. In the form Class Name combo box, select txtPeriods
4. In the Method Name combo box, select Leave and implement the event as follows:
    

   Private Sub txtPeriods_Leave(ByVal sender As Object, _ ByVal e As System.EventArgs) _ Handles txtPeriods.Leave ' If the user directly enters the number of days ' in the Periods text box and press Tab, ' we can perform the caltulation dtpEndDate_CloseUp(sender, e) End Sub

5. In the form Class Name combo box, select btnCalculate
6. In the Method Name combo box, select Click and implement the event as follows:
    

   Private Sub btnCalculate_Click(ByVal sender As Object, _ ByVal e As System.EventArgs) _ Handles btnCalculate.Click ' If the user directly enters the number of days ' in the Periods text box and clicks the Calculate ' button, we can perform the caltulation dtpEndDate_CloseUp(sender, e) End Sub

7. In the Class Name combo box, select btnClose
8. In the Method Name combo box, select Click and implement the event as follows:
    

   Private Sub btnClose_Click(ByVal sender As Object, _ ByVal e As System.EventArgs) _ Handles btnClose.Click End End Sub

9. Return to the form
10. In the Properties window, click the Properties button

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 like the month calendar control:

• The background color of the title bar is represented by the CalendarTitleBackColor property
• The color of the text on the calendar is handled by the CalendarForeColor property
• The font used on the text throughout the calendar is set by the CalendarFont 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 CalendarMonthBackground property
• The font color of the title bar is controlled by the CalendarTitleForeColor 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 CalendarTrailingForeColor property

1. On the form, click the top date picker control
2. In the Properties window, change the following values:
   CalendarForeColor: Blue
   CalendarMonthBackground: SkyBlue
   CalendarTitleBackColor: Navy
   CalendarTitleForeColor: Gold
   CalendarTrailingForeColor: DodgeBlue
3. On the form, click the top date picker control
4. In the Properties window, change the following values:
   CalendarForeColor: Maroon
   CalendarMonthBackground: Orange
   CalendarTitleBackColor: Sienna
   CalendarTitleForeColor: Khaki
   CalendarTrailingForeColor: White
5. Execute the application and test the application
    
6. 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 DropDownAlign property whose default value is Left. The other value is Right.

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

If you want to control the range of dates the user can select, use the MinDate and the MaxDate properties as we mentioned them from the MonthCalendar control.

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 Value field of the Properties window. At any time, you can find out what value the Date Picker has by retrieving the value of the Value property.

If you set the Format property to Long, the date displays using the Long Date formats of Control Panel. If you set the Format to Short, the control uses the Short Date value of Control Panel. If you want to customize the way the date is displayed, set the Format property to Custom. After setting the Format to Custom, use the CustomFormat property to create the desired 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.

The Date Time Picker control uses some events that the month calendar control does not have. Whenever the user changes the date or time value of the control, a ValueChanged event fires. You can use this event to take some action such as indicating to the user that the new date is invalid.

If the Format property of the control is set to Date and if the ShowUpDown property is set to False, when the user clicks the arrow of the combo box to display the calendar part of the date time picker control, the DropDown event fires. On the other hand, if the user clicks the arrow to retract the calendar, the CloseUp event fires. Both events are of EventArgs type.

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 Format property to a Time value. You can also do this programmatically. Here is an example:

Imports System.Drawing
Imports System.Windows.Forms

Module Exercise

    Public Class Starter
        Inherits Form

        Private ShowTime As DateTimePicker

        Dim components As System.ComponentModel.Container

        Public Sub New()
            InitializeComponent()
        End Sub

        Public Sub InitializeComponent()
            ShowTime = New DateTimePicker
            ShowTime.Format = DateTimePickerFormat.Time

            Controls.Add(ShowTime)
        End Sub

    End Class

    Function Main() As Integer

        Dim frmStart As Starter = New Starter

        Application.Run(frmStart)

        Return 0
    End Function

End Module

Although optional, you should (with emphasis) also set the ShowUpDown Boolean property to True. Here is an example:

Public Sub InitializeComponent()
            ShowTime = New DateTimePicker
            ShowTime.Format = DateTimePickerFormat.Time
            ShowTime.ShowUpDown = True

            Controls.Add(ShowTime)
End Sub

This makes it a true time picker control:

If you do not set the ShowUpDown property to true, the control would display as a combo box and when the user clicks the arrow button, a calendar would come up, which does not make sense since the purpose of the control is to deal with time values.

1. Start a new Windows Application named GeorgetownCleaningServices2
2. In the Solution Explorer, right-click Form1.vb and click Rename
3. Type CleaningServices.vb and press Enter
4. Design the form as follows:
    

   Control Name Text Additional Properties GroupBox   Order Identification   Label   Customer Name:   TextBox txtCustomerName     Label   Customer Phone:   TextBox txtCustomerPhone     Label   Date Left:   DateTimePicker dtpDateLeft     Label   Time Left:   DateTimePicker dtpTimeLeft   Format: Time Label   Date Expected:   DateTimePicker dtpDateExpected     Label   Time Expected:   DateTimePicker dtpTimeExpected   Format: Time GroupBox   Order Processing   Label   Item Type   Label   Unit Price   Label   Qty   Label   Sub Total   Label   Shirts   TextBox txtShirtsUnitPrice 1.25 TextAlign: Right TextBox txtShirtsQuantity 0 TextAlign: Right TextBox txtShirtsSubTotal 0.00 TextAlign: Right Label   Pants   TextBox txtPantsUnitPrice 1.95 TextAlign: Right TextBox txtPantsQuantity   TextAlign: Right TextBox txtPantsSubTotal 0.00 TextAlign: Right ComboBox cbxItem1 None Items: None Women Suit Dress Regular Skirt Skirt With Hook Men's Suit 2Pc Men's Suit 3Pc Sweaters Silk Shirt Tie Coat Jacket Swede TextBox txtItem1UnitPrice 0.00 TextAlign: Right TextBox txtItem1Quantity 0 TextAlign: Right TextBox txtItem1SubTotal 0.00 TextAlign: Right ComboBox cbxItem2 None Items: None Women Suit Dress Regular Skirt Skirt With Hook Men's Suit 2Pc Men's Suit 3Pc Sweaters Silk Shirt Tie Coat Jacket Swede TextBox txtItem2UnitPrice 0.00 TextAlign: Right TextBox txtItem2Quantity 0 TextAlign: Right TextBox txtItem2SubTotal 0.00 TextAlign: Right ComboBox cbxItem3 None Items: None Women Suit Dress Regular Skirt Skirt With Hook Men's Suit 2Pc Men's Suit 3Pc Sweaters Silk Shirt Tie Coat Jacket Swede TextBox txtItem3UnitPrice 0.00 TextAlign: Right TextBox txtItem3Quantity 0 TextAlign: Right TextBox txtItem3SubTotal 0.00 TextAlign: Right ComboBox cbxItem4 None Items: None Women Suit Dress Regular Skirt Skirt With Hook Men's Suit 2Pc Men's Suit 3Pc Sweaters Silk Shirt Tie Coat Jacket Swede TextBox txtItem4UnitPrice 0.00 TextAlign: Right TextBox txtItem4Quantity 0 TextAlign: Right TextBox txtItem4SubTotal 0.00 TextAlign: Right GroupBox   Order Summary   Button btnCalculate Calculate   Label   Cleaning Total:   TextBox txtCleaningTotal 0.00 TextAlign: Right Label   Tax Rate:   TextBox txtTaxRate 7.75 TextAlign: Right Label   %   Label   Tax Amount:   TextBox txtTaxAmount 0.00 TextAlign: Right Label   Net Total:   TextBox txtNetPrice 0.00 TextAlign: Right Button btnClose Close

5. Right-click the form and click View Code

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 AP/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 of the time, even the change occurs for only one section, the control fires a ValueChanged event, which is the default event of the control.

As mentioned already, the user changes the time by using the various sections of the controls. If the user changes the value of a section, it is considered that the whole time has been changed. At any time, the (current) time of the control is stored in the Value property. You can use this property either to programmatically change the time on the control or to get the time on the control.

1. In the Class Name combo box, select dtpTimeLeft
2. In the Method Name combo box, select ValueChanged and implement the event as follows:
    

   Private Sub dtpTimeLeft_ValueChanged(ByVal sender As Object, _ ByVal e As System.EventArgs) _ Handles dtpTimeLeft.ValueChanged Dim dateLeft As DateTime Dim timeLeft As DateTime Dim time9AM As DateTime dateLeft = dtpDateLeft.Value timeLeft = dtpTimeLeft.Value time9AM = New DateTime(timeLeft.Year, timeLeft.Month, timeLeft.Day, 9, 0, 0) ' If the customer leaves clothes before 9AM... If timeLeft <= time9AM Then ' ... then they should be ready the same day after 5PM dtpDateExpected.Value = dateLeft dtpTimeExpected.Value = New DateTime(dateLeft.Year, _ dateLeft.Month, _ dateLeft.Day, 17, 0, 0) Else ' If the clothes were left after 9AM, they will be available the following morning at 8AM dtpDateExpected.Value = New DateTime(dateLeft.Year, _ dateLeft.Month, _ dateLeft.Day + 1) dtpTimeExpected.Value = New DateTime(dateLeft.Year, _ dateLeft.Month, _ dateLeft.Day + 1, 8, 0, 0) End If End Sub

3. In the Class Name combo box, select btnCalculate
4. In the Method Name combo box, select Click and implement the event as follows:
    

   Private Sub btnCalculate_Click(ByVal sender As Object, _ ByVal e As System.EventArgs) _ Handles btnCalculate.Click Dim UnitPriceShirts As Double, UnitPricePants As Double Dim UnitPriceItem1 As Double, UnitPriceItem2 As Double Dim UnitPriceItem3 As Double, UnitPriceItem4 As Double Dim SubTotalShirts As Double, SubTotalPants As Double Dim SubTotalItem1 As Double, SubTotalItem2 As Double Dim SubTotalItem3 As Double, SubTotalItem4 As Double Dim QuantityShirts As Integer, QuantityPants As Integer = 1 Dim QuantityItem1 As Integer, QuantityItem2 As Integer = 1 Dim QuantityItem3 As Integer, QuantityItem4 As Integer = 4 Dim CleaningTotal As Double, TaxRate As Double Dim TaxAmount As Double, NetPrice As Double ' Retrieve the unit price of this item ' Just in case the user types an invalid value, we are using a try...catch Try UnitPriceShirts = CDbl(txtUnitPriceShirts.Text) Catch ex As Exception MsgBox("The value you entered for the price of shirts is not valid" & _ vbCrLf & "Please try again") Exit Sub End Try ' Retrieve the number of this item ' Just in case the user types an invalid value, we are using a try...catch Try QuantityShirts = CInt(txtQuantityShirts.Text) Catch ex As Exception MsgBox("The value you entered for the number of shirts is not valid" & _ vbCrLf & "Please try again") Exit Sub End Try Try UnitPricePants = CDbl(txtUnitPricePants.Text) Catch ex As Exception MsgBox("The value you entered for the price of pants is not valid" & _ vbCrLf & "Please try again") Exit Sub End Try Try QuantityPants = CInt(txtQuantityPants.Text) Catch ex As Exception MsgBox("The value you entered for the number of pants is not valid" & _ vbCrLf & "Please try again") Exit Sub End Try If (cbxItem1.Text = "None") Or (cbxItem1.Text = "") Then QuantityItem1 = 0 UnitPriceItem1 = 0.0 Else Try UnitPriceItem1 = CDbl(txtUnitPriceItem1.Text) Catch ex As Exception MsgBox("The value you entered for the price is not valid" & _ vbCrLf & "Please try again") Exit Sub End Try Try QuantityItem1 = CInt(txtQuantityItem1.Text) Catch MsgBox("The value you entered is not valid" & _ vbCrLf & "Please try again") Exit Sub End Try End If If (cbxItem2.Text = "None") Or (cbxItem2.Text = "") Then QuantityItem2 = 0 UnitPriceItem2 = 0.0 Else Try UnitPriceItem2 = CDbl(txtUnitPriceItem2.Text) Catch MsgBox("The value you entered for the price is not valid" & _ vbCrLf & "Please try again") Exit Sub End Try Try QuantityItem2 = CInt(txtQuantityItem2.Text) Catch MsgBox("The value you entered is not valid" & _ vbCrLf & "Please try again") Exit Sub End Try End If If (cbxItem3.Text = "None") Or (cbxItem3.Text = "") Then QuantityItem3 = 0 UnitPriceItem3 = 0.0 Else Try UnitPriceItem3 = CDbl(txtUnitPriceItem3.Text) Catch ex As Exception MsgBox("The value you entered for the price is not valid" & _ vbCrLf & "Please try again") Exit Sub End Try Try QuantityItem3 = CInt(txtQuantityItem3.Text) Catch ex As Exception MsgBox("The value you entered is not valid" & _ vbCrLf & "Please try again") Exit Sub End Try End If If (cbxItem4.Text = "None") Or (cbxItem4.Text = "") Then QuantityItem4 = 0 UnitPriceItem4 = 0.0 Else Try UnitPriceItem4 = CDbl(txtUnitPriceItem4.Text) Catch ex As Exception MsgBox("The value you entered for the price is not valid" & _ vbCrLf & "Please try again") Exit Sub End Try Try QuantityItem4 = CInt(txtQuantityItem4.Text) Catch ex As Exception MsgBox("The value you entered is not valid" & _ vbCrLf & "Please try again") Exit Sub End Try End If ' Calculate the sub-total for this item SubTotalShirts = QuantityShirts * UnitPriceShirts SubTotalPants = QuantityPants * UnitPricePants SubTotalItem1 = QuantityItem1 * UnitPriceItem1 SubTotalItem2 = QuantityItem2 * UnitPriceItem2 SubTotalItem3 = QuantityItem3 * UnitPriceItem3 SubTotalItem4 = QuantityItem4 * UnitPriceItem4 ' Calculate the total based on sub-totals CleaningTotal = SubTotalShirts + SubTotalPants + _ SubTotalItem1 + SubTotalItem2 + _ SubTotalItem3 + SubTotalItem4 TaxRate = CDbl(txtTaxRate.Text) ' Calculate the amount owed for the taxes TaxAmount = CleaningTotal * TaxRate / 100 ' Add the tax amount to the total order NetPrice = CleaningTotal + TaxAmount ' Display the sub-total in the corresponding text box txtSubTotalShirts.Text = FormatNumber(SubTotalShirts) txtSubTotalPants.Text = FormatNumber(SubTotalPants) txtSubTotalItem1.Text = FormatNumber(SubTotalItem1) txtSubTotalItem2.Text = FormatNumber(SubTotalItem2) txtSubTotalItem3.Text = FormatNumber(SubTotalItem3) txtSubTotalItem4.Text = FormatNumber(SubTotalItem4) txtCleaningTotal.Text = FormatNumber(CleaningTotal) txtTaxAmount.Text = FormatNumber(TaxAmount) txtNetPrice.Text = FormatNumber(NetPrice) End Sub

5. In the Class Name combo box, select btnClose
6. In the Method Name combo box, select Click and implement the event as follows:
    

   Private Sub btnClose_Click(ByVal sender As Object, _ ByVal e As System.EventArgs) _ Handles btnClose.Click End End Sub

7. Execute the application and create a few orders
    
   
8. Close the form and return to your programming environment

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, first set the Format property to Custom. Then, in the CustomFormat property, use a combination of the following characters to create a custom format:

You can set the format at design time using the Format field on the Properties window. To set the format at run time, assign the desired format to the DateTimePicker.CustomFormat 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 Value property. In the same way, at any time, you can retrieve the time value on the control by accessing the Value property.