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.
For examples of how to set up a lister, see Lister Custom COMP Examples.
- 1 Summary
- 2 Config Comp
- 3 Custom Callbacks
- 4 Inputs
- 5 Outputs
- 6 Custom Parameters
- 7 ListerExt Extension Class
The internal config Comp is where columns, colors, and other set-up is defined.
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
sourceDataModeis '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
sourceDatais 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
stringfetches values via
constantuses the literal
sourceDatastring in the colDefine table.
sourceDataand takes a list of [r, g, b, a] or [r, g, b, a, "text"] (anything else will be treated as text with no color)
sourceDataas an expression to evaluate, with the row object available as "
object". For example, to get the objects class name, you could set
blankdoes not display any text, no matter what the value is, but keeps the value in the lister's
Datalist. This can be useful with the
- 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>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
switchwould look for
switchFalseif the cell held a bool value.
Presswill then be appended to those names for roll and press states.
- 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
- justify: text justification. Can be 'TOPLEFT', 'TOPCENTER', 'TOPRIGHT', 'CENTERLEFT', 'CENTER', 'CENTERRIGHT', 'BOTTOMLEFT', 'BOTTOMCENTER', or 'BOTTOMRIGHT'. Defaults to 'CENTERLEFT'
- 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.
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|
|(fontcolorr, fontcolorg, fontcolorb, fontalpha)||textColor|
|(bgcolorr, bgcolorg, bgcolorb, bgalpha)||bgColor|
In addition, all border settings from textTOPs will be applied to the attributes (
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 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.
- 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: (c) Left mouse pressed and released on header row
- 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
- onMouseUp: Mouse button raised over list
- 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
AddRowmethod, or Undo/Redo.
- onSetupAutoColDefine: the autoColDefine definitions have been recreated. Use this callback to customize the autoColDefine table.
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.
inputTable: A table of data to be used in the lister. This data can be filtered or sorted within the lister.
out_table: A duplicate of the lister's data in text form.
out_selected: Info from selected rows
Many of lister's features are set up using custom parameters.
This is the parameter page with all basic lister settings.
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.
Editcallbacks - Open a text editor for the Lister's callbacks.
Printcallbacks - Enables debug prints of all callbacks (whether found or not) to the textport.
Refresh - Manually refresh the lister. NOTE: This re-analyzes raw data for lister, so dynamically added lister data might disappear!
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.
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
Autodefinecols - Enables automatic generation of table 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 - Enables the table header.
Clickableheader - Enables click-to-sort columns feature.
Multiple Row Select
Multiplerowselect - Enables selection of multiple rows using shift and ctrl keys.
Selectablerows - Enables selection of rows.
Drag To Reorder Rows
Dragtoreorderrows - Enables drag to reorder feature.
Deletekey - Enables selected row deletion using Delete key.
Highlightrollover - When on, rows will be highlighted when rolled over with the mouse. See Config Component inside for highlight colors.
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
Sortcols - A space delimited list of columns to sort by. Note that this is set automatically when Clickable Header is set to True.
Sortreverse - When True, sort order is reversed.
Filtercols - A space delimited list of columns to apply the filter to. If this is blank, no filter will be applied.
Filterstring - In order to be displayed, rows must contain the filter string in one or more of the filter columns.
Selectedrows - Always contains a space delimited list of the currently selected rows.
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.
Allowundo - Enables Undo features when user edits cells and moves rows.
Lockconfigs - Turn off to allow changes to the following two parameters...
Configcomp - The Lister's Config Component containing format information.
Callbackdat - The DAT containing the Lister's custom callbacks. Normally this is located in the Config Component.
ListerExt Extension Class
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
||A list of Python Ordered Dictionaries, keyed by column names + a 'rowData' key containing the original raw data for the lister.|
||(Read Only) A dictionary of column name: column number.|
||(Read Only) A dictionary of column number: column name.|
||(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.
row number of object
- Returns the row number of the provided object.
object- the raw data row object used to populate the lister.
- 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.
- 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
Nonein 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 that contains its own inside. There are twelve 3D and eight 2D types. See also .
An 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 that manipulates text strings: multi-line text or tables. Multi-line text is often a command , but can be any multi-line text. are rows and columns of cells, each containing a text string.
Some operators have a DAT 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 .
A set of commands located in a Text DAT that are triggered to run under certain conditions. There are two scripting languages in TouchDesigner: and the original . Scripts and single-line commands can also be run in the .
A form of (Data Operators) that is structured as rows and columns of text strings.
An that contains its own inside. There are twelve 3D and eight 2D types. See also .