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.
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.
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 and 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 make it clear that this row is an “index” or “identifier” for the remainder of the row. Using the
and 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
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
tab, 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 tab 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 , 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
), as well as some of the values in the Inspector for the jit.cellblock
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 print
ed into the Max window for us). Since you may want the program to control the current selection, the jit.cellblock
object will also respond to a message, with arguments that choose the column and row to select. 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 .
The current selection can be referred to as “current” in certain messages. So, the next number
box is routed through a 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 window 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 will force cell to contain the text . Of course, we also have to be able to remove data, which is the function of the message. The next message
box generates the message, which will erase the text that we just set.
box uses the syntax for setting contents in the object. The two integers following the 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
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 attribute to will prevent the values from being changed. When this is set, you can use the jit.cellblock
without worrying about the values being changed.
In order to be as flexible as possible, jit.cellblock
has several selection and output modes. The selection mode (set with the attribute) defaults to selecting a single cell (known as “one cell select” mode). If we look at the left umenu
of section 3
, we will see that there are six different options for cell selection.
The first option (option jit.cellblock
object to act like a large set of labels. Option , “single cell select”, is the default selection handler, where only one cell can be selected at a time. The next two options ( and ) all you to select a large number of cells with a single click. Option (“column select”) will select all cells in any column that you select. Option (“row select”) does the same for row values.
, “no selection) prevents any cell selection. This can be useful if you want the
The fifth option (option
, “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 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 and messages, although it cannot be controlled with your patch.
, “in-place edit”) provides an easy way to enter data into the
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 attribute. Mode , 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 , or “output as one list”, will combine all non-blank cell values into a single list, and output it in a single message. Mode , 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 to . 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 window 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 window 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 window seem no different. However, if you look at the output of the zl
object (covered in depth in another tutorial) connected to the jit.cellblock
object's outlet, you will see that our message only has elements, rather than the elements we saw in the previous mode.
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.
Two-dimensional storage and viewing