4D lets you specify and use hierarchical list boxes. A hierarchical list box is a list box in which the contents of the first column appears in hierarchical form. This type of representation is adapted to the presentation of information that includes repeated values and/or values that are hierarchically dependent (country/region/city and so on).

Only aray type list boxes can be hierarchical. 

Hierarchical list boxes are a particular way of representing data but they do not modify the data structure (arrays). Hierarchical list boxes are managed exactly the same way as regular list boxes.

To specify a hierarchical list box, there are three different possibilities:

• Manually configure hierarchical elements using the Property list of the form editor.
• Visually generate the hierarchy using the list box management pop-up menu, in the form editor.
• Use the LISTBOX SET HIERARCHY and LISTBOX GET HIERARCHY commands, described in the 4D Language Reference manual.

This section covers how to create hierarchical list boxes in the 4D Form editor and the basics of how they work during execution, as well as how to manage them (selections, breaks, using On Expand and On Collapse form events, etc. ).

You can enable and configure the hierarchical mode in the "Hierarchy" theme of the Property List. For more information, refer to List box specific properties.

When you click on the columns area of a list box, the context menu of the Form editor contains the Create hierarchy and Cancel hierarchy commands.

When you select at least one column in addition to the first one in a list box object (of the array type) in the form editor, the Create hierarchy command is available in the context menu:

When you choose this command, the following actions are carried out:

• The "Hierarchical list box" option is checked for the object in the Property List.
• The variables of the columns are used to specify the hierarchy. They replace any variables already specified.
• The columns selected no longer appear in the list box (except for the title of the first one).

Example: given a list box whose first columns contain Country, Region, City and Population. When Country, Region and City are selected (see illustration above), if you choose Create hierarchy in the context menu, a three-level hierarchy is created in the first column, columns 2 and 3 are removed and the Population column becomes the second:

When the first column is selected and already specified as hierarchical, you can use the Cancel hierarchy command. When you choose this command, the following actions are carried out:

• The "Hierarchical list box" option is deselected for the object,
• The hierarchical levels 2 to X are removed and transformed into columns added to the list box.

When a form containing a hierarchical list box is opened for the first time, by default all the rows are expanded. 

A break row and a hierarchical "node" are automatically added in the list box when values are repeated in the arrays. For example, imagine a list box containing four arrays specifying cities, each city being characterized by its country, its region, its name and its number of inhabitants: 

If this list box is displayed in hierarchical form (the first three arrays being included in the hierarchy), you obtain:

The arrays are not sorted before the hierarchy is constructed. If, for example, an array contains the data AAABBAACC, the hierarchy obtained is:
    >    A
    >    B
    >    A
    >    C

To expand or collapse a hierarchical "node," you can just click on it. If you Alt+click (Windows) or Option+click (macOS) on the node, all its sub-elements will be expanded or collapsed as well. These operations can also be carried out by programming using the LISTBOX EXPAND and LISTBOX COLLAPSE commands.

When values of the date or time type are included in a hierarchical list box, they are displayed in a standard format:

• Dates are displayed in the short system format (for example, for May 30, 2009, "05/30/09" on an American system and "30/05/09" on a European system).
• Times are also displayed in the short system format ("12:15:30" or "12:15" depending on the system parameters).

In a list box in hierarchical mode, a standard sort (carried out by clicking on the header of a list box column) is always constructed as follows:

• In the first place, all the levels of the hierarchical column (first column) are automatically sorted by ascending order.
• The sort is then carried out by ascending or descending order (according to the user action) on the values of the column that was clicked.
• All the columns are synchronized.   
• During subsequent sorts carried out on non-hierarchical columns of the list box, only the last level of the first column is sorted. It is possible to modify the sorting of this column by clicking on its header.

Given for example the following list box, in which no specific sort is specified:

If you click on the "Population" header to sort the populations by ascending (or alternately descending) order, the data appear as follows:

As for all list boxes, you can disable the standard sort mechanism by deselecting the "Sortable" option for the list box and managing sorts using programming.

