DATETIMEEDIT item type

Defines a line-edit with a calendar widget to pick a datetime.

DATETIMEEDIT item basics

The DATETIMEEDIT form item defines a field that can open a calendar to ease date-time input.

To store DATETIMEEDIT field values, use a DATETIME YEAR TO MINUTE or DATETIME YEAR TO SECOND program variable, depending on the target front-end.

DATETIMEEDIT widget constraints

Depending on the front-end platform, the widget and time picker to render a DATETIMEEDIT field may have the following limitations:
  • Date-time editor and calendar may not handle seconds and some front-ends may deny data types different from DATETIME YEAR TO {MINUTE|SECOND}. If the front-end does not support the data type used for the DATETIMEEDIT field, the runtime system raises an error and stops the program.
  • Date-time editors may not allow to specify NULL.
  • The widget may allow only strict date-time value input, and therefore cannot be used with a CONSTRUCT instruction, where it must be possible to enter search filters like ">= 2014-01-23 11:00".
Tip: Consider testing your application forms using DATETIMEEDIT fields with all types of front-ends.

Defining a DATETIMEEDIT

The DATETIMEEDIT form item type allows the user to edit date-time values with a specific widget for date-time input. A DATETIMEEDIT field typically provides a calendar and clock widget, to let the end user pick a date and time from it.

When using a DATETIME variable as recommended, with desktop front-ends, the format of DATETIMEEDIT fields is defined by the DBDATE environment variable. On mobile platforms, the date format is defined by the device OS language settings.

Front-ends support different presentation and behavior options, which can be controlled by a STYLE attribute. For more details, see Style attributes common to all elements.

Detecting DATETIMEEDIT calendar selection

To inform the dialog when a date-time is picked from the calendar widget, define an ON CHANGE block for the DATETIMEEDIT field. The program can then react immediately to user changes in the field:

-- Form file (grid layout)
DATETIMEEDIT dt1 = order.ord_shipdate,
   NOT NULL;

-- Program file:
ON CHANGE ord_shipdate
   -- A new date-time value was picked from the calendar

For more details, see Reacting to field value changes.

Where to use a DATETIMEEDIT

A DATETIMEEDIT form item can be defined with an item tag and a DATETIMEEDIT item definition in a GRID, SCROLLGRID and TABLE/TREE.

Defining the widget size

The size of a DATETIMEEDIT widget is computed by following the layout rules as described in Widget width inside hbox tags.

Field input length

The input length in a DATETIMEEDIT fields is defined by the (DATETIME) program variable. Define an item tag with enough positions to be able to display dates with 4 year digits. For more details, see Input length of form fields.