DojoTimeTextBox

The DojoTimeTextBox widget defines a text box that contains a time value. This widget is based on the Dojo dijit.form.TimeTextBox definition.

When the user clicks into the widget, it provides a time-selection menu, which is a graphical list of times. The user can select a listed time to update the value that is displayed in the box.

You can customize the time-selection menu by setting the visibleIncrement and visibleRange properties; and you can customize the time value shown in the time text box by setting the value and timePattern properties.

Here are the supported properties for DojoTimeTextBox:

constraints

A dictionary that is used as an argument during the invocation of functions that in turn validate user input. Those functions are referenced by the validators property and are referred to as validator functions.

The content of the dictionary is appropriate to your business need. Here is an example assignment:

constraints = new Dictionary{minimumHour = "11:30 AM"}};

In this case, a validator function might return an error message if the user specifies a time less than 11:30 AM.

errorMessage

The message that is displayed when the input is present but invalid. The message is displayed in an output field or tooltip that is provided for you.

inputRequired

A Boolean value that indicates whether input is required. The error message in this case is the value of the inputRequiredMessage property.

This validation precedes any others, but is active only after the field gains focus after having lost focus.

inputRequiredMessage

A string that is displayed when the InputRequired property is true, the time text box has no content, and the box gains focus after having lost focus. The message is displayed in an output field or tooltip that is provided for you.

If the inputRequiredMessage property is not present, the error message is the following string, as appropriate to the locale: "This value is required".

placeholder

A string that is displayed in the time text box but that is removed as soon as the user clicks into the box. The string is re-displayed in the time text box whenever the box is empty and the user is not working there.

promptMessage

A string that prompts the user's input. When the time text box gains focus, the string is displayed next to the box, in a tooltip that is provided for you, and the display continues until the user begins adding or changing content. To further set the string position, set the tooltipPosition property.

readOnly

A Boolean value that indicates whether the time text box is protected from user input.

selectOnClick

A Boolean value that indicates what happens when the user clicks from outside the time text box into the box:

False (the default): The content of the time text box is not selected. The update cursor is displayed at the click position.
True: The content of the time text box is selected. Any subsequent click displays the update cursor at the click position, and the content of the time text box is no longer selected.

suppressChangeEvent

A Boolean value that prevents the onChange events after setting this value to true by code.

text

A string that is formatted to match the default format in use. If you set the property in the widget declaration, the string must match the setting of the defaultTimeFormat build descriptor option. If you set the property at run time, the string must match the setting of the StrLib.defaultTimeFormat system function, which itself defaults to the value of the defaultTimeFormat build descriptor option.

The default value of the defaultTimeFormat option is HH:mm:ss.

timePattern

A string constant that indicates how the time is displayed:

TIMEBOX_FORMAT_12HR: Displays a time that is formatted between 12:00 AM to 11:59 AM and between 12:00 PM to 11:59 PM.
TIMEBOX_FORMAT_24HR: Displays a 24-hour (military) time.

validators

An array of validator functions that are invoked in array-element order. If the user's input passed validation in a given function, that function indicates the success by returning a null or blank; and only in that case is the next function in the array invoked. If the user's input did not pass validation, the function indicates a failure by returning a nonblank string.

The sequence of validators is invoked when the widget loses focus.

If the Dojo time text box is referenced by a controller, you can code controller-specific validator functions, which are wholly separate from the functions being described. The controller-specific functions are invoked only if the field-specific validation is successful and only after the widget loses focus.

For details on controllers, see Rich UI validation and formatting.

Each of the field-specific validator functions conforms to the following Delegate part:

Delegate Validator(input String in, constraints dictionary in)
         returns(string?) end

input: The user's input.
constraints: A dictionary that provides information used to construct a regular expression or to guide processing inside the validator functions. For example, the dictionary might specify the user's level of security.
string?: A null or blank (if no error occurred) or a nonblank string (to indicate that an error occurred).

You might want to invoke, from your validator, one or more of the functions provided in the DojoLib library.

value

A time variable, although an automatic conversion allows use of a string.

visibleIncrement

The increment that is shown on the time-selection menu. graphical list of times. One of the following constants:

TIMEBOX_ONE_QUARTER (the default, to display 15-minute increments)
TIMEBOX_FIVE_MINUTES
TIMEBOX_HALF_HOUR
TIMEBOX_ONE_HOUR
TIMEBOX_TWO_HOURS
TIMEBOX_THREE_HOURS
TIMEBOX_FIVE_HOURS
TIMEBOX_TEN_HOURS
TIMEBOX_TWELVE_HOURS
TIMEBOX_FULL_DAY (to display 24-hour increments)

visibleRange

The range of times to display in the time-selection menu. The user can scroll to other times, if necessary. The constants are the same as for the visibleIncrement property.

The following functions are specific to the EGL Dojo widget types that support view-level validation, as listed in Rich UI validation and formatting:

getValidState

Is solely for internal use.

showErrorIndicator

Accepts a Boolean value that sets or clears the error indicator in the widget. Here is the function prototype:

function showErrorIndicator(aboolean boolean in);

showErrorMessage

Accepts an error message for display in the error-message tooltip near the widget. The tooltip is shown when the widget gains focus and is hidden when the widget loses focus. Here is the function prototype:

function showErrorMessage(msg string in);

Other supported properties and functions are described in Widget properties and functions and Widget styles.