Difference between revisions of "Palette:treeLister"

From TouchDesigner Documentation
Jump to: navigation, search
Line 152: Line 152:
 
== Methods ==
 
== Methods ==
  
 +
<!--PYHMVK ReloadInput-->
 
'''<code>ReloadInput()</code>'''
 
'''<code>ReloadInput()</code>'''
 
:Reload input JSON or table.
 
:Reload input JSON or table.
 +
<!--PYHEND-->
  
'''<code>FromPathGetRowNum(path, startRow)</code> &rarr; <code>Row number or None if row object is not currently visible. '''
+
<!--PYHMVK FromPathGetRowNum-->
 +
'''<code>FromPathGetRowNum(path, startRow)</code> &rarr; <code>Row number or None if row object is not currently visible.</code>'''
 
:Only works in <code>Table with "path" col</code> mode.
 
:Only works in <code>Table with "path" col</code> mode.
 
:* <code>path</code>: The object's path
 
:* <code>path</code>: The object's path
 
:* <code>startRow</code>:  '''(Optional)''' - Start the search at this row. Default: 0.
 
:* <code>startRow</code>:  '''(Optional)''' - Start the search at this row. Default: 0.
 +
<!--PYHEND-->
  
 +
<!--PYHMVK FromPathsSelectRows-->
 
'''<code>FromPathsSelectRows(paths, addSelection)</code> &rarr; <code>list of paths that were not found</code>'''
 
'''<code>FromPathsSelectRows(paths, addSelection)</code> &rarr; <code>list of paths that were not found</code>'''
 
:Select the rows with the provided paths. Tree will be expanded to selected paths. Only works in 'Table with "path" col' mode. Any paths not found will be ignored.
 
:Select the rows with the provided paths. Tree will be expanded to selected paths. Only works in 'Table with "path" col' mode. Any paths not found will be ignored.
 
:* <code>paths</code>: a list of path strings matching paths in the input table
 
:* <code>paths</code>: a list of path strings matching paths in the input table
 
:* <code>addSelection</code>:  '''(Optional)''' - if True, add to current selection. Default: False.
 
:* <code>addSelection</code>:  '''(Optional)''' - if True, add to current selection. Default: False.
 +
<!--PYHEND-->
  
 +
<!--PYHMVK CollapseAll-->
 
'''<code>CollapseAll()</code>'''
 
'''<code>CollapseAll()</code>'''
 
:Collapse all tree branches.
 
:Collapse all tree branches.
 +
<!--PYHEND-->
  
 +
<!--PYHMVK ToggleExpand-->
 
'''<code>ToggleExpand(''ID, value=None, root=None'')</code>'''
 
'''<code>ToggleExpand(''ID, value=None, root=None'')</code>'''
 
:Switch the expanded setting of a tree ID branch. Requires a manual <code>Refresh()</code> call to update tree.
 
:Switch the expanded setting of a tree ID branch. Requires a manual <code>Refresh()</code> call to update tree.
Line 173: Line 182:
 
:* <code>value</code>:  '''(Optional)''' - if provided, switch to that value. Otherwise, toggle value.
 
:* <code>value</code>:  '''(Optional)''' - if provided, switch to that value. Otherwise, toggle value.
 
:* <code>root</code>:  '''(Optional)''' - for trees with overlapping roots displayed, you can specify which root to expand the given ID in with this argument. Otherwise, ID will toggle in ALL roots.
 
:* <code>root</code>:  '''(Optional)''' - for trees with overlapping roots displayed, you can specify which root to expand the given ID in with this argument. Otherwise, ID will toggle in ALL roots.
 +
<!--PYHEND-->
  
 +
<!--PYHMVK CreateJSONObject-->
 
'''<code>CreateJSONObject(''roots=None'')</code>  &rarr; <code>[http://docs.python.org/3.5/library/collections.html?highlight=ordereddict#collections.OrderedDict OrderedDict]</code>'''
 
'''<code>CreateJSONObject(''roots=None'')</code>  &rarr; <code>[http://docs.python.org/3.5/library/collections.html?highlight=ordereddict#collections.OrderedDict OrderedDict]</code>'''
 
:Create a JSON compatible Python object from tree data, starting at the given roots. '''Note:''' this only works in JSON Input Mode.
 
:Create a JSON compatible Python object from tree data, starting at the given roots. '''Note:''' this only works in JSON Input Mode.
 
:* <code>roots</code> '''(Optional)''' - a list of IDs that will be the root nodes of the Python object. If not provided, the entire tree will be used.
 
:* <code>roots</code> '''(Optional)''' - a list of IDs that will be the root nodes of the Python object. If not provided, the entire tree will be used.
 +
<!--PYHEND-->
  
 +
<!--PYHMVK CreateJSONText-->
 
'''<code>CreateJSONText(''roots=None'')</code> &rarr; <code>JSON text</code>'''
 
'''<code>CreateJSONText(''roots=None'')</code> &rarr; <code>JSON text</code>'''
 
:Create JSON text from tree data, starting at the given roots. '''Note:''' this only works in JSON Input Mode.
 
