SET LIST PROPERTIES

version 2004 (Modified)

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

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 4th Dimension in the Hierarchical Lists theme:

In the Windows appearance, the list has connecting dotted lines between the nodes and branches. One icon (+) denotes the collapsed nodes, a second one (–) the expanded nodes. Nodes without child items have no icon. Here is a default hierarchical list in Windows appearance:

In the Macintosh appearance, the list has no connecting dotted lines. One icon denotes the collapsed nodes, a second one 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 4th Dimension.

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

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

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 icons that is too tall or too wide, it will be displayed truncated and/or will be overidden by the connecting dotted lines (if appearance is Windows), as well as 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 4th Dimension, 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.

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 

In addition, the structure file of the database has been edited so it contains the following 'cicn' color icon resources:

1. With the following line:

   SET LIST PROPERTIES(hlCities;Ala Macintosh;Macintosh node)

The hierarchical list will look like this:

2. With the following line:

   SET LIST PROPERTIES(hlCities;Ala Windows;Windows node)

The hierarchical list will look like this:

3. With the following line:

   SET LIST PROPERTIES(hlCities;Ala Windows;20000)

The hierarchical list will look like this:

4. With the following line:

   SET LIST PROPERTIES(hlCities;Ala Macintosh;20010)

The hierarchical list will look like this:

The 'cicn' color icon resources shown are then added to the structure file of the database:

5. With the following line:

   SET LIST PROPERTIES(hlCities;Ala Windows;20020;32)

The hierarchical list will look like this:

GET LIST ITEM PROPERTIES, GET LIST PROPERTIES, SET LIST ITEM PROPERTIES.