4D Doc Center : SET LIST PROPERTIES

4D v13.4

SET LIST PROPERTIES


SET LIST PROPERTIES ( list ; appearance {; icon {; lineHeight {; doubleClick {; multiSelections {; editable}}}}} )

Parameter	Type	Description
list	ListRef	List reference number
appearance	Longint	Graphical style of the list 1 = Hierarchical list a la Macintosh 2 = Hierarchical list a la Windows 0 = Auto appearance depending on platform
icon	Longint	‘cicn’ Mac OS-based resource ID or 0 for default platform node icon
lineHeight	Longint	Minimal line height expressed in pixels
doubleClick	Longint	Expand/Collapse sublist on double-click 0 = Yes, 1= No
multiSelections	Longint	Multiple selections: 0 = No (default), 1 = Yes
editable	Longint	0 = List is not editable by user, 1 = List is editable by user (default)

Description

The SET LIST PROPERTIES command sets the appearance of the hierarchical list whose list reference you pass in list.

The parameter appearance can be one of the following predefined constants provided by 4D in the Hierarchical Lists theme:

Constant	Type	Value
Ala Macintosh	Longint	1
Ala Windows	Longint	2

In the Windows appearance, the icon (+) denotes collapsed nodes, and the icon (–) denotes expanded nodes. Nodes without child items have no icon. Here is a default hierarchical list in Windows appearance:

In the Macintosh appearance, a rightward-pointing arrow icon denotes the collapsed nodes, and a downward-pointing icon denotes the expanded nodes. Nodes without child items have no icon. Here is a default hierachical list in Macintosh appearance:

If you display a hierarchical list object without calling SET LIST PROPERTIES or pass 0 in the appearence parameter, the list appears with the default Windows or Macintosh appearances, depending on the Platform Interface property choosen for the object in the Design environment's Form Editor.

The parameter icon indicates the icons that will be displayed for each node. The value passed in icon sets the icon for collapsed nodes and icon+1 sets the icon for expanded nodes.

For example, if you pass 15000, the color icon 'cicn' ID=15000 will be displayed for each collapsed node and the color icon 'cicn' ID=15001 will be displayed for each expanded node.

It is therefore important to have these 'cicn' color icon resources present in your database structure file. If a color icon resource is missing, the corresponding nodes are displayed with no icons. (You can actually take advantage of this to display a list with no icons.)

WARNING: When creating 'cicn' color icon resources, use resource IDs greater than or equal to 15000. Resource IDs less than 15000 are reserved for 4D.

The resource IDs of the default Macintosh and Windows nodes are expressed by the following predefined constants provided by 4D:

Constant	Type	Value
Macintosh node	Longint	860
Windows node	Longint	138

In other words, 4D provides the following 'cicn' resources:

ID Number	Description
860	Collapsed node a la Macintosh
861	Expanded node a la Macintosh
138	Collapsed node a la Windows
139	Expanded node a la Windows

If you do not pass the parameter icon or pass 0, the nodes are displayed with the default icons of the chosen appearance type.

Color icon resources can be of various sizes. For example, you can create 16x16 or 32x32 color icons.

If you do not pass the parameter lineHeight, the line height of a hierarchical list is determined by the font and font size used for the object. If you use a color icon that is too tall or too wide, it will be displayed truncated and/or will be overridden by the text of the nodes above or below it.

Choose color icon size, font, and font size accordingly, otherwise pass in the parameter lineHeight the minimal line height of the hierarchical list. If the value you pass is greater than the line height derived from the font and font size used, the line height of the hierarchical list will be forced to the value you pass.

Note: SET LIST PROPERTIES affects the way nodes are displayed in the hierarchical list. If you would rather customize the icon of each item in the list, use the command SET LIST ITEM PROPERTIES.

The optional parameter doubleClick allows you to define that a double-click on a parent list item will not provoke the sublist to expand or to collapse. By default, a double-click on a parent list item provokes its child list to expand or to collapse. However, some user interfaces may need to deactivate this behavior. To do this, the doubleClick parameter should be set to 1.
Only double-click will be deactivated. Users will still be able to expand or collapse sublists by clicking on the list node.
If you omit the doubleClick parameter or pass 0, default behavior will be applied.

The optional multiSelections parameter lets you indicate whether the list must accept multiple selections.
By default, as in previous versions of 4D, you cannot simultaneously select several items of a hierarchical list. If you would like this function to be available for the list, pass the value 1 in the multiSelections parameter. In that case, multiple selections can be used:

manually, using the Shift+click key combination for a continuous selection or Ctrl+click (Windows) / Command+click (Mac OS) for a discontinuous selection,
by programming, using the SELECT LIST ITEMS BY POSITION and SELECT LIST ITEMS BY REFERENCE commands.
If you pass 0 or omit the multiSelections parameter, the default behavior will be applied.

The optional editable parameter lets you indicate whether the list must be editable by the user when it is displayed as a choice list associated with a field or a variable during data entry. When the list is editable, a Modify button is added in the choice list window and the user can add, delete and sort the values through a specific editor.
If you pass 1 or omit the editable parameter, the list will be editable; if you pass 0, it will not be editable.

Example

The following hierarchical list has been defined in the Design environment List Editor:

Within a form, the hierarchical list object hlCities reuses that list with this object method:

 Case of

    :(Form event=On Load)

       hlCities:=Load list("Cities")

       SET LIST PROPERTIES(hlCities;vlAppearance;vlIcon)

    :(Form event=On Unload)

       CLEAR LIST(hlCities;*)

 End case