Inserts new items into the tree.
Syntax
rv = Send_Message(Ctrl, "OLE.InsertItems", DestItem, NewItems, Action)
Parameters
| Parameter | Description |
|---|---|
| DestItem | The item before or after which the new items will be inserted |
| NewItems | The list of items to be added |
| Action | Determines whether the items are added before or after the destination item |
Remarks
The InsertItems property inserts new items into the existing tree. Specifically, it allows you to insert new items before or after an existing item. The DestItem parameter is the key of the item before or after which the new items should be inserted. This parameter cannot be set to "". The NewItems parameter is formatted as an @FM delimited array of tree items discussed in detail below. The Action parameter determines how the new items are inserted. Set it to "Before" to insert the new items before the destination item or "After" to insert the new items after the destination item.
Each field in the NewItems array represents a single new item, and the multivalue structure for each field is as follows:
| Pos | Name | Type | Description |
|---|---|---|---|
| <1, 1> | Level | Integer | The item's level in the tree |
| <1, 2> | Key | Text | The item's unique key |
| <1, 3> | Data | Text | The item's data |
| <1, 4> | Data Type | ||
| <1, 4, 1> | Type | Option | The item's data type, used to make sorting most accurate and efficient |
| <1, 4, 2> | Format | Formatted String | The item's data format, used to present the data |
| <1, 5> | Class | Text | The item's class, an application specific string that can used for classification purposes |
| <1, 6> | Image | Formatted String | The item's image, either a file or a key pointing to a global image |
| <1, 7> | Colors | ||
| <1, 7, 1> | Text Color | Color | The color of the item's text |
| <1, 7, 2> | Background | Color Fill | The item's background |
| <1, 8> | Font | Font | The font used to render the item's data |
| <1, 9> | Alignment | ||
| <1, 9, 1> | Horizontal | Option | The horizontal alignment of the item's data |
| <1, 9, 2> | Vertical | Option | The vertical alignment of the item's data |
| <1, 10> | Sort | Option | The item's sort setting |
| <1, 11> | Check Box | Option | The item's check box setting |
| <1, 12> | Expandable | Boolean | Whether or not the item can be expanded or collapsed by the user |
| <1, 13> | Height | Integer | The item's height |
| <1, 14> | Hyperlink | Boolean | Whether or not the item displays hyperlink feedback to the user |
| <1, 15> | Selectable | Boolean | Whether or not the item can be selected by the user |
The first two values, Level and Key, must be included for every item. All other values are optional.
Level
The first value of every item is its level within the tree. The level will be used to determine where the item fits within the hierarchy. If an item's level is greater than the item preceding it, then it becomes that item's child. Since the SRP Tree Control is a true hierarchy, the levels will be interpreted in terms of relativity, not actual value. For example, if you set item 1 to level 1 and item 2 to level 8, item 2 will still be a direct child of item 1. It's important to note that the level is relative to the destination item's level. That is, a new item at level 1 will be inserted at the same level as the destination item, not as a child of the Root Item.
Key
Every item has a unique key so it can be accessed directly later. This reduces the amount of tree traversal necessary to locate a particular item. An item's key can be any alphanumeric string, but it cannot be "" or "All" and it cannot contain delimiters, periods, or commas. If an item with the key already exists, then this item will not be added to the control.
Item Settings
The remaining values in each field initialize the new item. They are all optional, so set only those that are necessary. Usually, you will only set the Data and Class values while letting the default property settings take care of the rest. See Default Properties for more information.
See the Item property for more details.
Example
// Assume a tree with boys and girls organized into teams // Insert a whole new team, Purple Team, before the Red Team NewItems = "" NewItems<-1> = 1:@VM:"PurpleTeam":@VM:"Purple Team":@VM:@VM:"PurpleTeam" NewItems<-1> = 2:@VM:"Samantha":@VM:"Samantha":@VM:@VM:"Girl" NewItems<-1> = 2:@VM:"Brianna":@VM:"Brianna":@VM:@VM:"Girl" NewItems<-1> = 2:@VM:"Mia":@VM:"Mia":@VM:@VM:"Girl" NewItems<-1> = 2:@VM:"Alexis":@VM:"Alexis":@VM:@VM:"Girl" NewItems<-1> = 2:@VM:"Brayden":@VM:"Brayden":@VM:@VM:"Boy" NewItems<-1> = 2:@VM:"Zachary":@VM:"Zachary":@VM:@VM:"Boy" NewItems<-1> = 2:@VM:"Benjamin":@VM:"Benjamin":@VM:@VM:"Boy" NewItems<-1> = 2:@VM:"William":@VM:"William":@VM:@VM:"Boy" Send_Message(@Window:".OLE_TREE", "OLE.InsertItems", "RedTeam", NewItems, "Before")
