OBJECT SET LIST BY REFERENCE

Home

4D v16.3


OBJECT SET LIST BY REFERENCE ( {* ;} object {; listType}; list )

Parameter	Type	Description
*	Operator	If specified, object is an object name (string) If omitted, object is a field or variable
object	Form object	Object name (if * is specified) or Field or variable (if * is omitted)
listType	Longint	Type of list: Choice list, Required list or Excluded list
list	ListRef	List reference number

Description

The OBJECT SET LIST BY REFERENCE command defines or replaces the list associated with the object(s) designated by the object and * parameters, with the hierarchical list referenced in the list parameter.

Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only).

By default, if you omit the listType parameter, the command defines a source choice list (choice of values) for the object. You can designate any type of list in the listType parameter. To do this, you just need to pass one of the following constants found in the "Form Objects (Properties)" theme:

Constant	Type	Value	Comment
Choice list	Longint	0	Simple list of values to choose from ("Choice List" option in the Property List) (default)
Excluded list	Longint	2	Lists values not accepted for entry ("Excluded List" option in the Property List)
Required list	Longint	1	Lists only values accepted for entry ("Required List" option in the Property List)

In list, pass the reference number of the hierarchical list that you want to associated with the object. This list must have been generated using the Copy list, Load list or New list command.

To end the association of a list with an object, you can just pass 0 in the list parameter for the type of list concerned.

Removing a list association does not delete the list reference from memory. Remember to call the CLEAR LIST command when you no longer need the list.

This command is particularly interesting in the context of a pop-up or combo box associated with a variable or a field (see the Design Reference manual). In this case, the association is dynamic and any change in the list is copied to the form. When the object is associated with an array, the list is copied into the array and any changes to the list are not available automatically (see example 5).

Example 1

Associating a simple choice list (default list type) to a text field:

 vCountriesList:=New list

 APPEND TO LIST(vCountriesList;"Spain";1)

 APPEND TO LIST(vCountriesList;"Portugal";2)

 APPEND TO LIST(vCountriesList;"Greece";3)

 OBJECT SET LIST BY REFERENCE([Contact]Country;vCountriesList)

Example 2

Associating the "vColor" list as a simple choice list with the "DoorColor" pop-up/drop-down list:

 vColor:=New list

 APPEND TO LIST(vColor;"Blue";1)

 APPEND TO LIST(vColor;"Green";2)

 APPEND TO LIST(vColor;"Red";3)

 APPEND TO LIST(vColor;"Yellow";4)

 OBJECT SET LIST BY REFERENCE(*;"DoorColor";Choice list;vColor)

Example 3

Now you want to associate the "vColor" list with a combo box named "WallColor". Since this combo box is enterable, you want to make sure certain colors, such as "black," "purple," etc., cannot be used. These colors are placed in the "vReject" list:

 OBJECT SET LIST BY REFERENCE(*;"WallColor";Choice list;vColor)

 vReject:=New list

 APPEND TO LIST(vReject;"Black";1)

 APPEND TO LIST(vReject;"Gray";2)

 APPEND TO LIST(vReject;"Purple";3)

 OBJECT SET LIST BY REFERENCE(*;"WallColor";Excluded list;vReject)

Example 4

You want to remove the list associations:

 OBJECT SET LIST BY REFERENCE(*;"WallColor";Choice list;0)

 OBJECT SET LIST BY REFERENCE(*;"WallColor";Required list;0)

 OBJECT SET LIST BY REFERENCE(*;"WallColor";Excluded list;0)

Example 5

This example illustrates the difference in how the command works when applied to a pop-up menu associated with a text array or one associated with a text variable. There are two pop-up menus in a form:

The contents of these pop-up menus is set using the <>vColor list (containing color values). The following code is executed when the form is loaded:

 ARRAY TEXT(arr1;0) //arr1 pop up

 C_TEXT(text1) //text1 pop up

 OBJECT SET LIST BY REFERENCE(*;"arr1";<>vColor)

 OBJECT SET LIST BY REFERENCE(*;"text1";<>vColor)

During execution, both menus propose the same values:

(Montage showing contents of menus simultaneously)

Then you run the following code, for example by means of a button:

 APPEND TO LIST(<>vColor;"White";5)

 APPEND TO LIST(<>vColor;"Black";6)

Only the menu associated with the Text field is updated (by means of the dynamic reference):

In order to update the list associated with the pop-up managed by array, you need to call the OBJECT SET LIST BY REFERENCE command again to copy the contents of the list.