Difference between revisions of "Palette:lister"

From TouchDesigner Documentation
Jump to: navigation, search
Line 111: Line 111:
*'''onClick, onClickRight, onClickMiddle''': (c) mouse pressed and released on a cell
*'''onClick, onClickRight, onClickMiddle''': (c) mouse pressed and released on a cell
*'''onClickHeader''': (c) Left mouse pressed and released on header row
*'''onClickHeader, onClickHeaderRight, onClickHeaderMiddle''': (c) mouse pressed and released on header row cell
*'''onDoubleClick''': (c) Left mouse double-click on cell
*'''onDoubleClickHeader''': (c) Left mouse double-click on header row cell
*'''onEditEnd''': (c) Cell text has been edited
*'''onEditEnd''': (c) Cell text has been edited
*'''onChangeCellText''': (c) A cell's text has been changed
*'''onChangeCellText''': (c) A cell's text has been changed

Revision as of 20:22, 10 April 2019

File Lister


The lister custom Component builds on List COMP to make a multi-featured tool for listing complex data. Formatting of the lister is set up in the internal config Component. Data can be provided via Python, parameter or table. Complex data and effects can be achieved using callbacks. NOTE: Many of lister's features require a basic knowledge of Python.

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

For examples of how to set up a lister, see Lister Custom COMP Examples.

Config Comp[edit]

The internal config Comp is where columns, colors, and other set-up is defined.

colDefine table[edit]

The colDefine table sets up the data definitions and look. The Autodefine Columns parameter can be set to True for simple set-ups, and turning it on and off will reset the auto-definitions, but for more complex set-ups, you'll want to define your own columns. TIP: to move your auto-defined columns into the custom, colDefine, push the autoCopy button inside lister.

The rows inside colDefine are as follows:

  • column: the internal name of the column. The name "rowData" is reserved.
  • columnLabel: the header label for the column. "*" uses the column name.
  • sourceData: if sourceDataMode is 'label', this value will be put in each cell. If lister is populated with dictionaries, this value is the key where data for this column is found. If lister is populated with objects, this value is the name of an object's member. If lister is populated with lists, this is the index in the list. In the case of lists, the index is optional, and the list's order will be used if sourceData is left blank.
  • sourceDataMode: the type of data stored in the column cells. In addition to formatting, this mode defines the way sorts are performed. Anything besides the following values will result in str(<sourceData>).
  • int, float or string fetches values via sourceData.
  • constant uses the literal sourceData string in the colDefine table.
  • color uses sourceData and takes a list of [r, g, b, a] or [r, g, b, a, "text"] (anything else will be treated as text with no color)
  • repr displays repr(sourceData)
  • eval treats sourceData as an expression to evaluate, with the row object available as "object". For example, to get the objects class name, you could set sourceData to object.__class__.__name__.
  • blank does not display any text, no matter what the value is, but keeps the value in the lister's Data list. This can be useful with the <topPath>* mode below.
  • cellLook: used to reference the tops in config Comp. Make a <cellLook> TOP, a <cellLook>Roll TOP (optional) and a <cellLook>Press TOP (optional).
  • topPath: path to top with graphic to display in cells. Paths are relative to this config comp. To make a top that changes on roll and press, create tops with names <topPath>Roll and <topPath>Press. If the path ends with *, the text value of the cell will be added to the path. This is useful for buttons with different states, such as toggles. For example, a topPath of switch would look for switchTrue or switchFalse if the cell held a bool value. Roll and Press will then be appended to those names for roll and press states. Setting sourceDataMode to blank is often helpful when using topPath with the * feature.
  • help: the default tooltip for the column. '*' will put the value of the cell in the tooltip, which is useful for long data like paths...
  • width: pixel width of column (ignored for stretch column)
  • stretch: (1 or 0) If 1, this column stretches.
  • editable: (0-2) text is editable. Row objects will automatically be updated. Other effects can be written in onEdit callback. If the value is 1, single-click to edit. If the value is 2, double-click.
  • selectRow: (1 or 0) If 1, clicking this column selects the row when row selection features are active
  • draggable: (1 or 0) if 1, this column's cells are draggable
  • clickOnDrag: (1 or 0) if 1, pressing a cell in this column causes a click event and dragging the mouse across other cells in this column will cause clicks as each new cell is entered.

