DatePicker

The DatePicker control provides an easy way for a user to select a single date. The user can choose to edit the date in the control or to select a date from a drop-down calendar. The calendar is similar to the MonthCalendar control, which can be used to select a range of dates. As an alternative to the drop-down calendar, you can set the ShowUpDown property to display up and down arrows that allow users to specify one element of the date at a time.

The drop-down calendar can only be used to select a date. The up and down arrows lets users specify a time as well as a date. The following illustration shows three DatePicker controls. The controls on the left have the ShowUpDown property set. One uses the standard date format, and the other uses a custom format that displays the date and time. The control on the right uses the default drop-down calendar option and the standard long date format.

The first control on the left shows a date and the second a date and time in a simple one-line box. The control on the right shows a month in a calendar format with the selected date highlighted.

You can set initial properties for the appearance and behavior of the control in the Properties view. Properties that apply to the drop-down calendar portion of the control are similar to the properties that apply to the MonthCalendar control and display on the Calendar page in the Properties view. For example, you can choose which day of the week displays as the first day in the week, whether the current date is circled, and whether a “Today Section” showing the current date displays at the bottom of the calendar.

Specifying a format

You can choose to display the date in the DatePicker control as a long date, a short date, a time, or with a custom format. To set a custom format in the painter, select dtfCustom! from the Format list and type the format in the Custom Format field. For example, the second control on the left in the previous illustration uses the custom format yyyy/MM/dd HH:mm:ss. The uppercase H for the hour format specifies a 24-hour clock. The following statements set the Format property to use a custom format and set the CustomFormat property to show the full name of the month, the day of the month followed by a comma, and the four-digit year:

dp_1.Format = dtfCustom!
dp_1.CustomFormat = "MMMM dd, yyyy"

For a complete list of formats you can use, see the description of the CustomFormat property in the online Help.

Specifying maximum and minimum dates

The MaxDate and MinDate properties determine the range of dates that a user can enter or pick in the control. If you set a restricted range, the calendar displays only the months in the range you set, and if users type a date outside the range into the control, the date reverts to its previous value.

Editing modes

When a user tabs into a DatePicker control, the control is in normal editing mode and behaves in much the same way as an EditMask control with a Date or DateTime mask. Users can edit the part of the date (year, month, day, hour, minutes, or seconds) that has focus using the up/down arrow keys on the keyboard or, for numeric fields, the number keys. Use the left/right arrow keys to move between parts of the date.If the control has a drop-down calendar, users can navigate from one month or year to another using the controls in the calendar and click to select a date. If the ShowUpDown option is set, users can change the selected part of the date or time with the up and down keys in the control. To navigate in the drop-down calendar, a user can:

Click the arrows in the top corners to move from month to month
Click the month to display a list of months, then click a month to select it
Click the year to display a spin control, then use the spin control’s arrows to select a year
Click a date to select the date and close the calendar
Press the Esc key to close the calendar without changing the selection

Allowing users to edit the date directly

You can give users a third way to change the date by setting the AllowEdit property to true. The user can then press F2 or click in the control to select all the text in the control for editing. When the control loses focus, the control returns to normal editing mode and the UserString event is fired. The UserString event lets you test whether the text the user entered in the control is a valid date and set the value to the new date if it is valid. If it is valid, you can use the event’s dtm by reference argument to set the value to the new date. This code in the UserString event tests whether the date is valid and within range:

Date d
DateTime dt

IF IsDate(userstr) THEN
   d = Date(usrstr)
   IF (this.maxdate >= d and this.mindate <= d) THEN
      dtm = DateTime(dt)
   ELSE
      MessageBox("Date is out of range", userstr)
   END IF
ELSE
   MessageBox("Date is invalid", userstr)
END IF

The Value property

The Value property contains the date and time to which the control is set. If you do not specify a date, the Value property defaults to the current date and time. You can set the property in the painter or in a script. If you change the value at runtime, the display is updated automatically. The Value property has two parts that can be obtained from the DateValue and TimeValue properties. These properties should be used only to obtain the date and time parts of the Value property; they cannot be used to set a date or time. The Text property and the GetText function return the Value property as a string formatted according to your format property settings.

You can use the SetValue function to set the Value property in a control using separate date and time values or a single DateTime value. This example sets the property control using separate date and time values:

date d
time td=date("2007/12/27")
t=time("12:00:00")dp_1.SetValue(d, t)

This example sets the Value property using a DateTime value:

date d
time t
datetime dt
dt = DateTime(d, t)

dp_1.SetValue(dt)

Localizing the DatePicker control

The DatePicker control is designed to work in different locales. The string values in the DatePicker control support non-English charactersand the names of months and days of the week in the calendar display in the local language. You can set the FirstDayOfWeek property on the Calendar page in the Properties view to have the drop-down calendar use Monday or any other day of the week as the first day.

The MaxDate and MinDate properties and the date part of the Value property use the Short Date format specified in the regional settings in the Windows control panel of the local computer, and the time part uses the local computer’s time format. The three predefined display formats—long date, short date, and time—also depend on the local computer’s regional settings.