| Usage / Programming with DIALOG | |
DISPLAY ARRAY can allow multiple row selection with the DIALOG.setSelectionMode() method. When multi-row selection is enabled, the end user can select one or several rows with the standard keyboard and mouse click combinations. The program can then query the DIALOG.isRowSelected() method to check for selected rows.
Multi-row selection is GUI-specific and therefore can't be used in TUI mode.
With multi-row selection, you must distinguish between two concepts: row selection and current row. In GUI mode, a selected row usually has a blue background, while the current row has a dotted focus rectangle. The current row may not be selected, or a selected row may not be the current row. Selection flags can be changed by program for a range of rows with the DIALOG.setSelectionRange() method.
When the default single-row selection is used, the current row is always selected automatically.
The DISPLAY ARRAY dialog implements an implicit row-copy feature: The selected rows can be dragged to another dialog or external program, or the end-user can do an editcopy predefined action (Ctrl-C shortcut), to copy the selected rows to the front-end clipboard. The row-copy feature works also when multi-row selection is disabled, but only the current row will be dragged or copied to the front-end clipboard.
It is mandatory to specify the UNBUFFERED attribute for the DIALOG or singular DISPLAY ARRAY instruction, otherwise if selection flags are changed by program, the front-end will not be automatically synchronized.
If you delete, insert or append rows in the program array with methods such as array.deleteElement(), selection information is not synchronized: You must use dialog methods, like DIALOG.insertRow() (or DIALOG.insertNode() for tree-views), to sync the selection flags with the data rows.
| Dialog class method | Effect on multi-row selection |
|---|---|
| appendRow() | Selection flags of existing rows are unchanged. New row is appended at the end of the list with selection flag set to zero. |
| appendNode() | Selection flags of existing rows are unchanged. New node is appended at the end of the tree with selection flag set to zero. |
| deleteAllRows() | Selection flags of all rows are cleared. |
| deleteRow() | Selection flags of existing rows are unchanged. Selection information is synchronized (i.e., shifted up) for all rows after the deleted row. |
| deleteNode() | Selection flags of existing rows are unchanged. Selection information is synchronized (i.e., shifted up) for all nodes after the deleted node. |
| insertRow() | Selection flags of existing rows are unchanged. Selection information is synchronized (i.e., shifted down) for all rows after the new inserted row. |
| insertNode() | Selection flags of existing rows are unchanged. Selection information is synchronized (i.e., shifted down) for all nodes after the new inserted node. |
| setArrayLength() | Selection flags of existing rows are unchanged. If the new array length is larger than the previous length, selection flags of new rows are not initialized to zero. |
| setCurrentRow() | Selection flags of all rows are reset, and the new current row gets selected. |
| setSelectionMode() | When you switch off multi-row selection, the selection flags of existing rows are cleared. |