define table[edit]

The define table holds extra definitions for lister. Each definition has a Description with info about its effects.


The various TOPs define the attributes for the table, rows, columns, and cells in various states. The button____ TOPs are an example of a user-defined look. The btnImage____ TOPs are an example of graphics to be displayed in cells.

The following table shows the correspondence between the text TOPs and the listCOMP's attrib members:

TOP parameter(s) listCOMP attrib
font fontFace
fontsizex fontSizeX
(fontcolorr, fontcolorg, fontcolorb, fontalpha) textColor
(bgcolorr, bgcolorg, bgcolorb, bgalpha) bgColor
bold fontBold
italic fontItalic
position1 textOffsetX
position2 textOffsetY
(alignx, aligny) textJustify
resolution2 rowHeight

In addition, all border settings from textTOPs will be applied to the attributes (<side>Border<location>Color)

Callbacks DAT[edit]

The callbacks DAT contains the lister's custom callbacks. The location of this DAT can be changed via the lister's parameters. For more information, see below.

Custom Callbacks[edit]

Custom callbacks facilitate complex Python tasks within the lister. 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 info dictionary always contains an "ownerComp" key. It will often contain an "about" key, describing the callback, and will always contain this key if a return value is expected. Generally, callbacks are called AFTER the internal method they are associated with, to allow over-riding of whatever that method does.

Callbacks marked with (c), called Cell Callbacks, can be named in two ways...

  • Callback<Column name> for specific columns (e.g. onClickNetwork, onClickName)
  • Callback for all cells (e.g. onClick)

If you want to see all callbacks being called, turn on the Print Callbacks switch in the lister parameters. Callbacks will now be printed to textport.

Basic Callbacks[edit]

  • onInit: When extension is re-initialized, but before initial refresh and auto-column set up
  • onPostInit: Called one frame after initialization.
  • onRefresh: Whenever list data is changed, a refresh is called. The following four callbacks all happen within every Refresh call.
  • onGetRawData: This is where the list of raw data is set up. For example, this could be a list of comps. Lister can currently analyze a list of lists, a list of tuples, a list of dicts, a list of objects, or a table operator. If a source table is provided in Lister parameters or through wiring, info["data"] will be pre-filled with the data from that table. Return a raw data list.
  • onConvertData: Turn the raw data into a workingData, a list of strings to be used in the table cells. Note that the object from rawdata is always appended to this list! Lister automates this to a large degree. Return a converted data list.
  • onFilter: Filter out elements of workingData as desired. Lister automates this to a large degree. Return a filtered data list.
  • onSort: Sort workingData as desired. Lister automates this to a large degree. Return a sorted data list.
  • onClick, onClickRight, onClickMiddle: (c) mouse pressed and released on a cell
  • onClickHeader, onClickHeaderRight, onClickHeaderMiddle: (c) mouse pressed and released on header row cell
  • onDoubleClick: (c) Left mouse double-click on cell
  • onDoubleClickHeader: (c) Left mouse double-click on header row cell
  • onEditEnd: (c) Cell text has been edited
  • onChangeCellText: (c) A cell's text has been changed
  • onMouseDown, onMouseRightDown, onMouseMiddleDown: (c) Mouse pressed down on cell
  • onMouseUp, onMouseRightUp, onMouseMiddleUp: (c) Mouse released down on cell
  • onMouseHold: (c) The mouse has been held down on a cell for a full second
  • onMouseDrag, onMouseRightDrag, onMouseMiddleDrag: Button down and dragged
  • onSelectRow: A row has been selected
  • onDeselectRow: a row has been deselected
  • onRemovedSelectedRow: a row that was selected was removed during Refresh
  • onSelectColumn: A header column has been selected by click (mouse press-release)
  • onDataChanged: The main data list has been altered. This callback is called BEFORE the listCOMP is reset.
  • onMoveRows: Rows have been rearranged
  • onDeleteRows: Rows have been deleted
  • onKeyPressed: Keyboard action
  • onDropHover: (c) Something is being dragged onto lister. Return true if interested. If True is not returned, no onDrop callback will be received.
  • onDrop: (c) Something is being dropped onto lister. If the drop is from another Lister, info['fromListerInfo'] will contain the source cell. Otherwise, that value will be None. You won't get this if the return value of the previous onDropHover call was False. The Drop parameter in the Drag page must be set to allow drops. The Drop Script parameter must be set to /sys/drop.
  • onAddRow: a row has been added to the lister via the AddRow method, or Undo/Redo.
  • onSetupAutoColDefine: the autoColDefine definitions have been recreated. Use this callback to customize the autoColDefine table.