:Create JSON text from tree data, starting at the given roots. '''Note:''' this only works in JSON Input Mode.
 
:* <code>roots</code> '''(Optional)''' - a list of IDs that will be the root nodes of the JSON text object. If not provided, the entire tree will be used.
 
:* <code>roots</code> '''(Optional)''' - a list of IDs that will be the root nodes of the JSON text object. If not provided, the entire tree will be used.
 +
<!--PYHEND-->

Revision as of 21:31, 10 April 2019

The treeLister custom Component provides a powerful and easy way to make tree controls for displaying hierarchical data. It is derived from the lister custom component, so many of its features are documented in that Component's wiki pages. Note: many of treeLister's features require a basic knowledge of Python.

You can find treeLister in the Palette under the folder Derivative>UI. Drag and drop the component from the Palette into your network.

See Also: Palette:lister, Lister Custom COMP Examples

Quick Start
[edit]

There are three main ways to input data into a treeLister. They correspond to the options in the Input Mode parameter. Be sure the appropriate option is selected there when using the following methods...

Callbacks Only[edit]

This method is useful for data objects that already have a hierarchical structure, such as file directories and TouchDesigner networks. To use callbacks to dynamically generate tree data, you must:

  • define the following callbacks: getObjectFromID, getIDFromObject, getObjectChildren. See Basic Callbacks below for information about each one. To edit treeLister's callbacks, click the Edit Callbacks parameter on the Lister parameter page.
  • define tree roots in the Roots parameter and/or define the treeLister's DefaultRoots member in the onInit callback. DefaultRoots will be used if the Roots parameter is blank.

JSON[edit]

For this method, wire a DAT containing a valid JSON text object into the treeLister's input. The JSON object will be represented in tree form.

The row objects that are automatically created from JSON have the following members:

  • key: The object's key in it's parent container. This is a key string for objects in dicts and an index integer for objects in lists.
  • id: The tree ID used for the object. This is a tuple of keys leading to the object from the root.
  • type: The type of the object.
  • value: The value of the object if it does not hold a container.
  • children: The object's children if it holds a container.

Table with "path" col[edit]

For this method, wire a table DAT with column headers and a "path" column into the treeLister's input. The path should be unique for every row of the table. If necessary, set the Path Separator parameter. Example DATs for use with this method: OP Find DAT and Folder DAT.

Table with "path", "wirepath", and "parentpath" cols[edit]

For this method, wire a table DAT with column headers and "path", "wirepath", and "parentpath" columns into the treeLister's input. This is for use with the OP Find DAT to create tree data from TouchDesigner networks that include grey wired hierarchies.

Column Definitions[edit]

To verify your data and get the basics of your tree set up, turn on the Autodefine Columns parameter on the Lister page.

Ultimately you will probably want to create your own column definitions for a tree lister. For information about that, see Lister Custom COMP: colDefine table. For full tutorials, see: Lister Custom COMP Examples. Note: you should always keep the first two columns for indent and expander button. The third column should be stretchy to absorb each row's indent.

Config Comp
[edit]

The internal config Comp is where columns, colors, and other set-up is defined. All the features of Lister's Config Comp are available. Only the changes and additions will be described here.

colDefine table[edit]

The colDefine table sets up the data definitions and look. For detailed info, see Lister Custom COMP: colDefine table.

Required Columns[edit]

TreeLister has two required columns: Indent and Expando. These are set up for you in the default treeLister, and you will generally not have to change them. The Indent column is the empty space before a row, and the Expando column contains the button to expand and collapse tree branches.

The third column should be set to stretch to absorb each row's indent. Tip: the width entry sets the minimum width for stretchable columns, so set that to a number large enough to display your tree labels.

Changes To sourceData and sourceDataMode[edit]

TreeLister adds a new sourceDataMode to lister's choices: "id" will display a row object's tree ID.

When treeLister is using Table with "path" col Input Mode, sourceData will refers to the column label in the input table. In this mode, the special sourceData entry __row__ will also be available to display the source row of the input table. Tip: "__row__" is also available as a key in the row object of each lister Data row.

define table[edit]

The define table holds extra definitions for a lister. The treeLister adds an indentWidth row which defines the number of pixels to indent each level of the tree.

TOPs[edit]

The various TOPs define the attributes for the table, rows, columns, and cells in various states. The treeLister adds a few of these, most important of which are the expando* TOPs. These define the way the expando button looks in the treeLister.

Custom Callbacks
[edit]

Custom callbacks facilitate complex Python tasks within the treeLister. Callbacks always take a single argument, an info dictionary of values relevant to the callback. Print this dictionary to see what is being passed. The keys will explain what each item is. The following are new callbacks added to treeLister:

