Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
web:tree [2019/03/17 13:47]
agcyphers [Examples]
web:tree [2019/10/23 05:53] (current)
Line 24: Line 24:
 ==== Methods ==== ==== Methods ====
 ^ Definition      ^ Description       ^ ^ Definition      ^ Description       ^
-| AddItem( theItem as GraffitiWebTreeItem, theParent as GraffitiWebTreeItem = Nil, AddToParentItem as [[http://developer.xojo.com/boolean|Boolean]] = True ) | 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). | +| AddItem( theItem as GraffitiWebTreeItem, theParent as GraffitiWebTreeItem = Nil, AddToParentItem as Boolean = True ) | 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). | 
-| CheckItem( theItem as GraffitiWebTreeItem, theValue as [[http://developer.xojo.com/boolean|Boolean]] = True ) | Sets the item's checkbox value to theValue. |+| CheckItem( theItem as GraffitiWebTreeItem, theValue as Boolean = True ) | Sets the item's checkbox value to theValue. |
 | CollapseAll() | Collapse all currently expanded items. | | CollapseAll() | Collapse all currently expanded items. |
 | CollapseItem( theItem as GraffitiWebTreeItem ) | Collapses the supplied item. | | CollapseItem( theItem as GraffitiWebTreeItem ) | Collapses the supplied item. |
Line 35: Line 35:
 | ExpandAll() | Expands all currently expandable items. | | ExpandAll() | Expands all currently expandable items. |
 | ExpandItem( theItem as GraffitiWebTreeItem ) | Expands the supplied item. | | ExpandItem( theItem as GraffitiWebTreeItem ) | Expands the supplied item. |
-| FindItem( itemText as [[http://developer.xojo.com/string|String]] ) as GraffitiWebTreeItem | Finds the first item whose Caption matches itemText. | +| FindItem( itemText as String ) as GraffitiWebTreeItem | Finds the first item whose Caption matches itemText. | 
-| GetDepth( theItem as GraffitiWebTreeItem ) as [[http://developer.xojo.com/integer|Integer]] | Returns the level depth of the current item.  Top-level items will be 1, their children will be 2, etc. | +| GetDepth( theItem as GraffitiWebTreeItem ) as Integer | Returns the level depth of the current item.  Top-level items will be 1, their children will be 2, etc. | 
-| GetIndexOf( theItem as GraffitiWebTreeItem ) as [[http://developer.xojo.com/integer|Integer]] | Gets the index of the supplied item within its parent's Children array, or within the Items array if top-level. | +| GetIndexOf( theItem as GraffitiWebTreeItem ) as 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 GraffitiWebTreeItem, Separator as [[http://developer.xojo.com/string|String]] = "/" ) as [[http://developer.xojo.com/string|String]] | Returns an index path to the current item.  As an example, calling GetIndexPath( myItem, "/" ) will return something like "3/7/1". | +| GetIndexPath( theItem as GraffitiWebTreeItem, Separator as String = "/" ) as 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 GraffitiWebTreeItem, Separator as [[http://developer.xojo.com/string|String]] = "/" ) as [[http://developer.xojo.com/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". | +| GetPath( theItem as GraffitiWebTreeItem, Separator as String = "/" ) as 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 GraffitiWebTreeItem ) as [[http://developer.xojo.com/boolean|Boolean]] | Returns true if the supplied item has children. |+| HasChildren( theItem as GraffitiWebTreeItem ) as Boolean | Returns true if the supplied item has children. |
 | InsertItem( theItem as GraffitiWebTreeItem, insertBefore as GraffitiWebTreeItem ) | Inserts theItem before insertBefore. | | InsertItem( theItem as GraffitiWebTreeItem, insertBefore as GraffitiWebTreeItem ) | Inserts theItem before insertBefore. |
-| IsChildOf( theItem as GraffitiWebTreeItem, theParent as GraffitiWebTreeItem ) as [[http://developer.xojo.com/boolean|Boolean]] | Returns true is theItem is a direct child of theParent. | +| IsChildOf( theItem as GraffitiWebTreeItem, theParent as GraffitiWebTreeItem ) as Boolean | Returns true is theItem is a direct child of theParent. | 
-| IsFirstChild( theItem as GraffitiWebTreeItem ) as [[http://developer.xojo.com/boolean|Boolean]] | Returns True if theItem is the first child in its parent. | +| IsFirstChild( theItem as GraffitiWebTreeItem ) as Boolean | Returns True if theItem is the first child in its parent. | 
-| IsLastChild( theItem as GraffitiWebTreeItem ) as [[http://developer.xojo.com/boolean|Boolean]] | Returns True if theItem is the last child of its parent. |+| IsLastChild( theItem as GraffitiWebTreeItem ) as Boolean | Returns True if theItem is the last child of its parent. |
 | IsSiblingOf( theItem as GraffitiWebTreeItem, theSibling as GraffitiWebTreeItem ) | Returns True if the two supplied items are siblings. | | IsSiblingOf( theItem as GraffitiWebTreeItem, theSibling as GraffitiWebTreeItem ) | Returns True if the two supplied items are siblings. |
-| IsTopLevel( theItem as GraffitiWebTreeItem ) as [[http://developer.xojo.com/boolean|Boolean]] | Returns True if theItem is a top-level item. |+| IsTopLevel( theItem as GraffitiWebTreeItem ) as Boolean | Returns True if theItem is a top-level item. |
 | RemoveAll() | Removes all items from the Tree. | | RemoveAll() | Removes all items from the Tree. |
-| RemoveItem( theItem as GraffitiWebTreeItem, includeChildren as [[http://developer.xojo.com/boolean|Boolean]] = True ) | Removes theItem from the tree.  If includeChildren is False, then children of theItem are added to theItem's parent. |+| RemoveItem( theItem as GraffitiWebTreeItem, includeChildren as Boolean = True ) | Removes theItem from the tree.  If includeChildren is False, then children of theItem are added to theItem's parent. |
 | ScrollTo( theItem as GraffitiWebTreeItem ) | Scrolls to theItem.  If it is hidden under collapsed parents, those parents are expanded automatically. | | ScrollTo( theItem as GraffitiWebTreeItem ) | Scrolls to theItem.  If it is hidden under collapsed parents, those parents are expanded automatically. |
 | SelectItem( theItem as GraffitiWebTreeItem ) | Selects the specified item. | | SelectItem( theItem as GraffitiWebTreeItem ) | Selects the specified item. |
-| UpdateCaption( theItem as GraffitiWebTreeItem, newCaption as [[http://developer.xojo.com/string|String]] ) | Updates the specified item with newCaption. | +| UpdateCaption( theItem as GraffitiWebTreeItem, newCaption as String ) | Updates the specified item with newCaption. | 
-| UpdateIcon( theItem as GraffitiWebTreeItem, newIcon as [[http://developer.xojo.com/string|String]] ) | Updates the specified item with newIcon. |+| UpdateIcon( theItem as GraffitiWebTreeItem, newIcon as String ) | Updates the specified item with newIcon. |
 | UpdateItemStyle( theItem as GraffitiWebTreeItem ) | Updates the tree to show theItem.Style. | | UpdateItemStyle( theItem as GraffitiWebTreeItem ) | Updates the tree to show theItem.Style. |
  
 ==== Properties ==== ==== Properties ====
 ^ Name      ^ Type       ^ Default Value       ^ Description       ^ ^ Name      ^ Type       ^ Default Value       ^ Description       ^
-| AllowEdit | [[http://developer.xojo.com/boolean|Boolean]] | False | 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. | +| AllowEdit | Boolean | False | 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 | [[http://developer.xojo.com/string|String]] | "" | A FontAwesome icon string to use for an empty checkbox. | +| IconCheckbox | String | "" | A FontAwesome icon string to use for an empty checkbox. | 
-| IconCheckboxChecked | [[http://developer.xojo.com/string|String]] | "fa-checked-square-o" | A FontAwesome icon string to use for checked checkboxes. | +| IconCheckboxChecked | String | "fa-checked-square-o" | A FontAwesome icon string to use for checked checkboxes. | 
-| IconCheckboxUnknown | [[http://developer.xojo.com/string|String]] | "fa-square-o" | A FontAwesome icon string to use for checkboxes with an unknown value (IE: if some children, but not all, are selected). | +| IconCheckboxUnknown | String | "fa-square-o" | A FontAwesome icon string to use for checkboxes with an unknown value (IE: if some children, but not all, are selected). | 
-| IconExpanderClosed | [[http://developer.xojo.com/string|String]] | "fa-caret-down" | A FontAwesome icon string to use as an expander for items with children. | +| IconExpanderClosed | String | "fa-caret-down" | A FontAwesome icon string to use as an expander for items with children. | 
-| IconExpanderOpen | [[http://developer.xojo.com/string|String]] | "fa-caret-right" | A FontAwesome icon string to use as collapser for items with children. |+| IconExpanderOpen | String | "fa-caret-right" | A FontAwesome icon string to use as collapser for items with children. |
 | IconStyle | WebStyle | Nil | WebStyle to apply to icons in the tree. | | IconStyle | WebStyle | Nil | WebStyle to apply to icons in the tree. |
 | Items() | GraffitiWebTreeItem | Nil | Items in the tree, editing this directly is not recommended. | | Items() | GraffitiWebTreeItem | Nil | Items in the tree, editing this directly is not recommended. |
 | ItemSelStyle | WebStyle | Nil | WebStyle to apply to selected items. | | ItemSelStyle | WebStyle | Nil | WebStyle to apply to selected items. |
 | ItemStyle | WebStyle | Nil | WebStyle to apply to all items. | | ItemStyle | WebStyle | Nil | WebStyle to apply to all items. |
-| LockUpdate | [[http://developer.xojo.com/boolean|Boolean]] | False | 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. | +| LockUpdate | Boolean | False | 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 | [[http://developer.xojo.com/boolean|Boolean]] | False | When true, the Tree will display in RTL fashion. |+| RightToLeft | Boolean | False | When true, the Tree will display in RTL fashion. |
 | SelectedItem | GraffitiWebTreeItem | Nil | The currently selected item. | | SelectedItem | GraffitiWebTreeItem | Nil | The currently selected item. |
  
Line 78: Line 78:
 firstItemFirstChild.Checkbox = True firstItemFirstChild.Checkbox = True
 me.AddItem( firstItemFirstChild, firstItem )</code> me.AddItem( firstItemFirstChild, firstItem )</code>
 +
 +=== 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:
 +<code xojo>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</code>
 +
 +Then you would simply call the method and pass in your tree to iterate through all items:
 +<code xojo>StoreCheckValues(myTreeInstance)</code>
 +
 +Or, if you only want to iterate over a specific branch of the tree:
 +<code xojo>StoreCheckValues(myTreeInstance, myBranchTreeItem)</code>