SELECT LISTBOX ROW

version 11.2 (Modified)

SELECT LISTBOX ROW ({*; }object; position{; action})

The SELECT LISTBOX ROW command selects the row whose number is passed in position in the list box set in the object and * parameters.

If you pass the optional * parameter, you indicate that the object parameter is an object name (string). If you do not pass this parameter, you indicate that the object parameter is a variable. In this case, you do not pass a string, but a variable reference. For more information about object names, refer to the Object Properties section.

The optional action parameter, if passed, is used to define the selection action to execute when a selection of rows already exists in the list box. You can pass a value or one of the following constants (located in the "List box" theme):

• Replace listbox selection (0): The row selected becomes the new selection and replaces the existing selection. The command has the same effect as a user click on a row. This is the default action (if the action parameter is omitted).

• Add to listbox selection (1): The row selected is added to the existing selection. If the row specified already belongs to the existing selection, the command does nothing.

• Remove from listbox selection (2): The row selected is removed from the existing selection. If the row specified does not belong to the existing selection, the command does nothing.

When the position parameter does not correspond exactly to an existing row number, the command works as follows:

• If position is <0, the command does nothing, regardless of the action parameter value.

• If position is 0 and if the action parameter contains Replace listbox selection or is omitted, all the rows of the listbox are selected. If the action parameter contains Remove from listbox selection, all the listbox rows are deselected.

• If the position value is greater than the total number of rows contained in the listbox, the Boolean array associated with the listbox is automatically resized and the selection action is carried out. This mechanism means that you can use SELECT LISTBOX ROW with "standard" array management commands (such as APPEND TO ARRAY) that do not cause immediate synchronization of the listbox.

After execution of the method, the arrays are synchronized: if the source array of the listbox has indeed been resized, the selection action is carried out. Otherwise, the Boolean array associated with the listbox returns to its initial size and the command does nothing.

Notes:

• If you want the list box to scroll automatically in order to display the row selected, use the SCROLL LINES command.

• To switch a row into editing mode (to allow data entry), use the EDIT ITEM command.

• If the number passed in position corresponds to a hidden row in the list box, the row is selected but not displayed.

DELETE LISTBOX ROW, EDIT ITEM, INSERT LISTBOX ROW, SCROLL LINES.