Basic Callbacks[edit]

  • getObjectFromID: Every row object in a treeLister must have a unique ID, which is often the "path" to the object. This callback must return the row object. The info dictionary provides:
  • id: the ID used to identify the object
  • jsonObject: if the tree has an associated JSON hierarchy, this is the object returned by that hierarchy for the given ID.
  • getIDFromObject: This is the reverse of getObjectFromID. This callback must return the ID. The info dictionary provides:
  • object: the row object
  • jsonID: if the tree has an associated JSON hierarchy, this is the ID returned by that hierarchy for the given object.
  • getObjectChildren: This callback must return a list of child objects for the provided tree row object. The info dictionary provides:
  • object: the row object
  • jsonChildren: if the tree has an associated JSON hierarchy, this is a list of object's child objects in that hierarchy.

Advanced Callbacks[edit]

  • onReloadInput: Called after input JSON or table data is reloaded into tree.
  • onBuildTreeData: Called after the tree builds its working data for all rows.
  • onTreeInitRow: Called after the tree initializes a data row, including setting its rowIndent attribute.

Custom Parameters
[edit]

Basic treeLister functionality is set up with parameters.

Tree Page[edit]

Tools[edit]

Collapse All Collapseall - Collapse all branches of the tree.

Reload Input Reloadinput - Reload input table or JSON.

Settings[edit]

Input Mode Inputmode - Select the mode for the Component's input.

  • Callbacks Only: Use the callback system to build the tree dynamically. Requires that the following callbacks are defined: getObjectFromID, getIDFromObject, getObjectChildren.
  • JSON: Input provided through text DAT wired to input. The DAT must contain a valid JSON text object.
  • Table with "path" col: Input provided through table DAT wired to input. The DAT must have a "path" column that contains a unique path for each row. These paths will be used to define the tree hierarchy.

Path Separator Pathseparator - The separator used in the "path" column for the Table with "path" col input mode.

Roots Roots - A Python list of tree ID's to be used as the root objects in the tree.

Show Roots Roots - If off, the tree will start at the defined roots, but will start displaying at the roots' children. For example, this can be used to show every file in a folder without displaying a node for the folder itself.

Click Corner To Refresh Clickcornertorefresh - When on, treeLister will display a refresh button in the top-left of the tree. This is useful for manually refreshing data that has changed.

TreeListerExt Extension Class
[edit]

The TreeListerExt extension provides extended functionality for working with treeLister. Frequently used promoted members and methods are listed here. A full list can be found using the Python help() function.

Note: The TreeListerExt class uses ownerComp in an unusual way, to refer to its internal Lister custom Component. The treeLister itself is stored in its treeListerComp member.

Members[edit]

Lister The internal Lister custom Component. Note: this is also ownerComp, for inheritance reasons.
TreeLister The TreeLister component itself. Note: this is not ownerComp, for inheritance reasons.
DefaultRoots A set of tree IDs to be used as the default roots, if the Root parameter is empty.
Roots (Read Only) The IDs of the tree's root objects.
SelectedPaths (Read Only) All selected paths. Only works in 'Table with "path" col' mode.

Methods[edit]

ReloadInput()

Reload input JSON or table.

FromPathGetRowNum(path, startRow)Row number or None if row object is not currently visible.

Only works in Table with "path" col mode.
  • path: The object's path
  • startRow: (Optional) - Start the search at this row. Default: 0.

FromPathsSelectRows(paths, addSelection)list of paths that were not found

Select the rows with the provided paths. Tree will be expanded to selected paths. Only works in 'Table with "path" col' mode. Any paths not found will be ignored.
  • paths: a list of path strings matching paths in the input table
  • addSelection: (Optional) - if True, add to current selection. Default: False.

CollapseAll()

Collapse all tree branches.

ToggleExpand(ID, value=None, root=None)

Switch the expanded setting of a tree ID branch. Requires a manual Refresh() call to update tree.
  • ID: object ID
  • value: (Optional) - if provided, switch to that value. Otherwise, toggle value.
  • root: (Optional) - for trees with overlapping roots displayed, you can specify which root to expand the given ID in with this argument. Otherwise, ID will toggle in ALL roots.

CreateJSONObject(roots=None)OrderedDict

Create a JSON compatible Python object from tree data, starting at the given roots. Note: this only works in JSON Input Mode.
  • roots (Optional) - a list of IDs that will be the root nodes of the Python object. If not provided, the entire tree will be used.

CreateJSONText(roots=None)JSON text

Create JSON text from tree data, starting at the given roots. Note: this only works in JSON Input Mode.
  • roots (Optional) - a list of IDs that will be the root nodes of the JSON text object. If not provided, the entire tree will be used.

An Operator Family that contains its own Network inside. There are twelve 3D Object Component and eight 2D Panel Component types. See also Network Path.

An Operator Family that manipulates text strings: multi-line text or tables. Multi-line text is often a command Script, but can be any multi-line text. Tables are rows and columns of cells, each containing a text string.

The location of an operator within the TouchDesigner environment, for example, /geo1/torus1, a node called torus1 in a component called geo1. The path / is called Root. To refer instead to a filesystem folder, directory, disk file or http: address, see Folder.

TouchDesigner is a hierarchy of components. "root" is the top-most network in the hierarchy. The Path is simply /. A typical path is /project1/moviein1.