Community Post

The Big Bad Lister | Part 1/3

This post is going to be a little different than usual - normally Matthew does most of the writing for these posts, and then we cross post them on a few sites. This one is a different in part because we’ll be looking at something from the TouchDesigner pallet in depth, and also because Ivan from Derivative has very graciously volunteered to help demystify one of the coolest components that you’re not using enough in your projects - Lister. 

There’s a few things to keep in mind as you read through this post - there are two authors: Matthew and Ivan. They talked through what pieces would be great to share about lister, and then split up the examples and writing - that means that you’ll notice a slightly different voice in the writing, and you’ll get to see two different perspectives on how lister works. It’s also worth noting that Ivan is the developer at Derivative who has spent the most time working on lister, and the person who knows the Dark Dank Secrets of this component. There are also a handful of examples that go with everything written here, and we’re hoping that this post helps you find new and exciting ways to use lister in your projects!

Lister Basics

What’s a lister anyways? ! Lister is a shared component that both lives in the palette browser as its own comp, and is deeply integrated into the latest widgets UI kit Derivative has been cooking up. You can find both of these in the Palette browser on the on left hand side of the TouchDesigner UI, or by pulling up the palette browser with ctrl + l (win) / cmd + l (mac).

Lister is actually built on top of the List COMP. The List COMP is a wildly powerful component, and replaces some of the pieces that you used to do with the Table COMP. If you haven’t used the Table COMP before, it’s amazing… but gets a little unwieldy pretty quickly. The Table COMP can be used to make radio buttons or other list style interfaces (the op create dialogue is a good example of the Table COMP in action), but it’s all set up with Table DATs, and can be a little hard to read / understand.

The List COMP does many the same things, but unlike the Table COMP, the List COMP has a deep set of python integrations with an internal callback DAT that allows you to think about UI building and operation from a Pythonic perspective rather than with Table DATs. That’s very exciting, but to make a truly reusable and extensible UI component you have to write a lot of Python… and this is where Lister comes into play. Lister is built on top of the List COMP and solves a large number of challenges you might typically encounter. It still has all the raw power of the List COMP, but gives you a huge headstart over trying to create a list UI element from the ground up.

So what can you do with Lister? Anything you might use a list for!

With that said, let’s actually look at how we can get started with lister, and some of the ways we can start to style and configure a lister for use in your projects.


When it comes to working with lister, the config COMP is where you’ll actually find all of the most important secrets. The config COMP is docked below lister, and has a few easy to access helpers. On lister you’ll find a handful of pulse open parameters that will make configuration easier to set-up. 

Before we can really dig-in let’s set-up our workspace so we can see some of the interesting pieces of lister in action. To begin we’ll start with a Table DAT that holds a set of rows and columns that we want to turn into a UI element. 

We can start by creating a Table DAT that has two columns and a few rows. I’m going to give mine 6 rows, and name the columns “col1” and “col2”.

Let’s also add a lister from the palette - in this case we want the lister that’s in the UI Folder.

To see just how fast lister can be to use, let’s start by just connecting our table DAT to our lister COMP:

Right away we’ve already got a table up and running. This is a nice start, but we can do a little more to better configure our lister UI element. Some of the most important configuration pieces can be found in the docked base called “listerConfig”:

The listerConfig Base holds the sweet secrets for our lister - let’s take a closer look at how we might set a few configuration elements. Before we dive inside of the config, let’s first set a few of the parameters on lister.

On lister let’s first turn off the Auto-define Columns parameter:

Let’s also change the parameter “Input Table Has Headers” to True - since our input table has headers:

Like it’s parameter name sake, Auto-define columns will attempt to set-up your lister based on the input table. For this example, we’re going to turn off that parameter, and then click on the “Edit Column Definitions” pulse parameter. This will open a floating window of the colDefine table DAT inside of the listerConfig:

This table contains many of the configuration elements for our lister’s look. We can see that the table already has some elements set up. We’re going to replace these with our own values so we can see how lister will change. 

First let’s set the column name to be displayed as our header. Our starting table contains fruits in col1 and their quantities in col2 - So I want to change the column Row to be “Fruit” and “Quantity” respectively. 

Our lister’s data structure supports an internal column name that’s different from the display label - in some advanced cases you may want to use this. For now, let’s just set the columnLabel row to have a value of “*” which we can read as - “use the value from the column row.” 

Next let’s change the sourceData row to be the name of the input table’s columns that we’d like to use. My input table had columns called “col1” and “col2” - what’s important to consider here is that our lister’s columns don’t have to be arranged in the same order as our input table. This can be very helpful for more complex list UI elements. 

Let’s set our sourceDataMode to be “string” for both of our columns.

For now let’s style the width and stretch parameters for the column to be the same. Each column can have a width value of 100, and a stretch value of 0. At this point you should have a config table that looks something like this:

Your lister should look something like this:

Before we experiment with styling our lister anymore, let’s quickly take a look at some of the handy features that already exist. For starters we can see that there’s a hover highlight from our mouse position, and when we click on a row it highlights another color.

Lister also has two DAT outputs. The first lister DAT output is a table DAT version of exactly what’s in lister. The second output is the header columns from our lister, along with the selected row or rows from our lister:

Let’s next look at how we might style our lister’s output a little more. 

In addition to the column definitions table, there are a host of additional operators we can change inside of our listerConfig DAT that are worth playing with. Let’s head back to our lister’s parameters, and this time click on the pulse parameter called “Edit Config COMP”.

