Items

The SRP Tree Control is a collection of tree items. Each tree item has exactly one parent item and zero or more child items. Therefore, the internal data structure of the SRP Tree Control is a true hierarchy.

Internally, there is always an implicit parent item called the Root Item. This item is the parent of all items in the tree, and its existence allows for any number of root level items. An item is considered to be at the root level if it has no explicit parent -- although you and I know there is always the invisible Root Item parent.

Managing the SRP Tree Control's items would be difficult if we relied solely on indexes to access individual items. Fortunately, the SRP Tree Control uses unique keys to identify each item in a tree. No two tree items within the same SRP Tree Control may use the same key. A tree item key can be any alphanumeric string with some limitations. Tree item keys cannot be "" or "All" and cannot contain delimiters, periods, or commas. The Root Item's key is always "".

Managing the Tree

There are several ways to place new items into the tree. Use the ItemList property to initialize the tree. The ItemList property will always remove all existing items to make way for the new items. If you need to new items later, then use the AddItems or InsertItems methods. The AddItems method will add new child items to an item, while the InsertItems method inserts new items between existing items.

There are other a few methods for moving or copying your tree items. The MoveItems method moves items from one location in the tree to another location within the same tree. The SendItems and TransferItems methods copy items from one tree to another tree.

Finally, removing items can be done with the RemoveItems or RemoveAllItems methods.

Indexing Items

There are more than a dozen properties for modifying an item's attributes. These properties, which all begin with the "Item" prefix, are indexed. Indexed properties are just like normal properties with the addition that they can accept an index parameter. The index allows you to point to a specific item. In the case of the SRP Tree Control, the index is an item key. The syntax for an indexed property looks something like this:

Data = Get_Property(@Window:".OLE_TREE", "OLE.ItemData[Key]")

The square brackets indicate to OI that the property is indexed, and the value within those brackets is the index itself, that is, they key. As an example, let's say you want to programmatically expand an item whose key is "Employees":

Set_Property(@Window:".OLE_TREE", "OLE.ItemExpanded[Employee]", Yes$)

We simply place the key in the square brackets, telling OI to pass the new value to only that particular item. If your key is stored in a variable, then you have to use string concatenation to index the property:

Set_Property(@Window:".OLE_TREE", "OLE.ItemExpanded[":ItemKey:"]", Yes$)

There is one special keyword you can use to index all items at once: "All". This is why you can never use the word "All" as an item key. Use this keyword when you want to set all the items at the same time. For instance, we can collapse the entire tree by using the following code:

Set_Property(@Window:".OLE_TREE", "OLE.ItemExpanded[All]", No$)

If you use the "All" index during a Get_Property call, then the result will be a single value if all items are the same, or "" if at least one item differs in that attribute. So, if all items are expanded, than reading the property using the "All" keyword will return 1. If all but one are expanded, then the return value will be "".

Item Property Lists

If you need to get or set all the items using a dynamic array of values, you can use the "*" or "List" keyword as an index to any item property. For example, if you want to get the expanded setting for each item, you can do the following:

List = Get_Property(@Window:".OLE_TREE", "OLE.ItemExpanded[*]")

The List will be an @FM delimited array composed of Key:@VM:Value pairs. More importantly, you can use this new feature to batch set a bunch of item properties. If, for example, you wanted to update the text for many items quickly, call this instead of the ItemList property for maximum performance:

List     = "Item1":@VM:"Hello, One!"
List<-1> = "Item2":@VM:"Hello, Two!"
...
List<-1> = "Item99":@VM:"Hello, Ninety-nine!"
Set_Property(@Window:".OLE_TREE", "OLE.ItemData[*]", List)

The ItemList property is less suited for this use case because it always destroys all items and recreates new ones in their place, whereas the above example sets existing items in a single call. Much faster.

Tree Traversal

Traversing the tree is easy. Use the RootChildren property when you need to start from the very beginning of the tree. If you already have an item key, then use the ItemChildren property to get its children. To traverse upward, use the ItemParent property to get the item's parent.

Selecting Items

The user, by default, can select only one item a time, but you can use the SelectBehavior to allow for multiple selection or no selection at all. The SelectedItems property can be used to get the current selection or to programmatically change it. Whenever the user changes the selection, the OnSelChange event is fired. Note, however, that the event will not fire when setting the SelectedItems property.