Advanced Callbacks[edit]

The following callbacks will only be called if the Do Advanced Callbacks parameter is set to True. Generally, these callbacks will be called more often when active and are separated for the sake of speed.

  • onSetCellLook: (c) Called whenever a look is applied to a cell.
  • onSetCellText: (c) A cell's text is being set
  • onSetHeaderLook: Called when a look is applied to a header cell.
  • onSetRowLook: Called when a look is applied to a row
  • onInitCell: (c) Called when a cell is initialized, which happens after each Refresh
  • onInitHeader: Called when header row is initialized.
  • onInitRow: Called when row is initialized
  • onRollover: Mouse is rolling over the list.
  • onPressCell: (c) A cell is being pressed like a button, but has not been released. This can happen multiple times if the user presses and drags mouse on and off cell. Used in association with the "press" looks for buttons...
  • onRowObjectToWorkingData: called after a row is converted from a raw object to a list of data for the lister.
  • onSortDataRows: called after a set of rows are sorted by the lister.


Input 1 inputTable: A table of data to be used in the lister. This data can be filtered or sorted within the lister.


Output 1 out_table: A duplicate of the lister's data in text form. Output 2 out_selected: Info from selected rows

Custom Parameters[edit]

Many of lister's features are set up using custom parameters.

Lister Page[edit]

This is the parameter page with all basic lister settings.


Help Page Helppage - Open the lister wiki page in a browser.

Edit Config Comp Editconfigcomp - Open a network editor window for the Lister's Config Component.

Edit Column Definitions Editcoldefine - Open the lister's colDefine table.

Edit Callbacks Editcallbacks - Open a text editor for the Lister's callbacks.

Print Callbacks Printcallbacks - Enables debug prints of all callbacks (whether found or not) to the textport.

Refresh Refresh - Manually refresh the lister. NOTE: This re-analyzes raw data for lister, so dynamically added lister data might disappear!

Main Settings[edit]

Linked Table DAT Linkedtable - The lister's contents will be locked to the contents of this DAT. Changes to the DAT will be reflected in Lister and vice-versa.

Raw Data Lockfirstcol - This is a versatile parameter that can be either contain a path to a tableDAT containing data for the Lister, a python list, a python list of lists, or a python list of dictionaries.

Refresh On Input Change Refreshoninputchange - When on, lister will be automatically refreshed when wired inputTable changes.

Autodefine Columns Autodefinecols - Enables automatic generation of table columns.

Recreate Auto-columns Recreateautocolumns - Re-analyzes raw data to create automatic column definitions. This will resize column widths, among other things.

Copy Auto Cols To Config Copyautocolstoconfig - Pressing this button copies the column settings created by Autodefine Columns into the lister's custom colDefine table. This is useful for creating a starting point based on Autodefine settings. WARNING: this will destroy all current custom column settings.


Header Header - Enables the table header.

Clickable Header Clickableheader - Enables click-to-sort columns feature.

