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.
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. (Only available when Auto-define Columns is off)
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!
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
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:
color. Only available when Input Table DAT is defined via parameter and Input Table Has Headers is True.
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.
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).
Arrowkeys - Enables moving the row selection using arrow keys. Only available when Selectable Rows is on.
Deletekey - Enables selected row deletion using Delete key. Only available when Selectable Rows is on.
Highlightrollover - When on, rows will be highlighted when rolled over with the mouse. See Config Component inside for highlight colors.
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.
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
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.
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.
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.
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.
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.
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
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. Use only letters and numbers, and start with a letter.
- columnLabel: the header label for the column. "*" uses the column name.
- sourceData: if
sourceDataModeis '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
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
versionfetches values via
versionoption sorts using Python's distutils LooseVersion function.
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)
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
sourceDataas an expression to evaluate, with the row object available as "
object". For example, to get the objects class name, you could set
rowNumdisplays the lister row number. (
- 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. Setting
blankis often helpful when using
- 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
objectholds the rowObject for the cell and
textholds 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
- 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)
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.
- 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
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
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.
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
Noneto unset individual cell look (goes back to col look). Use
""to remove column look and unset individual cell look.
- 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(rowNumber=None, rowData=None, rowObject='__no__object__', rowDict=None, addUndo=True →
- 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
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)
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.