# GraffitiTree
Class Inherits GraffitiWebUIControl
## About
An easy to use hierarchical display component with support for custom styling and direct HTML embedding.
## Compatibility
### Framework API Version
| 1.0 | 2.0 |
| :---: | :---: |
| True | True |
### Web
| 32-Bit | 64-Bit |
| :---: | :---: |
| True | True |
## Event Definitions
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| Close | (None) | (None) | |
| ContextClick | mouseX as Integer <br> mouseY as Integer | (None) | Fires when the user right-clicks an item in the display. mouseX and mouseY are relative to the page, not the control. |
| ItemChecked | theItem as GraffitiTreeItem | (None) | |
| ItemClicked | theItem as GraffitiTreeItem | (None) | Fires when the user has clicked an item. |
| ItemCollapsed | theItem as GraffitiTreeItem | (None) | Fires when the user has collapsed an expandable item. |
| ItemContextClicked | item as GraffitiTreeItem <br> x as Integer <br> y as Integer | (None) | |
| ItemDoubleClicked | theItem as GraffitiTreeItem | (None) | Fires when the user has double-clicked an item. |
| ItemEdited | theItem as GraffitiTreeItem | (None) | Fires when the user has finished editing an item. |
| ItemExpanded | theItem as GraffitiTreeItem | (None) | Fires when the user has expanded an item. |
| ItemIconClicked | theItem as GraffitiTreeItem | (None) | Fires when the user has clicked the icon of an item. |
| ItemKeyPressed | theItem as GraffitiTreeItem <br> theKey as String | (None) | Raised when a key pressed on a selected item. |
| ItemSelected | theItem as GraffitiTreeItem | (None) | Fires when the user selects an item either with the mouse or keyboard. |
| ItemUnchecked | theItem as GraffitiTreeItem | (None) | Raised when an item is unchecked. |
| Open | (None) | (None) | |
| Shown | (None) | (None) | |
| ValueChange | (None) | (None) | Raised when the selection has changed. |
## Methods
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| AddItem | theItem as GraffitiTreeItem <br> theParent as GraffitiTreeItem = Nil <br> AddToParentItem as Boolean = True | (None) | Adds an item to the tree. If theParent is Nil, then it is added as a top-level node. AddToParent = True will add it to the Children property of the parent item (mostly for internal use). |
| CheckAll | (None) | (None) | Checks all top-level items. |
| CheckItem | theItem as GraffitiTreeItem <br> theValue as Boolean = True | (None) | Sets the item's checkbox value to theValue. |
| CollapseAll | (None) | (None) | Collapse all currently expanded items. |
| CollapseItem | theItem as GraffitiTreeItem | (None) | Collapses the supplied item. |
| CountItems | (None) | Integer | Returns a count of all top-level items. |
| DeselectAll | (None) | (None) | Deselect all items. |
| DisableItem | theItem as GraffitiTreeItem | (None) | Disables an item, making it uncheckable. |
| EditItem | theItem as GraffitiTreeItem | (None) | Makes an item editable. |
| EditItemEnd | theItem as GraffitiTreeItem <br> ApplyChanges as Boolean | (None) | |
| EnableItem | theItem as GraffitiTreeItem | (None) | Enables an item, making it checkable. |
| ExpandAll | (None) | (None) | Expands all currently expandable items. |
| ExpandItem | theItem as GraffitiTreeItem | (None) | Expands the supplied item. |
| FindItem | itemText as String | GraffitiTreeItem | Finds the first item whose Caption matches itemText. |
| GetDepth | theItem as GraffitiTreeItem | Integer | Returns the level depth of the current item. Top-level items will be 1, their children will be 2, etc. |
| GetIndexOf | theItem as GraffitiTreeItem | Integer | Gets the index of the supplied item within its parent's Children array, or within the Items array if top-level. |
| GetIndexPath | theItem as GraffitiTreeItem <br> Separator as String | String | Returns an index path to the current item. As an example, calling GetIndexPath( myItem, “/” ) will return something like “3/7/1”. |
| GetPath | theItem as GraffitiTreeItem <br> Separator as String | String | Returns the path to the current item using item captions. As an example, calling GetPath( myItem, “/” ) will return something like “Parent1/Parent2/Parent3/MyItem”. |
| HasChildren | theItem as GraffitiTreeItem | Boolean | Returns true if the supplied item has children. |
| HideCheckbox | theItem as GraffitiTreeItem | (None) | Hides the checkbox for the specified item. |
| InsertItem | theItem as GraffitiTreeItem <br> insertBefore as GraffitiTreeItem | (None) | Inserts theItem before insertBefore. |
| IsChildOf | theItem as GraffitiTreeItem <br> theParent as GraffitiTreeItem | Boolean | Returns true is theItem is a direct child of theParent. |
| IsFirstChild | theItem as GraffitiTreeItem | Boolean | Returns True if theItem is the first child in its parent. |
| IsLastChild | theItem as GraffitiTreeItem | Boolean | Returns True if theItem is the last child of its parent. |
| IsSiblingOf | theItem as GraffitiTreeItem <br> theSibling as GraffitiTreeItem | Boolean | Returns True if the two supplied items are siblings. |
| IsTopLevel | theItem as GraffitiTreeItem | Boolean | Returns True if theItem is a top-level item. |
| MoveTo | theItem as GraffitiTreeItem <br> newParent as GraffitiTreeItem <br> atIndex as Integer = -1 | (None) | Moves the specified item to a new parent. |
| RemoveAll | fromItem as GraffitiTreeItem = Nil | (None) | Removes all items from the Tree. |
| RemoveItem | theItem as GraffitiTreeItem <br> includeChildren as Boolean = True | (None) | Removes theItem from the tree. If includeChildren is False, then children of theItem are added to theItem's parent. |
| ScrollTo | theItem as GraffitiTreeItem | (None) | Scrolls to theItem. If it is hidden under collapsed parents, those parents are expanded automatically. |
| SelectItem | theItem as GraffitiTreeItem | (None) | Selects the specified item. |
| ShowCheckbox | theItem as GraffitiTreeItem | (None) | Shows the checkbox for the specified item. |
| UncheckAll | (None) | (None) | Unchecks all top-level items. |
| UpdateCaption | theItem as GraffitiTreeItem <br> newCaption as String | (None) | Updates the specified item with newCaption. |
| UpdateIcon | theItem as GraffitiTreeItem <br> newIcon as String | (None) | Updates the specified item with newIcon. |
| UpdateItemStyle | theItem as GraffitiTreeItem | (None) | Updates the tree to show theItem.Style. |
## Properties
| Name | Type | Default Value | Description |
| --- | :---: | :---: | --- |
| AllowEdit | Boolean | Nil | If True, users will be able to edit the contents of individual rows. NOTE: This property should only be set in the IDE's Inspector. |
| IconCheckbox | String | Nil | A FontAwesome icon string to use for an empty checkbox. |
| IconCheckboxChecked | String | Nil | A FontAwesome icon string to use for checked checkboxes. |
| IconCheckboxUnknown | String | Nil | A FontAwesome icon string to use for checkboxes with an unknown value ( IE : if some children, but not all, are selected). |
| IconExpanderClosed | String | Nil | A FontAwesome icon string to use as an expander for items with children. |
| IconExpanderOpen | String | Nil | A FontAwesome icon string to use as collapser for items with children. |
| IconExpanderStyle | GraffitiStyle | Nil | GraffitiStyle applied to item expanders. |
| IconStyle | GraffitiStyle | Nil | WebStyle to apply to icons in the tree. |
| Items() | GraffitiTreeItem | Nil | Items in the tree, editing this directly is not recommended. |
| ItemSelStyle | GraffitiStyle | Nil | WebStyle to apply to selected items. |
| ItemStyle | GraffitiStyle | Nil | WebStyle to apply to all items. |
| LockUpdate | Boolean | Nil | When true, rows added using AddItem will not update style information until LockUpdate is set to False. This should speed up addition of large amounts of rows. |
| RightToLeft | Boolean | Nil | When true, the Tree will display in RTL fashion. |
| SelectedItem | GraffitiTreeItem | Nil | The currently selected item. |
## Examples
### Creating an Item with a FontAwesome Icon
GraffitiWebTree provides a constructor for creating items that have a FontAwesome icon to the left of the node's text.
```
dim firstItemFirstChild as new GraffitiWebTreeItem( "test child", "fas fa-times" )
firstItemFirstChild.Checkbox = True
me.AddItem( firstItemFirstChild, firstItem )
```
### Iterate Items
As GraffitiWebTree items are maintained in a relational manner (using Parents and Children), iterating items can be a tough concept to grasp. The easiest path is to create a method to do your multi-level iteration and perform a specific function. For instance, the following code will loop through all items in the tree and give you an opportunity to do something with the individual item’s CheckValue property:
```
Private Sub StoreCheckValues(ofTree as GraffitiWebTree, inNode as GraffitiWebTreeItem = Nil)
dim arrCheck() as GraffitiWebTreeItem
if not IsNull( inNode ) Then
arrCheck = inNode.Children
else
arrCheck = ofTree.Items
end if
dim intCycle as Integer
dim intMax as Integer = arrCheck.Ubound
'// Note that you will want to perform the same operation on the parent
' before the loop if you're providing inNode and want its value recorded.
dim currentItem as GraffitiWebTreeItem
for intCycle = 0 to intMax
currentItem = arrCheck(intCycle)
if currentItem.Checkbox then '// Has a checkbox
'// Store the value of CheckValue
end if
'// The following line will iterate over the children of currentItem.
' If you only want to do top-level children then you can comment this
' or add a method parameter and check it here.
if currentItem.Children.Ubound >= 0 then StoreCheckValues( ofTree, currentItem )
next
End Sub
```
Then you would simply call the method and pass in your tree to iterate through all items:
```
StoreCheckValues(myTreeInstance)
```
Or, if you only want to iterate over a specific branch of the tree:
```
StoreCheckValues(myTreeInstance, myBranchTreeItem)
```
