GuiTreeViewCtrl
Hierarchical list of text items with optional icons.
TreeView
int
int
bool
int
bool
If true, the entire tree item hierarchy is deleted when the control goes to sleep.
bool
bool
If true, multiple items can be selected concurrently.
bool
bool
bool
If true, the root item is shown in the tree.
bool
bool
Inspector Trees
bool
If true, item text labels for objects will include object IDs.
bool
If true, item text labels for objects will include class names.
bool
If true, item text labels for objects will include object names.
bool
If true, item text labels for obje ts will include internal names.
bool
If true, class names will be used as object names for unnamed objects.
bool
bool
If true clicking on a selected item ( that is an object and not the root ) will allow you to rename it.
bool
If true then object renaming operates on the internalName rather than the object name.
Callbacks
bool
onDeleteObject(SimObject object)
bool
isValidDragTarget(int id, string value)
void
void
onAddGroupSelected(SimGroup group)
void
onAddSelection(int itemOrObjectId, bool isLastSelection)
void
onSelect(int itemOrObjectId)
void
onInspect(int itemOrObjectId)
void
onRemoveSelection(int itemOrObjectId)
void
onUnselect(int itemOrObjectId)
void
void
void
onKeyDown(int modifier, int keyCode)
void
onMouseUp(int hitItemId, int mouseClickCount)
void
void
onRightMouseDown(int itemId, Point2I mousePos, SimObject object)
void
onRightMouseUp(int itemId, Point2I mousePos, SimObject object)
void
void
void
onReparent(int itemOrObjectId, int oldParentItemOrObjectId, int newParentItemOrObjectId)
void
void
void
bool
canRenameObject(SimObject object)
bool
handleRenameObject(string newName, SimObject object)
void
Public Functions
void
addChildSelectionByValue(int parentId, string value)
Add a child selection by it's value.
void
addSelection(int id, bool isLastSelection)
Add an item/object to the current selection.
bool
buildIconTable(string icons)
Builds an icon table.
void
buildVisibleTree(bool forceFullUpdate)
Build the visible tree.
void
Cancel renaming an item (For internal use).
void
clear()
Empty the tree.
void
Clear the current item filtering pattern.
void
Set the pattern by which to filter items in the tree. Only items in the tree whose text matches this pattern are displayed.
void
Unselect all currently selected items.
void
Delete all items/objects in the current selection.
bool
editItem(int itemId, string newText, string newValue)
Edits the text and value for a given tree item.
bool
expandItem(int itemID, bool expand)
Expand/contract item, item's sub-tree.
int
findChildItemByName(int parentId, string childName)
Get the child item of the given parent item whose text matches childName.
int
findItemByName(string text)
Get the ID of the item whose text matches the given text.
int
findItemByObjectId(int objectId)
Find an item by its object id and returns the Tree Item ID for it.
int
findItemByValue(string value)
Get the ID of the item whose value matches value.
int
getChild(int itemId)
Get the child of the parent with the given id.
string
Get the current filter expression. Only tree items whose text matches this expression are displayed. By default, the expression is empty and all items are shown.
int
Get id for root item.
int
getItemAtPosition(Point2I position)
Get the tree item at the passed in position.
int
Get the total number of items in the tree or item count.
int
getItemObject(int itemId)
Gets the object for a particular item.
string
getItemText(int itemId)
Gets the text for a given item.
string
getItemValue(int itemId)
Gets the value for a given item.
int
getNextSibling(int itemId)
Get the next sibling of the given item id in the tree.
int
getParentItem(int itemId)
Get the parent of a given id in the tree.
int
getPrevSibling(int itemId)
Get the previous sibling of the given item id in the tree.
int
getSelectedItem(int index)
Return the selected item at the given index.
string
Returns a space separated list if ids of all selected items.
int
Get the selected number of items.
int
getSelectedObject(int index)
Return the currently selected SimObject at the given index in inspector mode or -1.
string
Returns a space separated list of all selected object ids.
int
getTabLevel(int itemId)
Get the tree item at the passed in position.
string
getTextToRoot(int itemId, string delimiter)
Gets the text from the current node to the root, concatenating at each branch upward, with a specified delimiter optionally.
void
hideSelection(bool state)
Call SimObject::setHidden( state ) on all objects in the current selection.
int
insertItem(int parentId, string text, string value, string icon, int normalImage, int expandedImage)
Add a new item to the tree.
int
insertObject(int parentId, SimObject obj, bool OKToEdit)
Inserts object as a child to the given parent.
bool
isItemSelected(int id)
Check whether the given item is currently selected in the tree.
bool
isParentItem(int itemId)
Returns true if the given item contains child items.
void
lockSelection(bool lock)
Set whether the current selection can be changed by the user or not.
bool
markItem(int itemID, bool mark)
Mark/unmark item.
void
moveItemDown(int itemId)
Move the specified item down in the tree.
void
moveItemUp(int itemId)
Move the specified item up in the tree.
void
Validate the new name for an object (For internal use).
void
open(string objName, bool okToEdit)
Set the root of the tree view to the specified object, or to the root set.
void
removeAllChildren(int itemId)
Remove all children of an item from the tree with the given id.
void
removeChildSelectionByValue(int parentId, string value)
Deselect a child item or remove it from the selection based on its parent and its value.
bool
removeItem(int itemId, bool deleteObjects)
Remove an item from the tree with the given id.
void
removeSelection(int itemId)
Deselect an item or remove it from the selection.
void
reparentItem(int itemId, int parentId)
Check whether the given item is currently selected in the tree.
bool
scrollVisible(int itemID)
Make the given item visible.
int
scrollVisibleByObjectId(int objectId)
Show item by object id.
bool
selectItem(int itemID, bool select)
Select or deselect and item.
void
setDebug(bool value)
Enable/disable debug output.
void
setFilterChildren(bool doFilterChildren)
Set the pattern by which to filter items in the tree. Only items in the tree whose text matches this pattern are displayed.
void
setFilterText(string pattern)
Set the pattern by which to filter items in the tree. Only items in the tree whose text matches this pattern are displayed.
void
setItemFilterException(uint item, bool isExempt)
Set the pattern by which to filter items in the tree. Only items in the tree whose text matches this pattern are displayed.
void
setItemHidden(uint item, bool hidden)
Set the pattern by which to filter items in the tree. Only items in the tree whose text matches this pattern are displayed.
void
setItemImages(int itemId, S8 normalImage, S8 expandedImage)
Sets the normal and expanded images to show for the given item.
bool
setItemTooltip(int itemId, string tooltip)
Set the tooltip to show for the given item.
void
showItemRenameCtrl(int itemId)
Show the rename text field for the given item (only one at a time).
void
sort(int parentId, bool traverseHierarchy, bool parentsFirst, bool caseSensitive)
Sorts all items of the given parent (or root). With 'hierarchy', traverses hierarchy.
void
Toggle the hidden state of all objects in the current selection.
void
Toggle the locked state of all objects in the current selection.
Detailed Description
Hierarchical list of text items with optional icons.
Can also be used to inspect SimObject hierarchies, primarily within editors.
GuiTreeViewCtrls can either display arbitrary user-defined trees or can be used to display SimObject hierarchies where each parent node in the tree is a SimSet or SimGroup and each leaf node is a SimObject.
Each item in the tree has a text and a value. For trees that display SimObject hierarchies, the text for each item is automatically derived from objects while the value for each item is the ID of the respective SimObject. For trees that are not tied to SimObjects, both text and value of each item are set by the user.
Additionally, items in the tree can have icons.
Each item in the tree has a distinct numeric ID that is unique within its tree. The ID of the root item, which is always present on a tree, is 0.
new GuiTreeViewCtrl(DatablockEditorTree) { tabSize = "16"; textOffset = "2"; fullRowSelect = "0"; itemHeight = "21"; destroyTreeOnSleep = "0"; MouseDragging = "0"; MultipleSelections = "1"; DeleteObjectAllowed = "1"; DragToItemAllowed = "0"; ClearAllOnSingleSelection = "1"; showRoot = "1"; internalNamesOnly = "0"; objectNamesOnly = "0"; compareToObjectID = "0"; Profile = "GuiTreeViewProfile"; tooltipprofile = "GuiToolTipProfile"; hovertime = "1000"; };
TreeView
int tabSize
int textOffset
bool fullRowSelect
int itemHeight
bool destroyTreeOnSleep
If true, the entire tree item hierarchy is deleted when the control goes to sleep.
bool mouseDragging
bool multipleSelections
If true, multiple items can be selected concurrently.
bool deleteObjectAllowed
bool dragToItemAllowed
bool clearAllOnSingleSelection
bool showRoot
If true, the root item is shown in the tree.
bool useInspectorTooltips
bool tooltipOnWidthOnly
Inspector Trees
bool showObjectIds
If true, item text labels for objects will include object IDs.
bool showClassNames
If true, item text labels for objects will include class names.
bool showObjectNames
If true, item text labels for objects will include object names.
bool showInternalNames
If true, item text labels for obje ts will include internal names.
bool showClassNameForUnnamedObjects
If true, class names will be used as object names for unnamed objects.
bool compareToObjectID
bool canRenameObjects
If true clicking on a selected item ( that is an object and not the root ) will allow you to rename it.
bool renameInternal
If true then object renaming operates on the internalName rather than the object name.
Callbacks
onDeleteObject(SimObject object)
isValidDragTarget(int id, string value)
onDefineIcons()
onAddGroupSelected(SimGroup group)
onAddSelection(int itemOrObjectId, bool isLastSelection)
onSelect(int itemOrObjectId)
onInspect(int itemOrObjectId)
onRemoveSelection(int itemOrObjectId)
onUnselect(int itemOrObjectId)
onDeleteSelection()
onObjectDeleteCompleted()
onKeyDown(int modifier, int keyCode)
onMouseUp(int hitItemId, int mouseClickCount)
onMouseDragged()
onRightMouseDown(int itemId, Point2I mousePos, SimObject object)
onRightMouseUp(int itemId, Point2I mousePos, SimObject object)
onBeginReparenting()
onEndReparenting()
onReparent(int itemOrObjectId, int oldParentItemOrObjectId, int newParentItemOrObjectId)
onDragDropped()
onAddMultipleSelectionBegin()
onAddMultipleSelectionEnd()
canRenameObject(SimObject object)
handleRenameObject(string newName, SimObject object)
onClearSelection()
Public Functions
addChildSelectionByValue(int parentId, string value)
Add a child selection by it's value.
Parameters:
| parentId | Parent TreeItemId. |
| value | Value to search for. |
addSelection(int id, bool isLastSelection)
Add an item/object to the current selection.
Parameters:
| id | ID of item/object to add to the selection. |
| isLastSelection | Whether there are more pending items/objects to be added to the selection. If false, the control will defer refreshing the tree and wait until addSelection() is called with this parameter set to true. |
buildIconTable(string icons)
Builds an icon table.
Parameters:
| icons | Name of icons to build, Icons should be designated by the bitmap/png file names (minus the file extensions)and separated by colons (:). This list should be synchronized with the Icons enum |
True if it was successful, false if not.
buildVisibleTree(bool forceFullUpdate)
Build the visible tree.
Parameters:
| forceFullUpdate | True to force a full update of the tree, false to only update the new stuff. |
cancelRename()
Cancel renaming an item (For internal use).
clear()
Empty the tree.
clearFilterText()
Clear the current item filtering pattern.
clearHiddenItems()
Set the pattern by which to filter items in the tree. Only items in the tree whose text matches this pattern are displayed.
Parameters:
| pattern | New pattern based on which visible items in the tree should be filtered. If empty, all items become visible. |
clearSelection()
Unselect all currently selected items.
deleteSelection()
Delete all items/objects in the current selection.
editItem(int itemId, string newText, string newValue)
Edits the text and value for a given tree item.
Parameters:
| itemId | TreeItemID to edit. |
True if successful, false if not.
expandItem(int itemID, bool expand)
Expand/contract item, item's sub-tree.
Parameters:
| itemID | TreeItemId of item to expand or contract. |
| expand | True to expand the item, false to contract it. |
True if it was successful, false if not.
findChildItemByName(int parentId, string childName)
Get the child item of the given parent item whose text matches childName.
Parameters:
| parentId | Item ID of the parent in which to look for the child. |
| childName | Text of the child item to find. |
ID of the child item or -1 if no child in parentId has the given text childName.
note:This method does not recurse, i.e. it only looks for direct children.
findItemByName(string text)
Get the ID of the item whose text matches the given text.
Parameters:
| text | Item text to match. |
ID of the item or -1 if no item matches the given text.
findItemByObjectId(int objectId)
Find an item by its object id and returns the Tree Item ID for it.
Parameters:
| objectId | Object id you want the item id for. |
Tree Item Id for the given object ID.
findItemByValue(string value)
Get the ID of the item whose value matches value.
Parameters:
| value | Value text to match. |
ID of the item or -1 if no item has the given value.
getChild(int itemId)
Get the child of the parent with the given id.
Parameters:
| itemId | TreeItemID of item that a child we should get. |
Id of child of given item.
getFilterText()
Get the current filter expression. Only tree items whose text matches this expression are displayed. By default, the expression is empty and all items are shown.
The current filter pattern or an empty string if no filter pattern is currently active.
getFirstRootItem()
Get id for root item.
Id for root item.
getItemAtPosition(Point2I position)
Get the tree item at the passed in position.
Parameters:
| position | The position to check for what item is below it. |
The id of the item under the position.
getItemCount()
Get the total number of items in the tree or item count.
total number of items in the tree.
getItemObject(int itemId)
Gets the object for a particular item.
Parameters:
| itemId | Item id you want the object id for. |
Object Id for the given tree item ID.
getItemText(int itemId)
Gets the text for a given item.
Parameters:
| itemId | TreeItemID to get text of. |
Text for a given item.
getItemValue(int itemId)
Gets the value for a given item.
Parameters:
| itemId | TreeItemID to get value of. |
Value for a given item.
getNextSibling(int itemId)
Get the next sibling of the given item id in the tree.
Parameters:
| itemId | TreeItemID of item that we want the next sibling of. |
Id of next sibling of the given item.
getParentItem(int itemId)
Get the parent of a given id in the tree.
Parameters:
| itemId | TreeItemID of item that has a parent we should get. |
Id of parent of given item.
getPrevSibling(int itemId)
Get the previous sibling of the given item id in the tree.
Parameters:
| itemId | TreeItemID of item that we want the previous sibling of. |
Id of previous sibling of the given item.
getSelectedItem(int index)
Return the selected item at the given index.
Parameters:
| index | Given index to look for selected item. |
selected item at the given index.
getSelectedItemList()
Returns a space separated list if ids of all selected items.
space separated list of selected item ids.
getSelectedItemsCount()
Get the selected number of items.
number of selected items.
getSelectedObject(int index)
Return the currently selected SimObject at the given index in inspector mode or -1.
Parameters:
| index | Given index to look for selected object. |
currently selected SimObject at the given index in inspector mode or -1.
getSelectedObjectList()
Returns a space separated list of all selected object ids.
space separated list of all selected object ids.
getTabLevel(int itemId)
Get the tree item at the passed in position.
Parameters:
| position | The position to check for what item is below it. |
The id of the item under the position.
getTextToRoot(int itemId, string delimiter)
Gets the text from the current node to the root, concatenating at each branch upward, with a specified delimiter optionally.
Parameters:
| itemId | TreeItemId of node to start at. |
| delimiter | (Optional) delimiter to use between each branch concatenation. |
text from the current node to the root.
hideSelection(bool state)
Call SimObject::setHidden( state ) on all objects in the current selection.
Parameters:
| state | Visibility state to set objects in selection to. |
insertItem(int parentId, string text, string value, string icon, int normalImage, int expandedImage)
Add a new item to the tree.
Parameters:
| parentId | Item ID of parent to which to add the item as a child. 0 is root item. |
| text | Text to display on the item in the tree. |
| value | Behind-the-scenes value of the item. |
| icon | |
| normalImage | |
| expandedImage |
The ID of the newly added item.
insertObject(int parentId, SimObject obj, bool OKToEdit)
Inserts object as a child to the given parent.
isItemSelected(int id)
Check whether the given item is currently selected in the tree.
Parameters:
| id | Item/object ID. |
True if the given item/object is currently selected in the tree.
isParentItem(int itemId)
Returns true if the given item contains child items.
Parameters:
| itemId | TreeItemID to check for children. |
True if the given item contains child items, false if not.
lockSelection(bool lock)
Set whether the current selection can be changed by the user or not.
Parameters:
| lock | If true, the current selection is frozen and cannot be changed. If false, the selection may be modified. |
markItem(int itemID, bool mark)
Mark/unmark item.
Parameters:
| itemID | TreeItemId of item to Mark or unmark. |
| mark | True to Mark the item, false to unmark it. |
True if it was successful, false if not.
moveItemDown(int itemId)
Move the specified item down in the tree.
Parameters:
| itemId | TreeItemId of item to move down in the tree. |
moveItemUp(int itemId)
Move the specified item up in the tree.
Parameters:
| itemId | TreeItemId of item to move up in the tree. |
onRenameValidate()
Validate the new name for an object (For internal use).
open(string objName, bool okToEdit)
Set the root of the tree view to the specified object, or to the root set.
Parameters:
| objName | Name or id of SimSet or object to set the tree root equal to. |
removeAllChildren(int itemId)
Remove all children of an item from the tree with the given id.
Parameters:
| itemId | TreeItemID of item that has children we should remove. |
removeChildSelectionByValue(int parentId, string value)
Deselect a child item or remove it from the selection based on its parent and its value.
Parameters:
| parentId | Parent TreeItemId. |
| value | Value to search for. |
| performCallback | True to notify script of the change, false to not. |
removeItem(int itemId, bool deleteObjects)
Remove an item from the tree with the given id.
Parameters:
| itemId | TreeItemID of item to remove. |
| deleteObjects | Whether the object on the item is deleted when the item is. |
True if successful, false if not.
removeSelection(int itemId)
Deselect an item or remove it from the selection.
Parameters:
| itemId | Item Id to deselect. |
reparentItem(int itemId, int parentId)
Check whether the given item is currently selected in the tree.
Parameters:
| id | Item/object ID. |
True if the given item/object is currently selected in the tree.
scrollVisible(int itemID)
Make the given item visible.
Parameters:
| itemID | TreeItemId of item to scroll to/make visible. |
True if it was successful, false if not.
scrollVisibleByObjectId(int objectId)
Show item by object id.
Parameters:
| objectId | Object id you want to scroll to. |
True if successful, false if not.
selectItem(int itemID, bool select)
Select or deselect and item.
Parameters:
| itemID | TreeItemId of item to select or deselect. |
| select | True to select the item, false to deselect it. |
True if it was successful, false if not.
setDebug(bool value)
Enable/disable debug output.
Parameters:
| value | True to enable debug output, false to disable it. |
setFilterChildren(bool doFilterChildren)
Set the pattern by which to filter items in the tree. Only items in the tree whose text matches this pattern are displayed.
Parameters:
| pattern | New pattern based on which visible items in the tree should be filtered. If empty, all items become visible. |
setFilterText(string pattern)
Set the pattern by which to filter items in the tree. Only items in the tree whose text matches this pattern are displayed.
Parameters:
| pattern | New pattern based on which visible items in the tree should be filtered. If empty, all items become visible. |
setItemFilterException(uint item, bool isExempt)
Set the pattern by which to filter items in the tree. Only items in the tree whose text matches this pattern are displayed.
Parameters:
| pattern | New pattern based on which visible items in the tree should be filtered. If empty, all items become visible. |
setItemHidden(uint item, bool hidden)
Set the pattern by which to filter items in the tree. Only items in the tree whose text matches this pattern are displayed.
Parameters:
| pattern | New pattern based on which visible items in the tree should be filtered. If empty, all items become visible. |
setItemImages(int itemId, S8 normalImage, S8 expandedImage)
Sets the normal and expanded images to show for the given item.
Parameters:
| itemId | TreeItemID of item to set images for. |
| normalImage | Normal image to set for the given item. |
| expandedImage | Expanded image to set for the given item. |
setItemTooltip(int itemId, string tooltip)
Set the tooltip to show for the given item.
Parameters:
| itemId | TreeItemID of item to set the tooltip for. |
| tooltip | String tooltip to set for the item. |
True if successfully found the item, false if not
showItemRenameCtrl(int itemId)
Show the rename text field for the given item (only one at a time).
Parameters:
| itemId | TreeItemId of item to show rename text field for. |
sort(int parentId, bool traverseHierarchy, bool parentsFirst, bool caseSensitive)
Sorts all items of the given parent (or root). With 'hierarchy', traverses hierarchy.
Parameters:
| parentId | TreeItemID of parent/root to sort all the items under. Use 0 to sort the entire tree. |
| traverseHierarchy | True to traverse the hierarchy, false to not. |
| parentsFirst | True to sort the parents first. |
| caseSensitive | True to pay attention to case, false to ignore it. |
toggleHideSelection()
Toggle the hidden state of all objects in the current selection.
toggleLockSelection()
Toggle the locked state of all objects in the current selection.