Defining the action for a row choice

The row choice in the DISPLAY ARRAY dialog can be associated with a dedicated action.

Action fired by default by current row selection

When using a DISPLAY ARRAY dialog to control a list view like a TABLE, the physical event to choose a row has the following results, depending on the type of front-end:

On the desktop (GDC) or web (GBC) front-end, by default, a mouse double-click changes the current row, and fires the "accept" action, if available. If the default accept action is fired, the dialog will end, except if the accept action has been disabled or was overwritten by an ON ACTION accept handler. This default behavior applies to most record lists of desktop applications, where the main purpose is to let the user choose a row from the list.
On a mobile device (GMA/GMI), there is no concept of double-click as with a mouse. By default, a tap on a row changes the current row only. This corresponds to a single mouse click on a desktop front-end, and therefore does not fire the "accept" action by default. If a tap must fire an action, define that action with the DOUBLECLICK attribute in the DISPLAY ARRAY dialog.

When using an INPUT ARRAY dialog, no row choice action ("accept") is possible by default. However, when setting the DOUBLECLICK attribute, a double click can be detected during INPUT ARRAY.

Defining the name of the row choice action

The action to be fired when a row choice occurs can be defined in the form file with the DOUBLECLICK attribute of the TABLE, TREE or SCROLLGRID containers, or with the DOUBLECLICK attribute of the DISPLAY ARRAY dialog:

DISPLAY ARRAY arr TO sr.*
        ATTRIBUTES(UNBUFFERED, DOUBLECLICK=select)
   ...

The DISPLAY ARRAY attributes DOUBLECLICK, DETAILACTION and ACCESSORYTYPE were introduced for mobile apps, to be used together at dialog configuration level for list configuration.

Note: The DOUBLECLICK attribute in DISPLAY ARRAY takes precedence over the DOUBLECLICK attribute in the list container of a form file.

When defining a DOUBLECLICK action in the list container of the form file, or in a dialog attribute, you declare an explicit action view, and no default action view will be displayed for this action (you can force it with DEFAULTVIEW=YES).

Using the DOUBLECLICK attribute with INPUT ARRAY

With an INPUT ARRAY, field editing is implicit: A double click with the mouse is typically used to select text in an editable field. Therefore, unlike DISPLAY ARRAY, no accept action is fired by default when the user double-clicks on a cell during an INPUT ARRAY.

However, if the TABLE, TREE or SCROLLGRID list container defines the DOUBLECLICK attribute, the corresponding action is fired when a double click occurs, and a row choice action can be implemented in and INPUT ARRAY. This configuration is typically used when the list container has columns defined with non-editable fields like LABEL or EDIT using NOENTRY.

Physical event triggering the row choice action

For desktop and web UI applications, the physical event that fires the row choice action is the mouse double-click, which can be changed with the rowActionTrigger presentation style attribute for the Table, ScrollGrid and Tree classes.

For example, in web applications, the row choice is typically done by a simple mouse click. Define the simple-click physical event to fire the row choice action in your .4st style file as follows:

...
  <Style name="Table">
     <StyleAttribute name="rowActionTrigger" value="singleClick" />
  </Style>
...

Row choice action handler in programs

To handle row choice actions in the program code, define the DOUBLECLICK attribute for the DISPLAY ARRAY dialog, and the corresponding action handler block ON ACTION action-name:

DISPLAY ARRAY arr TO sr.*
        ATTRIBUTES(UNBUFFERED, DOUBLECLICK=select)
   ON ACTION select
      MESSAGE "myselect:", arr_curr()
END DISPLAY

Note: If the DOUBLECLICK attribute is defined, it will only configure the action for the corresponding physical event. By default, the "accept" action is still available, and the [Ok] button or the [Return] key will still fire the accept action and leave the dialog. To avoid the default accept action, add ACCEPT=FALSE to the DISPLAY ARRAY attribute list.

Execution order of row change control blocks

During a DISPLAY ARRAY, if the selected row is not the current row, the AFTER ROW and BEFORE ROW control blocks execute before the ON ACTION block, in the following order:

AFTER ROW (for the previous current row)
BEFORE ROW (for the new current row)
ON ACTION double-click-action