This will open a floating network window that looks into the listerConfig base:

In addition to the column definitions table that we’ve been working with, there’s also a whole cluster of other TOPs. The first two columns of TOPs hold text TOPs that are used to define how our lister is styled. 

By changing these TOPs we in turn change the style for the lister’s columns. Let’s take a quick look at what we might change and the impact that will have on our lister. 

Let’s start on the text TOP called “header” on the font page. We can see that a number of the parameters are set to read-only - but there are a few on this page of parameters that we can change. Let’s start by turning the font x size up to 12 and turning on the “Bold” parameter.

Next let’s move to the Color page, and change the background color for our header. Here I’m going to make the Font Color bright white, change teh background color to a plumb, and set the bottom border of my TOP to be Border A. You’ll want to make sure that you also set the Border A Alpha parameter to 1 - it’s set to 0 by default. The result should look something like this:

Next if we look at our lister we’ll see those changes in action:

This same idea also works with our rows - we just have to edit the first column of TOPs in our liserConfig base. I’m going to change my TOPs so that my lister uses this plumb / purple color palette. The only changes I have to make will be to the first column of TOPs:

The resulting look for the whole lister is something like this:

If you wanted to also change the row heights, you can achieve that change by adjusting the header TOP’s vertical resolution, and the master TOP’s vertical resolution. I’m going to change the header TOP’s resolution to 36, and the master TOP’s to 30. I’m also going to turn on row Striping on the lister COMP. The resulting changes look like this:

This is just a start of the kind of customization we can achieve with lister. Now that we have a handle on some of the essential elements for manipulating the look of our lister, let’s take a deeper dive into customization and other lister features.


Auto Config and Copy Auto-Cols

For a simple input table this is a pretty straightforward approach, but sometimes we end up with a table that’s slightly more complicated. A good example of this might be when we’re converting SOP data to a table - this can be helpful in all sorts of situations, but setting up our lister for this many columns could take a  minute. Let’s set up a quick table that holds data converted from a sphere SOP.

We can start with a sphere SOP and change its primitive type to Polygon (this will start us off with fewer rows). Let’s add a null SOP (in case we want to add any other transformations), and then use a SOP to DAT to convert this in a table format.

Similar to Houdnini’s geometry spreadsheet, this table holds all sorts of useful information about our SOP. This often works great for internal project uses, but if we want to create a styled interface for this data we would have to think about how to display this information.

A lister here can be a great help. Let’s add a new lister form the palette to get started. Next we can connect our DAT to lister.

Lister starts with the “Auto Define Cols” parameter on, which helps us get a starting point from our data right away. If, however, we want to style our lister a little more we’d need to repeat the steps we practiced earlier - going though and creating a column in our colDefine table for each column that we want to display. That’s all well and good, but it’d be oh so nice if there was a way to copy the current auto-config format into our colDefine table to give us a headstart. This gives us an opportunity to look at one of the handiest parameters on lister - Copy Auto-Cols to Config. 

For a table with this many columns it might be a little cumbersome to go through and set all of the colDeinfe elements manually - which makes this parameter incredibly helpful. So let’s go through an setup this lister so we can see the “Copy auto Cols To Config” in action. First, I want to turn on the parameter “Input Table Has Headers.” This SOP to DAT has header information already, and I want to make sure that the first row is treated as a header.

Now we can use the pulse parameter called “Copy Auto Cols to Config.” A good trick to keep in mind here is that pulsing the “Recreate Auto-columns” parameter will adjust column widths to their contents when you press it. This would be helpful when you’re looking to have your columns auto size themselves. 

For this example we’re going to make some changes to our columns after we’ve captured them in the colDefine table. Let’s pulse the “Copy Auto Cols to Config” parameter. After we pulse this parameter, let’s turn off the “Auto-define Columns” parameter so we can make some changes to our lister.

Now let’s use the pulse parameter on lister to open our Edit Column Definitions table. We should see that lister has done all of the hard work of setting up our column definitions table, and now we can focus on just modifying the contents of this table.

Now that we have the initial work done let’s go through and make some edits to our definitions. For starters, we might consider changing the labels for our columns. The names that come from our SOP to DAT are great when working in TouchDesigner, but aren’t always as descriptive as we might like for a user interface. We can update what’s displayed in the headers by making some changes to the first row of our colDefine DAT. I’m going to change a few names:

  • Index -> Point Index

  • P(0) -> Point.x

  • P(1) -> Point.y

  • P(2 -> Point.z

  • N(0) -> Normal.x

  • N(1) -> Normal.y

  • N(2) -> Normal.z


I’m also going to remove the point weight column, and the groups column. I also want the columns to stretch to fill the lister’s width, so let’s change the stretch row to be 1 for each of the columns. I want the Point Index values to be center justified instead of left justified, so we can change the justify cell in column 1 to be CENTER. Finally, I want the text in the first column to be Bold, so let’s change the fontBold cell to be 1. The resulting table should look like this:

While we’re here practice using the font TOPs inside of the listerConfig COMP to style your lister. I’m going to adjust my row heights, and add a little color. After a few adjustments, my listerConfig looks like this:

And the final lister looks like this:

In our next installment we’re going to look at additional mechanics for working with tables, creating buttons in lister, using simple callback functions, and deeper styling with TOP paths. 

You can download all of the examples from this post here.

Happy programming… and lister-ing.