2022 Lister Updates (from Ivan DelSol and Matthew Ragan)

 TouchDesigner’s 2022 Update brought a lot of exciting changes and new features to users. It also has some updates to Lister - one of the components in the palette that often finds its way into quick back office tools and installation interfaces. Ivan and Matthew are back at it again with a run down of lister features, updates, and techniques.

 If you use the lister custom component, you know that there are a whole lot of features packed into it. So many that you might not notice when things are added! This article will familiarize you with the important changes from the last year or so.

 The attached listerUpdateExamples.toe contains examples of most of the items below.

Python f-string formatting

See examples in the “f_strings” component

In order to allow full control of the displayed text in a lister cell, Python f-string formatting has been added to the colDefine table in the “textFormat” column. This allows you to use the full power of Python to reformat data for display. The syntax for these strings is simple: anything inside curly braces is evaluated as Python code, everything else is literal.

Here are some examples:

As you can see in the above, the variable “text” holds the text value of your data. If your data is numeric, you can set the sourceDataMode to float or int and use the variable “val” to work with it:

The f-string also has access to the source data for the row via “rowObject”. To see what is available in that, use the textFormat “{rowObject}” in a stretchy column.

If you start the textFormat string with an asterisk (*), it will ignore any errors in the f-string. If such an error occurs, the data will be displayed in the lister cell unaltered. This is useful when your data is not guaranteed to be free of unexpected items or human error.

For the full details of f-strings, an internet search will bring up many tutorials. Here is a good one: https://realpython.com/python-f-strings/#f-strings-a-new-and-improved-way-to-format-strings-in-python. 

The sourceIndex of rows

See examples in the “sourceIndex” component

Because lister data is often based on static tables while the rows in listers can often be rearranged, a common need has been to find the source data in the original table. This is now available as “sourceIndex” in the rowData object, which is an argument in most callbacks and can also be found via yourLister.Data[<row #>]. So, for example, yourLister.Data[1][‘sourceIndex’] will give you the row index in the source table of your lister’s row number 1. The sourceIndex will remain the same no matter how your lister’s data is sorted or filtered.

There are a couple more ways to access the sourceIndex of your lister rows. To see it displayed in a column, you can set the “sourceDataMode” in your colDefine table to “sourceIndex”. You can also turn on the Source Index In Output parameter to add a sourceIndex column to the lister DAT outputs.

Text look nodes are now textCOMPs instead of textTOPs

In the lister Config Comp, the nodes that hold the various built-in and custom text looks are now textCOMPs. These textCOMPs give a more accurate representation of what your cells will look like than using a textTOPs. You can still use textTOPs for backwards compatibility but this is not recommended. You will notice that the default textCOMPs that come with lister have many parameters set to read-only. The parameters that are not read-only are the only ones that have an effect on the lister looks. If you make custom cell looks, it is recommended (but not required) that you copy one of these textCOMPs to start with.

Justify, bold, and italic can now be set in the look textCOMPs

See examples in the “justify_bold_italic” component

In older versions of lister, you could only set text justification, bold, and italic in the colDefine table’s justify, fontBold, and fontItalic rows. You now have the option to set those items in the textCOMP looks by leaving the colDefine cells blank. 

The Sort/Filter/Select parameter page

This parameter page has some useful features worth understanding when your lister uses sorting, filtering, and selection. The first section in the par page (Sort Columns, Sort Reverse, Filter Columns, Filter String, and Selected Rows) generally describe the current status of the lister. For example, when you select a row, the lister itself will set the Selected Rows parameter, but you can also set it yourself if you want to set which rows are selected. The odd man out here is the Filter String. You have to set that string yourself, usually by binding a Text COMP’s text parameter. When there is a string in this parameter and a filter column is selected, only rows with that string in the filter column will be displayed.

The Selected Output parameter defines what data is in the rows of lister’s second output, which shows only the rows currently selected. You can choose between displaying the data in the lister row, or data from the input table row from which the lister row was derived.

The next section contains “save” options. When on, these options save Sort, Filter, and Selection data with the file. This means when you restart your TouchDesigner file (or cut and paste the lister) the relevant parameters will keep their data.

Finally, the sort characters, when on, are displayed in the column headers when they are sorted to indicate whether and in which direction they are being sorted.

Changes to treeLister

See examples in the “treeListerIcons” component

The lister component’s cousin treeLister has leveraged some of these changes as well. Specifically, the “expando” (the icon showing whether nested branches are visible or not) is now defined in treeLister’s colDefine table in the textFormat row of the Expando column: 

This expression says that when the expando value is “1”, open, the icon displayed is chr(0xf0140), otherwise the icon will be chr(0xf0142). You can change these values to display different icons. The default font for these is Material Design Icons, and this can be changed in the expando look textCOMPs.

In addition, the “Click Corner To Refresh” icon (visible when that parameter is toggled on), is defined in the treeListerConfig/define table in the refreshChar row. This character always uses Material Design Icons.

Dictionary Style Lookups for Multiple Icons

See examples in the “iconLookups” component

Lister’s support of f-strings also opens up a variety of different approaches for changing list icons. For example, let’s say we had three different types of icons we might want to display based on the text inside of a cell. An expression like:

Only supports two different possibilities. We could instead use the .get() function for python dictionaries to fetch a wider range of possible outcomes. We might be more familiar with this format if we look at it on several lines first.

Because f-strings evaluate the contents of curly branches, we can instead wrap our entire dictionary and the get function inside of our curly braces as a single line: 

While it may look a little less elegant, it opens up a wide range of opportunities for how we might match the contents of tables to corresponding icons with lister. This can also be achieved through a table lookup, which is shown in the example file.