version 11 (Modified)
APPEND TO LIST (list; itemText; itemRef{; sublist; expanded})
Parameter | Type | Description | |
list | ListRef | List reference number | |
itemText | String | Text of 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 optional sublist will be expanded or | |
collapsed |
Description
The APPEND TO LIST command appends a new item to the hierarchical list whose list reference number you pass in list.
You pass the text of the item in itemText. You can pass a string or text expression of up to 2 billion characters.
You pass the unique reference number of the item(of the Longint type) in itemRef. Although we qualify this item reference number as unique, you can actually pass the value you want. Refer to the Managing Hierarchical Lists section for more information about the itemRef parameter.
If you also want an item to have child items, pass a valid list reference to the child hierarchical list in sublist. In this case, you must also pass the expanded parameter. Pass True or False in this parameter so that the sublist is displayed expanded or collapsed respectively.
The list reference you pass in sublist must refer to an existing list. The existing list may be a one-level list or a list with sublists. If you do not want to attach a child list to the new item, omit the parameter or pass 0. Even though they are both optional, the sublist and expanded parameters must be passed jointly.
Tips
To insert a new item in a list, use INSERT IN LIST. To change the text of an existing item or modify its child list as well as its expanded state, use SET LIST ITEM.
To change the appearance of the new appended item use SET LIST ITEM PROPERTIES.
Example
Here is a partial view of a database structure:
The [Departments] and [Employees] tables contain the following records:
You want to display a hierarchical list, named hlList, that shows the Departments, and for each Department, a child list that shows the Employees working in that Department. The object method of hlList is:
` hlList Hierarchical List Object Method Case of : (Form event=On Load) C_LONGINT(hlList;$hSubList;$vlDepartment;$vlEmployee) ` Create a new empty hierarchical list hlList:=New list ` Select all the records from the [Departments] table ALL RECORDS([Departments]) ` For each Department For ($vlDepartment;1;Records in selection([Departments])) ` Select the Employees from this Department RELATE MANY([Departments]Name) ` How many are they? $vlNbEmployees:=Records in selection([Employees]) ` Is there at least one Employee in this Department? If ($vlNbEmployees>0) ` Create a child list for the Department item $hSubList:=New list ` For each Employee For ($vlEmployee;1;Records in selection([Employees])) ` Add the Employee item to the sublist ` Note that the record number of the [Employees] record ` is passed as item reference number APPEND TO LIST($hSubList;[Employees]Last Name+", "+ [Employees]First Name;Record number([Employees])) ` Go the next [Employees] record NEXT RECORD([Employees]) End for Else ` No Employees, no child list for the Department item $hSubList:=0 End if ` Add the Department item to the main list ` Note that the record number of the [Departments] record ` is passed as item reference number. The bit #31 ` of the item reference number is forced to one so we'll be able ` to distinguish Department and Employee items. See note further ` below on why we can use this bit as supplementary information about ` the item. APPEND TO LIST(hlList;[Departments]Name; 0x80000000 | Record number([Departments]);$hSublist;$hSubList # 0) ` Set the Department item in Bold to emphasize the hierarchy of the list SET LIST ITEM PROPERTIES(hlList;0;False;Bold;0) ` Go to the next Department NEXT RECORD([Departments]) End for ` Sort the whole list in ascending order SORT LIST(hlList;>) ` Display the list using the Windows style ` and force the minimal line height to 14 Pts SET LIST PROPERTIES(hlList;ala Windows;Windows node;14) : (Form event=On Unload) ` The list is no longer needed; do not forget to get rid of it! CLEAR LIST(hlList;*) : (Form event=On Double Clicked) ` A double-click occurred ` Get the position of the selected item $vlItemPos:=Selected list items(hlList) ` Just in case, check the position If ($vlItemPos # 0) ` Get the list item information GET LIST ITEM(hlList;$vlItemPos;$vlItemRef;$vsItemText;$vlItemSubList;$vbItemSubExpanded) ` Is the item a Department item? If ($vlItemRef ?? 31) ` If so, it is a double-click on a Department Item ALERT("You double-clicked on the Department item "+Char(34)+$vsItemText+Char(34)+".") Else ` If not, it is a double-click on an Employee item ` Using the parent item reference number find the [Departments] record GOTO RECORD([Departments];List item parent(hlList;$vlItemRef)?-31) ` Tell where the Employee is working and to whom he or she is reporting ALERT("You double-clicked on the Employee item "+Char(34)+$vsItemText+Char(34)+ " who is working in the Department "+Char(34)+[Departments]Name+Char(34)+ " whose manager is "+Char(34)+[Departments]Manager+Char(34)+".") End if End if End case ` Note: 4D can store up to 1 billion records per table ` The record number fits on 24 bits. In our example, we use bit #31 of the unused high byte for ` distinguishing Employees and Departments items.
In this example, there is only one reason to distinguish [Departments] items and [Employees] items:
1. We store record numbers in the item reference numbers; therefore, we will probably end up with [Departments] items whose item reference numbers are the same as [Employees] items.
2. We use the List parent item command to retrieve the parent of the selected item. If we click on an [Employees] item whose associated record number is #10, and if there is also a [Departments] item #10, the [Departments] item will be found first by List parent item when it browses the lists to locate the item with the item reference number we pass. The command will return the parent of the [Departments] item and not the parent of the [Employees] item.
Therefore, we made the item reference numbers unique, not because we wanted unique numbers, but because we needed to distinguish [Departments] and [Employees] records.
When the form is executed, the list will look like this:
Note: This example is useful for user interface purposes if you deal with a reasonably small number of records. Remember that lists are held in memorydo not build user interfaces with hierarchical lists containing millions of items.
See Also
INSERT IN LIST, SET LIST ITEM, SET LIST ITEM PROPERTIES.