Data Tutorial 4: Cellblock

Introduction

This tutorial focuses on the jit.cellblock object (commonly referred to as “cellblock”). The jit.cellblock object provides a visual interface to a 2-dimensional matrix of data, where each data point (or “cell”) can contain any of the data types used in Max. This data can be changed and edited, and selected either by the user or by the patch.

The jit.cellblock object fills a special need in Max – an space-efficient display of Max values, with the ability to select or edit them visually within the patch. This object, like the lcd object, supports a very large number of messages and attribute settings; in this tutorial, we will cover some of the most useful ones, but there are many more options available for advanced use.

To open the tutorial patch, click on the Open Tutorial button in the upper right-hand corner of the documentation window.

Structural messages and setup

Take a look at the patcher for this tutorial. You will see a grid-based display, along with three sets of message boxes. The grid in the middle of the patcher (which resembles a spreadsheet) is the jit.cellblock object; it provides a two-dimensional display of data stored in an internal structure.

Many of the structural settings of the jit.cellblock are available for programmatic control. For example, there are two number boxes connected to rows and cols messages. These number boxes can be used to manually change the number of rows and columns stored in the jit.cellblock. If you add more rows or columns than can be displayed in the available area, scrollbars will automatically appear.

Another type of structure can be implied by changing the color of the first column or row with the object. When this is done, it makes it clear that this row is an “index” or “identifier” for the remainder of the row. Using the rowhead and colhead messages, you can change the perceived use of this first value. It’s important to note that, while there is a visual change to the header area, there is no change in your use of the data, or your ability to add or change it.

There are other visual attributes that can be changed that have no effect on the underlying data. An example is the grid attribute. When the grid is on, we get a familiar spreadsheet-like display of the data. When it is off, however, the display of the values is not delineated by the drawn grid; this is especially handy if you want a less distinct grid layout that uses either text or background colors to distinguish data subsets.

There are more structural settings available for manipulation, and opening the object inspector gives access to most of them. If we open the object inspector for the jit.cellblock object in the tutorial patch and select the Structure section, we see attribute settings that match the patch-based messages we just used. Additionally, there are settings for the default column and row sizes: the width and height of these elements if they are not specifically set. If you adjust these settings, you will see the cells in the jit.cellblock dynamically change to match.

Other visual settings are available under the appearance section of the inspector. The colors of the various jit.cellblock elements can be set using the color picker; click on the color that you want to alter, and a standard color selector will be displayed. Select the Default Background Color, and change the color to a bright red. You will notice that the background of all of the cells will be changed, but the other elements (like the color of the grid, or the currently selected cell) remain unchanged.

Familiarize yourself with the different settings on the left side of the patcher (labeled 1.Structure and Appearance), as well as some of the values in the Inspector for the jit.cellblock object.

Storing and retrieving values

Beyond setting up the structure of the jit.cellblock object, we will need to select cells, store data in them, and retrieve the data again. First, let’s look at choosing a cell. The easiest way to select a cell is to click on it – much like you would with a spreadsheet. You will notice that selecting a new cell outputs the coordinates (in column/row order) from the left outlet of the object (this is printed into the Max Console for us). Since you may want the program to control the current selection, the jit.cellblock object will also respond to a select message, with arguments that choose the column and row to select. You will find this in the section labeled 2.Contents. Using the two number boxes attached to the select message, you will be able to control the current selection of the jit.cellblock. Notice that both the row and column number is zero-based, meaning that the first row and first column is selected by sending the message select 0 0.

The currently selected cell(s) can be referred to as “current” in certain messages. So, the next number box is routed through a set current message; this will take the incoming value and change the current cell’s value to this integer. Test this out by selecting several different cells and changing the value. Now click on any cell with a value: you will see that the output of the object has changed, with the Max Console displaying not only the column and row numbers, but also the data that is in the cell.

You don’t have to select a cell to change the data it contains. The next message box uses the set x y value... syntax for setting contents in the object. The two integers following the set message represent the column and row that will be changed. All data following these coordinates will be stored. If the data is an integer or floating-point number, that single entry will be stored. Symbols and lists can also be stored as values for a cell. Clicking on the third message box will force cell 2 2 to contain the text Here I am!. Of course, we also have to be able to remove data, which is the function of the clear message. The next message box generates the clear 2 2 message, which will erase the text that we just set.

The jit.cellblock object is useful partly because it provides a large set of user options for selecting and manipulating data in a cell. Of course, if we’ve gone through the trouble of setting the values of the cells, we wouldn’t want the user (or the program, for that matter) to change these values. Setting the readonly attribute to 1 will prevent the values from being changed. When this is set, you can use the jit.cellblock without worrying about the values being changed.

Selection and output options

In order to be as flexible as possible, jit.cellblock has several selection and output modes. The selection mode (set with the selmode attribute) defaults to selecting a single cell (known as “one cell select” mode). If we look at the left umenu of section 3. Selection and Output, we will see that there are six different options for cell selection.

The first option (option 0, “no selection") prevents any cell selection. This can be useful if you want the jit.cellblock object to act like a large set of labels. Option 1, “single cell select”, is the default selection handler, where only one cell can be selected at a time. The next two options (2 and 3) all you to select a large number of cells with a single click. Option 2 (“column select”) will select all cells in any column that you select. Option 3 (“row select”) does the same for row values.

The fifth option (option 4, “header select”) is more involved. If you have column or row headers turned on, and if you click on a header cell, the entire column or row will be selected. Otherwise, only a single cell will be selected. This is very similar to the way a spreadsheet works, where the headers have special selection rules that are different from standard cells.

The last option (option 5, “in-place edit”) provides an easy way to enter data into the jit.cellblock. Double-clicking on any cell will allow you to edit or add information into the selected cell. This may be more convenient than using select and set messages, although it cannot be controlled with your patch.

Since several of these modes will select multiple cells, it begs the question “What format will the data be in?” The jit.cellblock object provides three output modes as an answer - these are set with the outmode attribute. Mode 0, or “individual output” mode, will send each selected cell in its own message, and will output a message for cells that may not have any data value. Mode 1, or “output as one list”, will combine all non-blank cell values into a single list, and output it in a single message. Mode 2, or “output as one symbol”, will combine all of the non-blank cell values into a list, then turn the list into a single text symbol. This is most useful if you have filled your jit.cellblock with textual values, and want to combine them into larger phrases.

To see the output mode in action, click on the button attached to the loader subpatcher. This will format and load the jit.cellblock object with numbers from 0 to 99. The jit.cellblock is also flipped into “row select” mode, so we will be selecting many cells with each click. Click on a cell to select a row; you will notice that 10 messages appear in the Max Console sequentially, one for each cell that is selected. Now, change the output mode to “output as one list”, and click on the sixth row. The Max Console now shows a single line result, meaning that only one message was produced. The first two numbers are the column (irrelevant, in this case) and row (5, since jit.cellblock is zero-based), then a list of all the values in that row.

If we change the output mode to “output as one symbol”, the results in the Max Console seem no different. However, if you look at the output of the zl len object (covered in depth in another tutorial) connected to the jit.cellblock object's outlet, you will see that our message only has 3 elements, rather than the 12 elements we saw in the previous mode.

Summary

The jit.cellblock object is a robust tool for dealing with 2D data of any type, and for the presentation of data in a grid-like format. We have only touched on a few of the most useful commands; for more information, review the help files and reference documentation on this object.