Review of MATLAB Syntax

Introduction

Before attempting to code a MATLAB plugin, you should be VERY familiar with the 4 basic MATLAB data types: numerical arrays, strings, cell arrays, and structures. If you are coding a workspace object, you should also be VERY familiar with graphics object handles, properties, and the set/get command. You should also understand how to create fast graphics (i.e. ones that will render quickly). The sections below briefly summarize some of these points, but they are not a substitute for real experience.

guidata and the handles structure

Almost all data tracked by rave that is NOT particular to one graph is stored in a variable named “handles”. Unfortunately this is the same name as the concept of the handle of a graphics object, but it is also the default name MATLAB uses for this variable and I didn’t change it. (For consistency, you shouldn’t either). handles is a structure, which you can think of as a folder that holds other variables (many of which are themselves also structures). The handles structure is special in that it is stored and retrieved using the “guidata” function, which allows it to easily be shared by all functions in rave. (A better way to say this is that there is a single special variable that can be stored/retrieved using the guidata function, and in this case that variable is a structure which we will always name “handles”.)

There is always only ONE guidata variable that is shared by EVERY object/callback of a single figure (i.e. window) This variable is retrieved using the syntax handles=guidata(src); where “src” is the handle of any object in the figure. Regardless of what the “src” handle is, you will always get the same handles structure as you’d get using any other “src” in the same figure. IMPORTANTLY, this means that handles is only shared among callbacks that originate from the main rave window. Callbacks from popup windows will have their own guidata, and must access the main handles structure using another method (described elsewhere).

Any time you make changes to the handles structure, you must also store the updated results, also done using the guidata function, but with the syntax guidata(src,handles); (note in either case, src is always the first input to guidata.) Again, it does not matter what “src” is – this function call sets the guidata for EVERY object in the figure.

What are the implications of all this? Simply that most functions in rave do not have inputs and outputs in the traditional sense. Instead, each function takes a handle (src) as an input, then uses handles=guidata(src) to retrieve ALL your data. Then the function modifies handles as necessary, and stores the results using guidata(src,handles).

Consequently, handles=guidata(src) is the first line of almost every function in rave. And guidata(src,handles) is the last line of almost every function (the exception being those functions that don’t actually change handles.

Structures and Cell Arrays

In MATLAB, a structure contains “fields,” each of which can be thought of as a new variable. Fields are accessed by typing the name of the structure, a period, then the name of the field. For example, the statement handles.index=5 creates a field named “index” in the structure “handles” and gives this field the value 5. Since 5 is a number, handles.index is effectively a double precision array with dimension 1x1. Depending on what is to the right of the equals sign, handles.index could also have been made into a string, cell array, or other class of numeric array. If you want handles.index to itself be a structure, just append another period and field name. For example, handles.index.data=10.

Now, if handles.index is an array, you can directly reference into it using parentheses. For example, handles.index=[2 4 6 8], then handles.index(3) will return “6”. Similarly, if handles.index is a cell array, you can reference into it using braces.

As with any cell array in MATLAB, a structure field that is a cell array can contain other (nested) cell arrays. You can index into nested cell arrays by simply appending more and more curly braces, and (if necessary) a final reference into a numerical array in parentheses. (You can ALWAYS only have 1 parenthetical reference and it must be the last reference).

For example, the line mycolumn=handles.alldata{1}{3}(:,5); Tells you that handles.alldata is a cell array that contains at least 1 entry, which must also be a cell array (since the next reference is also to a cell) that in turn contains at least 3 elements. The 3rd element of THAT cell array must be a numerical matrix, since the next reference is in parentheses (instead of braces) , and it must contain at least 5 columns, since the index references the 5th column. Thus, mycolumn is the 5th column of the 3rd cell of the 1st cell of handles.alldata. If all of that made sense to you, you’ll do just fine. If instead you said “huh?” you should probably read the MATLAB help files for structures and cell arrays and practice using them before you try coding for rave. Note there are also more complex references possible where the fields themselves have dimensions, things like handles.alldata(5).names{3}, but rave (I think) never uses these.