4D Doc Center : Selected list items

4D v13.4

Selected list items


Selected list items ( {* ;} list {; itemsArray {; *}} ) -> Function result

Parameter	Type	Description
*	Operator	If specified, list is an object name (string) If omitted, list is a list reference number
list	ListRef, String	List reference number (if * omitted), or Name of list type object (if * passed)
itemsArray	Longint array	If 2nd * omitted: Array contains the positions of selected items in the list(s) If 2nd * passed: Array contains the selected item references
*	Operator	If omitted: Item position(s) If passed: Item reference(s)
Function result	Longint	If 2nd * omitted: Position of current selected list item in expanded/collapsed list(s) If 2nd * passed: Reference of the selected item

Description

The Selected list items command returns the position or reference of the selected item in the list whose reference number or object name you pass in list.

If you pass the first optional * parameter, you indicate that the list parameter is an object name (string) corresponding to a representation of the list in the form. If you do not pass this parameter, you indicate that the list parameter is a hierarchical list reference (ListRef). If you only use a single representation of the list or work with item references (the second * is passed), you can use either syntax. Conversely, if you use several representations of the same list and work with the item positions (the second * is omitted), the syntax based on the object name is required since each representation can have its own expanded/collapsed item configuration.

Note: If you use the @ character in the name of the list object and the form contains several lists that match with this name, the Selected list items command will only apply to the first object whose name corresponds.

In the case of multiple selection, the command can also return in the itemsArray array, the position or reference of each item selected. You apply this command to a list displayed in a form to detect which item(s) the user has selected.

The second * parameter lets you indicate whether you want to work with current item positions (in this case, the * parameter should be omitted) or with fixed item references (in this case, the * parameter must be used).

You can pass a longint array in the itemsArray parameter. If necessary, the array will be created and resized by the command. Once the command has been executed, itemsArray will contain:

the position of each item selected relative to the expanded/collapsed state of the list(s) if the * parameter is omitted.
the fixed reference of each item selected if the * parameter is passed.
If no items have been selected, the array is returned empty.

Note: In the event of multiple selections, the command returns the position or reference of the current item of list. The current item is the last item clicked by the user (manual selections) or the item set by the SELECT LIST ITEMS BY POSITION or Selected list items commands (programmed selection).

If the list has sublists, you apply the command to the main list (the one actually defined in the form), not one of its sublists. The positions are expressed relative to the top item of the main list, using the current expanded/collapsed state of the list and its sublist.

In any case, if no items are selected, the function returns 0.

Example

Here a list named hList, shown in the Application environment:

$vlItemPos:=Selected list items(hList) ` at this point $vlItemPos gets 2

 $vlItemPos:=Selected list items(hList) ` at this point $vlItemPos gets 5

 $vlItemRef:=Selected list items(hList;*) ` $vlItemRef gets 200 (for instance)

 $vlItemPos:=Selected list items(hList) ` at this point $vlItemPos gets 8

 $vlItemRef:=Selected list items(hList;*) ` $vlItemRef gets 203 (for instance)

 $vlItemPos:=Selected list items(hList;$arrPos) ` at this point, $vlItemPos gets 3

  ` $arrPos{1} gets 3, $arrPos{2} gets 4 and $arrPos{3} gets 5

 $vlItemRef:=Selected list items(hList;$arrRefs;*) ` $vlItemRef gets 203 (for instance)

  ` $arrRefs{1} gets 101, $arrRefs{2} gets 203 (for instance)