CHECKBOX item type

Defines a boolean or three-state checkbox field.

CHECKBOX item basics

The CHECKBOX form item defines a field with a check box and a text label.

Defining a CHECKBOX

The TEXT attribute defines the label to be displayed near the check box. Consider using localized strings for this attribute.

The box shows a check mark when the form field contains the value defined in the VALUECHECKED attribute (for example: "Y"), and shows no check mark if the field value is equal to the value defined by the VALUEUNCHECKED attribute (for example: "N"). If you do not specify the VALUECHECKED or VALUEUNCHECKED attributes, they respectively default to TRUE (integer 1) and FALSE (integer 0).

By default, during an INPUT dialog, a CHECKBOX field can have three states:
  • Grayed ( NULL value )
  • Checked ( VALUECHECKED value )
  • Unchecked ( VALUEUNCHECKED value )

If the field is declared as NOT NULL, the initial state can be grayed if the default value is NULL; once the user has changed the state of the CHECKBOX field, it switches only between checked and unchecked states.

During a CONSTRUCT, a CHECKBOX field always has three possible states (even if the field is NOT NULL), to allow the end user to clear the search condition:
  • Grayed (No search condition)
  • Checked (Condition column = VALUECHECKED value)
  • Unchecked (Condition column = VALUEUNCHECKED value)

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 and CheckBox style attributes.

Detecting CHECKBOX modification

To inform the dialog immediately when the value changes, define an ON CHANGE block for the CHECKBOX field. The program can then react immediately to user changes in the field:

-- Form file (grid layout)
CHECKBOX cb1 = order.ord_valid,
   ITEMS = ... ;

-- Program file:
ON CHANGE ord_valid
   -- The checkbox field has been modified

For more details, see Reacting to field value changes.

Where to use a CHECKBOX

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