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 the field value, use a DATETIME YEAR TO MINUTE or DATETIME YEAR TO SECOND program variable with such form item.

Important: DATETIMEEDIT fields are dedicated for DATETIME value input. Some front-ends (especially on mobile devices) deny data types different from DATETIME. 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. Consider testing your application 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.

The display and input precision (time part with or without seconds) of the DATETIMEEDIT widget depends on the front-end. On some platforms, native date-time editors do not handle the seconds. Furthermore, some front-ends (especially on mobile devices) do not allow data types different from DATETIME YEAR TO {MINUTE|SECOND}.

On some front-end platforms, the native widget used for DATETIMEEDIT fields 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".

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 in different ways:
  1. With an item tag and a DATETIMEEDIT item definition in a grid-layout container (GRID, SCROLLGRID and TABLE).
  2. As a DATETIMEEDIT stack item in a STACK container.

Defining the widget size

In a grid-based layout, the size of a DATETIMEEDIT widget is computed by following the layout rules as described in Widget size within hbox tags.

In a stack-based layout, the widget will take the full width available in the parent container.

Field input length

The input length in a DATETIMEEDIT fields is defined by the (DATETIME) program variable. In a grid-based layout, 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.