A hierarchical list box displays a variable number of rows on screen according to the expanded/collapsed state of the hierarchical nodes. This does not however mean that the number of rows of the arrays vary. Only the display is modified, not the data.

It is important to understand this principle because programmed management of hierarchical list boxes is always based on the data of the arrays, not on the displayed data. In particular, the break rows added automatically are not taken into account in the display options arrays (see Management of break rows below).

Let’s look at the following arrays for example:

If these arrays are represented hierarchically, the row "Quimper" will not be displayed on the second row, but on the fourth, because of the two break rows that are added:

Regardless of how the data are displayed in the list box (hierarchically or not), if you want to change the row containing "Quimper" to bold, you must use the statement Style{2} = bold. Only the position of the row in the arrays is taken into account. 

This principle is implemented for internal arrays that can be used to manage:

• colors
• background colors
• styles
• hidden rows
• selections

For example, if you want to select the row containing Rennes, you must pass:

Non-hierarchical representation:

Hierarchical representation:

Note: If one or more rows are hidden because their parents are collapsed, they are no longer selected. Only the rows that are visible (either directly or by scrolling) can be selected. In other words, rows cannot be both hidden and selected. 

As with selections, the LISTBOX GET CELL POSITION command will return the same values for a hierarchical list box and a non-hierarchical list box. This means that in both of the examples below, LISTBOX GET CELL POSITION will return the same position: (3;2).

Non-hierarchical representation:

Hierarchical representation:

When all the rows of a sub-hierarchy are hidden, the break line is automatically hidden. In the above example, if rows 1 to 3 are hidden, the "Brittany" break row will not appear.

If the user selects a break row, LISTBOX GET CELL POSITION returns the first occurrence of the row in the corresponding array. In the following case: 

... LISTBOX GET CELL POSITION returns (2;4). To select a break row by programming, you will need to use the LISTBOX SELECT BREAK command.

Break rows are not taken into account in the internal arrays used to manage the graphic appearance of list boxes (styles and colors). It is however possible to modify these characteristics for break rows via the graphic management commands for objects (Objects (Forms) theme). You simply need to execute the appropriate commands on the arrays that constitute the hierarchy. 

Given for example the following list box (the names of the associated arrays are specified in parentheses): 

Non-hierarchical representation:

Hierarchical representation:

In hierarchical mode, break levels are not taken into account by the style modification arrays named tStyle and tColors. To modify the color or style of break levels, you must execute the following statements:

Note: In this context, only the syntax using the array variable can function with the object property commands because the arrays do not have any associated object. 

Result:

You can optimize hierarchical list boxes display and management using the On Expand and On Collapse form events. 

A hierarchical list box is built from the contents of its arrays so it can only be displayed when all these arrays are loaded into memory. This makes it difficult to build large hierarchical list boxes based on arrays generated from data (through the SELECTION TO ARRAY command), not only because of the display speed but also the memory used.

Using the On Expand and On Collapse form events can overcome these constraints: for example, you can now display only part of the hierarchy and load/unload the arrays on the fly, based on user actions. 

In the context of these events, the LISTBOX GET CELL POSITION command returns the cell where the user clicked in order to expand or collapse a row.

In this case, you must fill and empty arrays through the code. The principles to be implemented are:

• When the list box is displayed, only the first array must be filled. However, you must create a second array with empty values so that the list box displays the expand/collapse buttons:
  
• When a user clicks on an expand button, you can process the On Expand event. The LISTBOX GET CELL POSITION command returns the cell concerned and lets you build the appropriate hierarchy: you fill the first array with the repeated values and the second with the values sent from the SELECTION TO ARRAY command and you insert as many rows as needed in the list box using the LISTBOX INSERT ROWS command.
  
• When a user clicks on a collapse button, you can process the On Collapse event. The LISTBOX GET CELL POSITION command returns the cell concerned: you remove as many rows as needed from the list box using the LISTBOX DELETE ROWS command.