Lister Custom COMP Examples

From Derivative
Jump to: navigation, search

This page contains examples of how to set up a lister custom component. They assume a basic knowledge of TouchDesigner and Python.

For full documentation of lister, see: Lister Custom COMP.

Example 1 - File Lister[edit]

File Lister

In this example, we will create a very simple lister using only parameters and wires. We will also use a couple of simple Python expressions in associated operators. The end result will be a lister that allows you to choose the file displayed in a movieFileInDAT.

Creating a lister[edit]

To create a lister, drag one from the Palette (Derivative>UI folder) into your network.

Creating an input DAT[edit]

Any table can be used as an input into lister. For this example, we will use a Folder DAT because we are making a list of files. Create a Folder DAT in your network to the left of the lister. Change the DAT's Root Folder parameter expression to app.samplesFolder + '/Map'. It now contains a list of all the sample maps provided in TouchDesigner. Wire the output of the DAT to the input of the lister. Pulse the lister's Refresh parameter (on the Lister page) to ingest the DAT. Open a floating viewer of the lister by right-clicking on its node and selecting "View...".

Ordering and selecting data[edit]

You can sort rows by clicking on the column labels. Note that your original Folder DAT does not change when you do these things. The DAT is only used to create the original data.

To select a row, click on it. You can select multiple rows using shift and ctrl clicks. You can rearrange rows by selecting and dragging them.

Filtering data[edit]

To filter the lister's data, you can enter a string into its Filter String parameter. It will now only display rows that contain that string in the currently filtered column. To select the filter column, click on the column label.

Controlling a movieFileIn TOP using the lister[edit]

In this step, you will create a very simple file selector using the lister. For this example, first turn off a few features. Switch off the following toggle parameters in the lister: Clickable Header, Multiple Row Select, Drag To Reorder Rows. Also, remove any Filter String you have set. The lister data will now stay the same as the original table.

Create a Movie File In TOP in your network. Change the TOP's File parameter expression to

op('folder1')[int(op('lister').par.Selectedrows), 1] if op('lister').par.Selectedrows else .

This little bit of Python selects a cell from the input table that corresponds to the lister's selected row. Select different rows to see this work. NOTE: The if clause at the end takes care of the case where no rows are selected.

Example 2 - Network Lister[edit]

Network Lister

In this example, we will create a lister using Python callbacks and the Column Definition (colDefine) table. The end result will be a lister that allows you to select operators in TouchDesigner's root network.

Creating a lister[edit]

To create a lister, drag one from the Palette (Derivative>UI folder) into your network.

Populating the lister using onGetRawData callback[edit]

Open the lister's callback DAT for editing by clicking its Edit Callbacks parameter. The onGetRawData callback populates the lister's row data. It can handle a number of different kinds of data, but in this case we will be using a list of objects. Specifically, we will populate the raw data with an OP object for each row. Put the following code in the callback DAT:

def onGetRawData(info):
	return op('/').children

This returns a list of the root operator's children. The lister will base each row on an item in the list, in this case a TouchDesigner Operator object. Open a floating viewer of the lister by right-clicking its node and selecting "View...". You will see that the autodefine columns feature has created a column of "objects" with a string representation of each operator in the rows. Our next step is to manually define the columns that we want in our lister.

Editing the Column Definition table[edit]

To open the Column Definition table, click the lister's Edit Column Definitions parameter. In this table, the first column contains labels and the following columns contain formatting information about each of the lister's columns. Change your table to contain this data:

Column Definition (colDefine) table

To see the effects of these changes, switch off the Autodefine Columns parameter in the lister. It is now using the colDefine table you just set up. Let's take a look at some of the features of this table...

The column row contains a unique name for each column. The columnLabel row is the string that will appear above that column in the lister's header. The "*" in the Operator column's columnLabel means to use the column name above. The empty columnLabels in Select and Delete indicate no column label.

The sourceData and sourceDataMode rows define what data will be put in this column. The lister is based on a list of OP objects, so the name in the Operator column indicates that the lister will use each OP's name member, which is a string, as indicated by the sourceDataMode setting. Both Select and Delete have a constant sourceDataMode, so those rows will contain the literal contents of sourceData.

For more details about the various settings in the table, see colDefine table.

Creating special looks in the Config COMP[edit]

The Select and Delete columns illustrate two ways to create special looks in your lister. Notice that the Select column has a bitmap button and the Delete column has a text button with a differentiated color. Try rolling over and clicking on these columns to see more of their looks.

In the colDefine table, these unique cell looks are set in the cellLook and topPath. To see what they refer to, open the Config COMP by clicking the lister's Edit Config COMP parameter. In this COMP you will find many customizable features for lister. Among other things, the colDefine table, callbacks DAT, and TOPs that define cell looks are located here. The button, buttonRoll, and buttonPress TOPs define the button look for the Delete column. The btnImage, btnImageRoll, and btnImagePress TOPs define the image to be displayed in the Select column. You can create as many of these custom cell looks and images as you like, using this naming convention.

For details about the various settings available through the look TOPs, see Config TOPs.

Writing button callbacks[edit]

The functionality for buttons is created using Python callbacks. To set this up, open the lister's callbacks DAT. Create the Select button's click functionality by adding the following text:

def onClickSelect(info):
	op = info['rowData']['rowObject']
	op.current = True