Multiple Row Select Multiplerowselect - Enables selection of multiple rows using shift and ctrl keys.

Selectable Rows Selectablerows - Enables selection of rows.

Drag To Reorder Rows Dragtoreorderrows - Enables drag to reorder feature.

Delete Key Deletekey - Enables selected row deletion using Delete key.

Highlight Rollover Highlightrollover - When on, rows will be highlighted when rolled over with the mouse. See Config Component inside for highlight colors.

Row Striping Rowstriping - Striping uses background color of rowStripeOverlay TOP in config COMP to color every other row. Dividing Lines uses color set in define table in config COMP to create an underline for each row.

Sorts, Filters, Selections[edit]

Sort Columns Sortcols - A space delimited list of columns to sort by. Note that this is set automatically when Clickable Header is set to True.

Sort Reverse Sortreverse - When True, sort order is reversed.

Filter Columns Filtercols - A space delimited list of columns to apply the filter to. If this is blank, no filter will be applied.

Filter String Filterstring - In order to be displayed, rows must contain the filter string in one or more of the filter columns.

Selected Rows Selectedrows - Always contains a space delimited list of the currently selected rows.

Advanced Page[edit]

This parameter page contains advanced user features for lister.

Do Advanced Callbacks Advancedcallbacks - Enables advanced callback features. See inside the internal Docs component for more information.

Allow Undo Allowundo - Enables Undo features when user edits cells and moves rows.

Lock Configs Lockconfigs - Turn off to allow changes to the following two parameters...

Config Comp Configcomp - The Lister's Config Component containing format information.

Callback DAT Callbackdat - The DAT containing the Lister's custom callbacks. Normally this is located in the Config Component.

ListerExt Extension Class[edit]

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


Data A list of Python Ordered Dictionaries, keyed by column names + a 'rowData' key containing the original raw data for the lister.
ColumnDict (Read Only) A dictionary of column name: column number.
ColNumDict (Read Only) A dictionary of column number: column name.
SelectedRowObjects (Read Only) A list of all rowObjects in selected rows.



Re-init table, refreshing all data and formatting all cells.


Delete a list of rows.
  • rows - A python list of row numbers.


Call this when you change the Lister's Data. Refreshes text and size. Does not get raw data, convert data, sort or filter.
  • selectionObjects (Optional) - a list of objects that will be selected if present in rowObjects.

GetObjectRowNum(object)row number of object

Returns the row number of the provided object.
  • object - the raw data row object used to populate the lister.

SelectRow(row, addRow=False)

Set selected row. Set row to None and addRow to False to remove all selections.
  • row - the row number to select.
  • addRow - (Keyword, Optional) Set to True to add row to current selection.


Deselect a row.
  • row - the row number to deselect.

SortDataRows(dataRows, keyList=None)

Sort a list of row data in place. This will sort using the columns set by the lister's Sort Columns parameter.
  • dataRows - a list of data rows.
  • keyList - (Keyword, Optional) A list of sort keys to apply to their corresponding columns. These will override standard sort methods. A value of None in the list means to use standard sort.

AddRow(self, rowNumber, rowData)

Add a row to lister data.
  • rowNumber - where to insert row.
  • rowData - must be a dictionary indexed by column name with an additional entry for 'rowObject'. It should look almost exactly like an entry in lister.Data, the exception being that it doesn't have to be an OrderedDict, but will be converted to one.

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 creates, composites and modifies images, and reads/writes images and movies to/from files and the network. TOPs run on the graphics card's GPU.

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.

Some operators have a DAT docked to them that contains some python functions. These functions, called "callbacks", get called when something in the operator changes.

Operators that have 1 or more input, like a Math CHOP, are called filters. See Generator.

A set of commands located in a Text DAT that are triggered to run under certain conditions. There are two scripting languages in TouchDesigner: Python and the original Tscript. Scripts and single-line commands can also be run in the Textport.

A form of DATs (Data Operators) that is structured as rows and columns of text strings.

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.