treelist

obj_uiZ_treelist

This is an object that can be used to display some sort of tree structure. The user can navigate this structure using a +/- box to collapse or extend certain "branches" of the tree. The object structure can be read from and xml file or string. To see this in action, please look at the example section. Unfortunately, all of the xml functions in uiZ aren't documented very well (yet). To get a list of xml functions, go to scripts > uiz > uiz > xml parser in a game maker project which has uiz imported.

You may see multiple references to "tree list item handle". Every entry in your tree list has it's own handle. The handle corresponds with the vertical position of the item in the tree list when it is fully expanded. So the very first (root) element would have handle 0, while the very next entry would have handle 1.

Property Variables

margin[1]: The margins used in multiple places.
boxcolor[c_black]: The color of the extend/collapse buttons of folders.
boxoncolor[c_gray]: The color of the extend/collapse buttons of folders when the mouse hovers over it.
boxincolor[c_ltgray]: The color of the extend/collapse buttons of folders when the mouse clicks it.
boxsprite[spr_uiZ_plusminbox]: The sprite to use for the folders. Image 0 should be an extend button and image 1 a collapse button.
font[-1]: the font to use, a value of -1 means font will be ignored (any random font will be used).
textcolor[c_black]: The color of text.
textoncolor[c_blue]: The color of text when the mouse hovers over it.
textselcolor[c_white]: The color of text when an item is selected.
backcolor[c_white]: The background color of an item.
backoncolor[c_black]: The background color of an item when the mouse hovers over it.
backselcolor[c_black]: The background color of an item when it's selected (e.g. the mouse clicks on it).
backdragcolor[$ffd1ab]: The background color of an item when it's being dragged.
backalpha[0]: The background alpha of an item when the mouse hovers over it.
backonalpha[0.5]: The background alpha of an item when the mouse is hovering over it.
backselalpha[1]: The background alpha of an item when it's selected (e.g. the mouse clicks on it).
backdragalpha[0.5]: The background alpha of an item when it's being dragged.
updateXML[true]: Whether to automatically update the given xml file when any changes to the tree list are made. If set to false, your xml file is unchanged. Use xml functions like uiz_xml_toString or uiz_xml_savefile to handle the updated XML file.
updateXMLBoxState[true]: Whether to also automatically update extended/collapsed state changes in the xml file. This refers to the user clicking the + or - box next to an entry. This parameter only has effect when updateXML is also set to true.
hierarchyLines[true]: Whether to show lines to indicate structure, or just indents. In the example below, the hierarchy lines are enabled. Hierarchy lines start off relatively thick (at hierarchyLineMaxWidth), and get thinner (by hierarchyLineDecreaseWidth) the deeper the hierarchy goes, until a minimum thickness is reached (hierarchyLineMinWidth).
hierarchyLineMaxWidth[5]: The maximum thickness of the hierarchy lines, used for items close to the root of the tree structure.
hierarchyLineMinWidth[1]: The minimum thickness of the hierarchy lines, used for items far away from the root of the tree structure.
hierarchyLineDecreaseWidth[1]: By how much the width of the hierarchy lines should decrease for each level of depth in the tree structure.
hierarchyLineColor[c_black]: What color the hierarchy lines should have.
scrollbarwidth[16]: The width of the scrollbar. (Only appears when items don't fit on screen)
scrollbarwidthtype[px]: The type of width of the scrollbar. (Only appears when items don't fit on screen)
scrollbarsprite[spr_uiZ_scrollbar]: The sprite to use for the scroll bar, see uiz_drawscrollbar_ for more information.
scrollbarbacktextmode[uiz_texturemode_fill]: How to draw the background. You can choose from uiz_texturemode_fill, texturemode_tile and texturemode_tilefit. See uiz_drawscrollbar_ for more information.
scrollbarcolor[c_white]: The color blend of the scrollbar.
onDragScript[uiz_treelist_clickScript_switch_node]: What script to call when the user drags a tree item over an other tree item. The arguments given to this script are:
- argument0: id of the tree list calling the script
- argument1: the handle/id of the item being dragged
- argument2: destinationItem, the handle/id of the item the mouse is currently over
- argument3: a float between 0 and 1 of how far the mouse is currently over the destinationItem.
onClickScript[uiz_treelist_clickScript_expand]: What script to call when the user clicks an item in the tree list. The arguments given to this script are:
- argument0: id of the tree list calling the script
- argument1: the handle/id of the item being clicked.

Readable variables

usexml[0]: The reference to the xml file used by this treelist.
update: When an item is selected.
scroll: Scroll value, see obj_uiZ_scrollbar for information on how to read this variable.

XML customizability

The following attributes can be added to tags:

name: A string to give a custom name do display. The tag name will be used by default. This is useful if your name should contain spaces or xml syntax characters.
sprite: If you want to add a little icon you can do that.
image: The image number for the sprite.
enabled: Whether you want to show this tag on the list. (Only applies for this item not the ones below it in the xml-structure).
boxState: Whether this item is collapsed, extended or doesn't how an +/- icon at all. There are three states:
- 0 (default): (equal to uiz_treelist_boxState_noBox), for no +/- box.
- 1: (equal to uiz_treelist_boxState_collapsed), for a box with a - on it. All children of this node aren't visible.
- 2: (equal to uiz_treelist_boxState_extended), for a box with a + on it. All children of this node are visible.

Functions

uiz_treelist_setxml(instanceid,xml handle[0]):
- instanceid: the instance id of the instance you want to modify
- usexml[0]: The reference to the xml file used by this treelist. Use a function like uiz_xml_loadstring or uiz_xml_loadfile to get a reference. See the example below to understand how to do this.
uiz_treelist_setmargin(instanceid, margin):
- instanceid: the instance id of the instance you want to modify
- margin[1]: The margins used in multiple places.
uiz_treelist_setboxsettings(instanceid, sprite, normal color, mouse over color, mouse click color):
- instanceid: the instance id of the instance you want to modify
- sprite[spr_uiZ_plusminbox]: The sprite to use for the folders. Image 0 should be an extend button and image 1 a collapse button.
- normal color[c_black]: The color of the extend/collapse buttons of folders.
- mouse over color[c_gray]: The color of the extend/collapse buttons of folders when the mouse hovers over it.
- mouse click color[c_ltgray]: The color of the extend/collapse buttons of folders when the mouse clicks it.
uiz_treelist_settextsettings(instanceid,normal color, mouse over color, mouse click color, font):
- instanceid: the instance id of the instance you want to modify
- normal color[c_black]: The color of text.
- mouse over color[c_blue]: The color of text when the mouse hovers over it.
- mouse click color[c_white]: The color of text when an item is selected.
- font[-1]: the font to use, a value of -1 means font will be ignored (any random font will be used).
uiz_treelist_setbackgroundsettings(instanceid, normal color, mouse over color, mouse click color, mouse drag color, normal alpha, mouse over alpha, mouse in alpha, mouse drag alpha):
- instanceid: the instance id of the instance you want to modify
- normal color[c_white]: The background color of an item.
- mouse over color[c_black]: The background color of an item when the mouse hovers over it.
- mouse click color[c_black]: The background color of an item when it's selected.
- mouse drag color[$ffd1ab]: The background color of an item when it's being dragged.
- alpha[0]: The background alpha of an item when the mouse hovers over it.
- mouse over alpha[0.5]: The background alpha of an item when the mouse is hovering over it.
mouse in alpha[1]: The background alpha of an item when it's selected (e.g. the mouse clicks on it).
mouse drag alpha[0.5]: The background alpha of an item when it's being dragged.
uiz_treelist_setXMLSettings(instanceid,updateXML,updateXMLBoxState):
- instanceid: the instance id of the instance you want to modify
- updateXML[true]: Whether to automatically update the given xml file when any changes to the tree list are made. If set to false, your xml file is unchanged. Use xml functions like uiz_xml_toString or uiz_xml_savefile to handle the updated XML file.
- updateXMLBoxState[true]: Whether to also automatically update extended/collapsed state changes in the xml file. This refers to the user clicking the + or - box next to an entry. This parameter only has effect when updateXML is also set to true.
uiz_treelist_setHierarchyLinesSettings(instanceid, hierarchyLines, hierarchyLineMaxWidth, hierarchyLineMinWidth, hierarchyLineDecreaseWidth, hierarchyLineColor):
- hierarchyLines[true]: Whether to show lines to indicate structure, or just indents. In the example below, the hierarchy lines are enabled. Hierarchy lines start off relatively thick (at hierarchyLineMaxWidth), and get thinner (by hierarchyLineDecreaseWidth) the deeper the hierarchy goes, until a minimum thickness is reached (hierarchyLineMinWidth).
- hierarchyLineMaxWidth[5]: The maximum thickness of the hierarchy lines, used for items close to the root of the tree structure.
- hierarchyLineMinWidth[1]: The minimum thickness of the hierarchy lines, used for items far away from the root of the tree structure.
- hierarchyLineDecreaseWidth[1]: By how much the width of the hierarchy lines should decrease for each level of depth in the tree structure.
- hierarchyLineColor[c_black]: What color the hierarchy lines should have.
uiz_treelist_setscrollbarsettings(instanceid, width, widthtype, sprite,texturemode, color):
- instanceid: the instance id of the instance you want to modify
- width[16]: The width of the scrollbar. (Only appears when items don't fit on screen)
- widthtype[px]: The type of width of the scrollbar. (Only appears when items don't fit on screen)
- sprite[spr_uiZ_scrollbar]: The sprite to use for the scroll bar, see uiz_drawscrollbar_ for more information.
- texturemode[uiz_texturemode_fill]: How to draw the background. You can choose from uiz_texturemode_fill, texturemode_tile and texturemode_tilefit. See uiz_drawscrollbar_ for more information.
- color[c_white]: The color blend of the scrollbar.
uiz_treelist_onDrag(instanceid, dragScript): Set what has to happen when the user drags a tree item over another tree item.
- instanceid: the instance id of the instance you want to modify
- onDragScript[uiz_treelist_dragScript_move]: What script to call when the user drags a tree item over another tree item. The arguments given to this script are:
  - argument0: id of the tree list calling the script
  - argument1: the handle/id of the item being dragged
  - argument2: destinationItem, the handle/id of the item the mouse is currently over
  - argument3: a float between 0 and 1 of how far the mouse is currently over the destinationItem.
uiz_treelist_onClick(instanceid, clickScript): Set what has to happen when the user drags a tree item over another tree item.
- instanceid: the instance id of the instance you want to modify
- clickScript[uiz_treelist_clickScript_switch_node]: What script to call when the user clicks an item in the tree list. The arguments given to this script are:
  - argument0: id of the tree list calling the script
  - argument1: the handle/id of the item being clicked
uiz_treelist_isMouseOverBox(instanceid, itemHandle): check if the mouse is over a +/- box within a certain item. Does not properly check mouse y levels, so only use this within onClickScripts.
- instanceid: the instance id of the instance you want to modify
- itemHandle: the handle to an item in the treelist. You can get this as argument1 in the clickScript.
uiz_treelist_exportxml(instanceid, xml): Removes any data in the given xml file (loaded in the xml parser) and replaces it with the data in the treelist. To create a new file use "xmlFile = uiz_xml_createfile()". After using this function on the new file, you can use uiz_xml_savefile or uiz_xml_toString to output the xml to a text medium.
- instanceid: the instance id of the instance you want to modify
- xml: A reference to an xml file to put the treelist contents into. Note that any existing data will get deleted.
xmlHandle = uiz_treelist_getXmlHandle(instanceid, listHandle):
- xmlHandle: A handle usable by uiZ xml functions. Take care with this handle, you can end up having your xml and treelist out of sync.
- instanceid: the instance id of the instance you want to modify
- listHandle: The handle referring to an item in the tree list.
uiz_treelist_addEntryAt(instanceid, handle, name, [sprite], [spriteImage], [indentLevel],[enabled], [boxState],[extraAttributeNameList,extraAttributeDataList]): adds an entry right before a tree list item handle, with (by default) the same indentation as the item on the handle.
- instanceid: the instance id of the instance you want to modify
- handle: The handle referring to an item in the tree list.
- name: The text to display on the treelist item.
- sprite: Optional parameter. Defines the use of a sprite next to your entry.
- spriteImage: Optional parameter. Defines the image index to use for the previously defined sprite.
- indentLevel: Optional parameter. How far the item should be indented. This is basically how deep should it be in the structure. 0 means that your item is placed at the root. Be careful with this argument. If unsure, use "uiz_treelist_item_get_indentLevel(handle)".
- enabled: Whether this item should be drawn or not.
- boxState: What state the +/- expand/collapse box should have. You can choose from:
  - 0 (default): (equal to uiz_treelist_boxState_noBox), for no +/- box.
  - 1: (equal to uiz_treelist_boxState_collapsed), for a box with a - on it. All children of this node aren't visible.
  - 2: (equal to uiz_treelist_boxState_extended), for a box with a + on it. All children of this node are visible.
- extraAttributeNameList: Use this argument only if you have updateXML set to true. This can be used to add extra attributes to the xml file. It has no further effect on the treelist.
- extraAttributeNameList: Use this argument only if you have updateXML set to true. This can be used to add extra attributes to the xml file. It has no further effect on the treelist. Set extraAttributeNameList to a ds_list of attribute names. If you use this argument, you also need to use the next one: "extraAttributeDataList".
- extraAttributeDataList: Use this argument only if you have updateXML set to true. This can be used to add extra attributes to the xml file. Set extraAttributeDataList to a ds_list of attribute values. Make sure the two lists are the same size. Every index in the NameList corresponds to the same index in the DataList.
uiz_treelist_removeEntry(instanceid, handle, recursive): Removes an entry from a treelist. If this entry has children, the children will be placed in the entry above the deleted entry. However, if that entry doesn't exist (e.g. you are at the first node) or the indentLevel of the entry above is not the same as this one, the children might get broken. If recursive mode is enabled however, all children are deleted.
- instanceid: the instance id of the instance you want to modify
- handle: The handle referring to an item in the tree list.
- recursive: Whether to also remove any of the children below the chosen entry.
uiz_treelist_isItemVisible(instanceid, handle): Returns whether all the parents of the item are extended. If all parents are extended the item is visible, else it is not. Does not check for scrolling visibility or occlusion from other objects.
- instanceid: the instance id of the instance you want to modify
- handle: The handle referring to an item in the tree list.
uiz_treelist_moveEntry(instanceid, itemHandle, destinationHandle, [indentLevel], [isOffset]): Moves an entry from item to destination.
- instanceid: the instance id of the instance you want to modify
- itemHandle: The handle referring to an item in the tree list.
- destinationHandle: The handle referring to a position in the tree list of where the itemHandle should go.
- indentLevel: Optional parameter. How far the item should be indented. This is basically how deep should it be in the structure. 0 means that your item is placed at the root. Be careful with this argument. If unsure, use "uiz_treelist_item_get_indentLevel(handle)". If this argument is omitted the indent of the item already at the destinationHandle is used. If isOffset is set to true, this argument will act as offset to the default indentLevel, instead of an overriding absolute value.
- isOffset: If this argument is true the default indentLevel is used, but indentLevel given by argument is added (or subtracted) from the default indentLevel.
uiz_treelist_moveEntry(instanceid, itemHandle, destinationHandle, [indentLevel], [isOffset]): Moves an entry and all its children from item to destination. For a list of arguments, see "uiz_treelist_moveEntry".
handle = uiz_treelist_handle_getByName(instanceid, itemName): Returns a handle to the first occurring tree list entry with the given name.
- handle: The return value. This handle refers to the found tree list entry with the given name. Returns -1 if no item was found.
- instanceid: the instance id of the instance you want to modify
- itemName: A string containing the displayed name of the item you are looking for.
handle = uiz_treelist_handle_getByName(id, itemName1, itemName2, ...): Finds itemName n that is inside itemName n-1, which is inside itemName n-2, etc... And example would be "uiz_treelist_handle_getByName(id, 'animals', 'mammals', 'cats')" vs "uiz_treelist_handle_getByName(id, 'movies', '2019', 'cats')"
- handle: The return value. This handle refers to the found tree list entry with the given name. Returns -1 if no item was found.
- instanceid: the instance id of the instance you want to modify
- itemName n: If this is the last argument to this function, this should simply contain the name of the item you are looking for. If this is not the last argument, it should contain an item name of a parent element in which the next argument is placed.
handle = uiz_treelist_handle_getEnd(instanceid, handle): takes a treelist handle and returns a handle to the last item within in the node.
- handle: The return value. This returns the last child in the given handle. If no child has been found, it returns the handle in argument1.
- instanceid: the instance id of the instance you want to modify
- handle: The handle to a node which contains other nodes.
name = uiz_treelist_item_get_name(treelist, itemHandle):
- name: A string containing the name of the item (what text is displayed to the user in the tree)
- instanceid: the instance id of the instance you want to modify
- itemHandle: The handle to a node from which you want to read data.
sprite = uiz_treelist_item_get_sprite(treelist, itemHandle):
- sprite: Returns what sprite is used for the given item. -1 means there is no sprite used.
- instanceid: the instance id of the instance you want to modify
- itemHandle: The handle to a node from which you want to read data.
spriteImg = uiz_treelist_item_get_sprite(treelist, itemHandle):
- spriteImg: Returns what sprite image is used for the given item.
- instanceid: the instance id of the instance you want to modify
- itemHandle: The handle to a node from which you want to read data.
indentLevel = uiz_treelist_item_get_indentLevel(treelist, itemHandle): Gets how many levels this treelist is indented. This is equal to the amount of parents this item has. An item at the root of the tree has an indentLevel of 0.
- indentLevel: Returns the indent level of the given item.
- instanceid: the instance id of the instance you want to modify
- itemHandle: The handle to a node from which you want to read data.
enabled = uiz_treelist_item_get_enabled(treelist, itemHandle):
- enabled: Returns a boolean on whether the given item is enabled or disabled.
- instanceid: the instance id of the instance you want to modify
- itemHandle: The handle to a node from which you want to read data.
boxState = uiz_treelist_item_get_boxState(treelist, itemHandle): Returns the state of the little +/- box used to expand/collapse items.
- boxState: This function can return the following states:
  - uiz_treelist_boxState_noBox: no box is drawn
  - uiz_treelist_boxState_collapsed: a + box is drawn, the children are not visible
  - uiz_treelist_boxState_extended: A - box is drawn, the children are visible.
- instanceid: the instance id of the instance you want to modify
- itemHandle: The handle to a node from which you want to read data.

click/dragScripts

Useful functions for your click/dragScripts

To make the treelist versatile, a few event activated scripts have been added, as you can read about "Property Variables" and "Functions" sections. Some functions may be useful to you when making these scripts:

uiz_mouse_isDoubleClick(): If the user single clicked or double clicked your object. Note that on a double click the function will fire twice: once where uiz_mouse_isDoubleClick returns false, and a few steps later where uiz_mouse_isDoubleClick returns true. Useful for onClick scripts.
uiz_treelist_isMouseOverBox(): Check if the mouse is hovering over the +/- box on an item. Useful for onClick scripts.
uiz_treelist_item_ functions: There is a whole suite of functions to get information about the tree item the user has just clicked or dragged from/to. Use this however you want.

Premade click scripts

The following click scripts have been implemented:

uiz_treelist_clickScript_switch_node: Just extends/collapses the node the user clicked on.

Premade drag scripts

The following drag scripts have been implemented:

uiz_treelist_dragScript_move: Moves the draggingItem to the place of the itemDestination. If the user hovered their mouse over the bottom of the destination, the item will be put on top. If the user hovered their mouse over the bottom of the destination, the draggingItem is placed inside the destination. All operations done are recursive, meaning all the children of the draggingItem are also moved.

Example

uiz_xml_init()
//create xml
folders=uiz_xml_loadstring(@"
<C name=\42C:\42>
<some_folder>
 <workfolder/>
</some_folder>
<video's>
 <fun/>
 <random/>
</video's>
<system_files>
 <important/>
 <viruses/>
</system_files>
<what_you_looking_at>
 <nothing/>
 <you/>
</what_you_looking_at>
<homework>
 <tentacle/>
</homework>
</C>
")
folderview=uiz_c(obj_uiZ_treelist);
uiz_setParent(folderview,win);
folderview.posinframey=uiz_fill;
folderview.posinframex=uiz_fill;
uiz_treelist_setxml(folderview,folders);//set and load the xml
uiz_fixgeneralpos(folderview)