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. There is also an extensive tutorial here.

Custom Parameters

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

Lister Page

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. (Only available when Auto-define Columns is off)

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!

Input Settings

Input Table DAT Inputtabledat - Table used as input to the lister. Wired input will override this.

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

Input Table Has Headers Inputtablehasheaders - If True, the first row of the input table will be treated as column headers. For this to work, every column must have a non-blank header.

Auto-sync Input Table Autosyncinputtable - If True, changes to the lister will be mirrored back to Input Table DAT automatically. This only works for columns with the following sourceDataModes: int, float, string, version, blank, color. Only available when Input Table DAT is defined via parameter and Input Table Has Headers is True.

Setup Settings

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.

Selectable Rows Selectablerows - Enables selection of rows.

Multiple Row Select Multiplerowselect - Enables selection of multiple rows using shift and ctrl keys. Only available when Selectable Rows is on.

Drag To Reorder Rows Dragtoreorderrows - Enables drag to reorder feature. Only available when Selectable Rows is on (rows must be selected to reorder).

Arrow Keys Arrowkeys - Enables moving the row selection using arrow keys. Only available when Selectable Rows is on.

Delete Key Deletekey - Enables selected row deletion using Delete key. Only available when Selectable Rows is on.

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 behavior

  • 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.

Drop Highlight Drophighlight - Defines preview when an external object is dragged into lister and defined as an acceptable drop (see onDropHover callback in Basic Callbacks). The color of the line or highlight will be defined by the dragDropLineColor or dragDropOverlayColor rows in the define table, respectively.

  • Above Row: draw a line above the row being hovered over.
  • Below Row: draw a line below the row being hovered over.
  • Row : draw a highlight over the row being hovered over.
  • Cell: draw a highlight over the cell being hovered over.

Sort/Filter/Select Page

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

This parameter page contains advanced user features for lister.

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

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

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 Rawdata - 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. Useful for testing different kinds of input.

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.

Auto-Create Config On Autocreateconfigon - The operator to attach external config to when auto-created

Auto-Create Config Par Autocreateconfigpar - Name of parameter that holds the Config Comp's target location when auto-created

Config Comp

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

colDefine table

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. Use only letters and numbers, and start with a letter.
  • columnLabel: the header label for the column. "*" uses the column name.
  • sourceData: if sourceDataMode is 'constant', 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, string, or version fetches values via sourceData. The version option sorts using Python's distutils LooseVersion function.
  • 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)
  • 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.
  • 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__.
  • rowNum displays the lister row number. (sourceData is ignored)
  • 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 popup help for the column. * will put the value of the cell in the tooltip, which is useful for long data like paths. * followed by an expression will evaluate that expression and use the result for the popuphelp; in this mode, the keyword object holds the rowObject for the cell and text holds the cell's text.
  • width: pixel width of column (used as minimum for stretch columns)
  • 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

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

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

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)

Note: the Callback<Column name> format uses the column setting from the colDefine table up to the first space.

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.

Callback Gotchas - Drag/Drop and Off Cell Callbacks

In order to receive the drop callbacks below, the On Dropping Into parameter on the Drag/Drop page must not be set to Do Not Allow Drop. In addition, to receive an onDrop callback, you must return True in the previous onDropHover callback. If you do not return True, the behavior defaults to the normal drag/drop system for components and will run the /sys/drop script. This will drop dragged operators into your lister, which is rarely what you want to happen!

In order to receive callbacks for the area in the lister that does not have any cells, the Off Cell Callbacks parameter on the List page must be set to True. The row and column for off cell callbacks is -1.

Basic Callbacks

  • 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. Callbacks will not be recieved if the Drop parameter in the Drag/Drop page is set to Do Not Allow Drops.
  • 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

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

ListerExt Extension Class

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.

SetCellLookName(row, col, lookName)

Set the individual cell look name. Generally, this should be called in the onInitCell (individual cell) or onInitTable (whole table) callbacks
  • row - cell row number
  • col - cell col number
  • lookName - name of look (see textTOPs in config comp). Use None to unset individual cell look (goes back to col look). Use "" to remove column look and unset individual cell look.

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(rowNumber=None, rowData=None, rowObject='__no__object__', rowDict=None, addUndo=TruerowData

Add a row to lister data.
  • rowNumber - where to insert the row. None (default) appends it.
  • rowData - a full row data dictionary including all cols and 'rowObject' key
  • rowObject - a rowObject to be processed by RowObjectToDataRow. Ignored if rowData is provided.
  • rowDict - a dictionary of colName:data to fill row. Missing columns will be blank. None (default) will create a blank row. Ignored if rowObject or rowData is provided.
  • addUndo - if True, add an undo step for this

RowObjectToDataRow(rowObject)Ordered dict formatted for Data list

Convert a rowObject to an OrderedDict keyed by column names. The final item will be the rowObject.
  • rowObject - any valid row object (list, dict, or Python object)

WorkingDataToDataRow(workingData)Ordered dict formatted for Data list

Convert a list of data to an OrderedDict keyed by column names. The final item will be the rowObject. If you don't need to alter the data in the columns, use RowObjectToDataRow instead.
  • workingData - a list of data corresponding to each column of the lister, followed by the original row object.