The name onClick followed by the lister's column name defines the callback for clicks on that column. The 'rowData' item in the info dictionary contains a Python Ordered Dict with items for each column followed by a 'rowObject' item which is the original object provided as raw data for the lister. In this case, 'rowObject' contains the Operator for this row. Setting that operator's current member to True selects the operator in the network as if it were clicked on. Open up the root network and click on the Select buttons in the lister to see this effect. Because the clickOnDrag setting is set to on in the colDefine for this column, you can drag the mouse across it with the button down to select different operators as you drag.

For the Delete buttons, enter the following code to illustrate a different approach:

def onClick(info):
	if info['col'] == 2:
		info['ownerComp'].DeleteRows([info['row']])

In addition to the onClick<columnName> callbacks, there is a general onClick callback which is called when any cell is clicked. In order to use this for the Delete button, we must first check that it is in that column by testing info['col']. If our column is 2, we delete the row from the lister by using its DeleteRows method. As you can see, the lister itself is stored in info['ownerComp']. Notice that for the sake of a safe example, the Delete button is set up to delete the row from the lister, not to delete the operator from the network.

For a full list of available lister callbacks, see: Custom Callbacks.

Advanced Callbacks and custom pop-up help[edit]

The last feature to add to the Network Lister is a pop-up help string showing the path to each operator. This needs to be set up in the onInitCell advanced callback. These callbacks are off by default because they are called more often, reducing speed slightly and cluttering the textport when the Print Callbacks parameter is on. Switch on the Do Advanced Callbacks parameter on the lister's Advanced page to activate them. Then add the following code to the callbacks DAT:

def onInitCellOperator(info):
	if info['row'] > 0:
		op = info['rowData']['rowObject']
		attribs = info['attribs']
		attribs.help = op.path

Here we are again using the column callback technique by appending Operator to the onInitCell callback name. The first line of the callback checks that the row number is greater than 0 because header rows also get an onInitCell callback. If we are not in the header row, we alter the cell's attribs.help member to hold the operator's path. For info about the many things that can be set in attribs, see: ListCOMP Class.

Example 3 - Linked Table Lister[edit]

Linked Table Lister

In this example, we will create a lister with a linked table. The end result will be a lister that mirrors changes in a table DAT and can conversely be changed to alter the table DAT. The lister's cells will also be editable and those changes will be reflected in the table. NOTE: If you just want a DAT representation of a lister, but don't need changes from that DAT to be reflected in the lister, simply wire the lister's output to a Null DAT.

Creating a lister[edit]

To create a lister, drag one from the Palette (Derivative>UI folder) into your network.

Creating a linked table[edit]

A lister's linked table will be mirrored in real-time by the lister. Likewise, changes to the lister will be mirrored in the linked table. NOTE: for lister changes to be reflected in the table, it must be a Table DAT so that it is editable.

For this example, create a Table DAT with the following contents:

Linked Table DAT

Next, set the lister's Linked Table DAT parameter to your new DAT. You will immediately see the DAT's contents reflected in the lister. Notice that by sorting the lister or dragging its rows, you can alter the contents of the table. Likewise, editing the contents of the table will change the contents of the lister.

Creating editable lister cells[edit]

The linked table already has nice features, but we want to be able to edit lister cells directly. This setting is in the colDefine table. The autodefined columns are pretty close to correct and recreating them is boring, so we are going to copy those autodefined columns into our custom colDefine. To do this, click the Copy Auto Cols To Config parameter of the lister. Next, turn off the Autodefine Columns parameter to use the custom definitions. Notice that the lister now contains an undesired row (Name/Age), which was previously used as the lister's header. Remove that row from the table DAT.

Now to make the lister cells editable, click the Edit Column Definitions parameter to open up the lister's colDefine table. Change the editable values to "2" for Name and "1" for Age. This makes the columns editable by double-click and single-click, respectively. Try it out. You can now edit the cells directly in the lister and those changes are reflected in the table.

An Operator Family that manipulates text strings: multi-line text or tables. Multi-line text is often a command Script, but can be any multi-line text. Tables are rows and columns of cells, each containing a text string.

The operating system's holder of files and other folders (directories). It does not refer to operators within TouchDesigner. See Network Path.

TouchDesigner is a hierarchy of components. "root" is the top-most network in the hierarchy. The Path is simply /. A typical path is /project1/moviein1.

The connection of an output of one node to the input of another node in a network. In contrast, see Link.

To pulse a parameter is to send it a signal from a CHOP or python or a mouse click that causes a new action to occur immediately. A pulse from a CHOP is typically a 0 to 1 to 0 signal in a channel, and a pulse via python is via a .pulse() call on a pulse-type parameter, such as Reset in a Speed CHOP.

Operators that have 1 or more input, like a Math CHOP, are called filters. See Generator.

An Operator Family 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.

Any of the procedural data operators. OPs do all the work in TouchDesigner. They "cook" and output data to other OPs, which ultimately result in new images, data and audio being generated. See Node.

Any of the procedural data operators. OPs do all the work in TouchDesigner. They "cook" and output data to other OPs, which ultimately result in new images, data and audio being generated. See Node.

An Operator Family that contains its own Network inside. There are twelve 3D Object Component and eight 2D Panel Component types. See also Network Path.

A form of DATs (Data Operators) that is structured as rows and columns of text strings.