4D Doc Center : INSERT IN LIST

4D v13.4

INSERT IN LIST


INSERT IN LIST ( {* ;} list ; beforeItemRef \| * ; itemText ; itemRef {; sublist ; expanded} )

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)
beforeItemRef \| *	Longint, Operator	Item reference number or 0 for the last item added to the list or * for the currently selected list item
itemText	String	Text for the new list item
itemRef	Longint	Unique reference number for the new list item
sublist	ListRef	Optional sublist to attach to the new list item
expanded	Boolean	Indicates if the sublist will be expanded or collapsed

Description

The INSERT IN LIST command inserts the item designated by the itemRef parameter 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 structural items (the second * is omitted), you can use either syntax. Conversely, if you use several representations of the same list and work with the current item (the second * is passed), the syntax based on the object name is required since each representation can have its own current item.

The beforeItemRef parameter can be used to designate the item before which you wish to insert the new item:

You can pass the value 0 in order to designate the last item added to the list. The newly inserted item will then become the selected item.
You can pass * in order for the new item to be inserted before the currently selected item in the list. In this case, the newly inserted item will also become the selected item.
Otherwise, if you want to insert an item before a specific item, you pass the item reference number of that item. In this case, the newly inserted item is not automatically selected. If there is no item with the corresponding item reference number, the command does nothing.

You pass the text and the item reference number of the new item in itemText and itemRef.

If you want for the item to include subitems, pass a valid list reference number in the sublist parameter. In this case, you must also pass the expanded parameter. Pass either True or False in this parameter so that this sublist is displayed either expanded or collapsed respectively.

Example

The following code inserts an item (with no attached sublist) just before the currently selected item in the hList list:

 vlUniqueRef:=vlUniqueRef+1

 INSERT IN LIST(hList;*;"New Item";vlUniqueRef)