RADIOGROUP item type

Defines a mutual exclusive set of options field.

RADIOGROUP item basics

The RADIOGROUP form item defines a field that provides several options that the user can make a selection from. Checking one radio button unchecks any previously checked button within the same group.

Defining a RADIOGROUP

A RADIOGROUP defines a set of radio buttons where each button is associated with a value defined in the ITEMS attribute.

The text associated with each item value will be used as the label of the corresponding radio button, for example: ITEMS=((1,"Beginner"), (2,"Normal"), (3,"Expert")) will create three radio buttons with the texts Beginner, Normal and Expert, respectively.

RADIOGROUP ...
   ITEMS=((1,"Beginner"),(2,"Normal"),(3,"Expert"));

Consider using localized strings when defining key/value pairs in the radio group items:

RADIOGROUP ...
   ITEMS=((1,%"skills.beginner"),
          (2,%"skills.normal"),
          (3,%"skills.expert"));

If the ITEMS attribute is not specified, the form compiler automatically fills the list of items with the values of the INCLUDE attribute, when specified. However, the item list will not automatically be populated with include range values (that is values defined using the TO keyword). The INCLUDE attribute can be specified directly in the form or indirectly in the schema files.

During an INPUT, a RADIOGROUP field value can only be one of the values specified in the ITEMS attribute. During a CONSTRUCT, a RADIOGROUP field allows all items to be unchecked (even if the field is NOT NULL), to let the user clear the search condition.

If one of the items is explicitly defined with NULL and the NOT NULL attribute is omitted, in INPUT, selecting the corresponding radio button sets the field value to null. In CONSTRUCT, selecting the radio button corresponding to null will be equivalent to the equals (=) query operator, which will generate a "colname is null" SQL condition.

Use the ORIENTATION attribute, to define if the radio group items must be arranged vertically or horizontally:

RADIOGROUP ...
   ITEMS=(...),
   ORIENTATION = HORIZONTAL;

A radio group can adapt its orientation for responsive layout, if you specify a @screen-size modifier for the ORIENTATION attribute:

RADIOGROUP ...
   ORIENTATION@SMALL = VERTICAL, -- no really needed: default is vertical
   ORIENTATION@MEDIUM = HORIZONTAL,
   ORIENTATION@LARGE = HORIZONTAL;

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 RADIOGROUP item selection

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

-- Form file (grid layout)
RADIOGROUP rg1 = user.user_skill,
   ITEMS = ... ;

-- Program file:
ON CHANGE user_skill
   -- An new item was selected in the radiogroup

For more details, see Reacting to field value changes.

Where to use a RADIOGROUP

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