Latest revision as of 16:06, 26 April 2012

Introduction

This page lists the various files that may comprise a workspace object. Each workspace object must have a unique keyword (unique in the sense that in any given Rave installation, each keyword must be unique). For this reason it is suggested that if you code your own workspace object and intend to distribute it to others, you give it a keyword that is specific enough to almost guarantee uniqueness. Conversely, the workspace objects that are distributed with Rave have very generic keywords. You may find it useful to code your workspace objects as specialized versions of these generic objects, by making copies of their folder and all its files, renaming them to have a new keyword, and making whatever changes are necessary. (Keep in mind that any modifications you make to the existing Rave files can only be distributed under the GPLv2 license.)

The files described below are named for a workspace object whose keyword is KEYWORD. All files related to this object must be placed in a folder named KEYWORD that is placed in one of the six folders below the graphics directory (rave\graphics\). Any time KEYWORD appears in a file name you must replace it with the unique keyword for the object you are coding. Otherwise, the filenames must be exactly as they appear below or Rave will not recognize them. Note that some file names do not include the keyword---Rave recognizes these by their location within the KEYWORD directory.

General File Info

All files must be functions except as indicated. None of the functions should have outputs. Each function must take two inputs. The first (usually called "src") is a handle to a graphics object in the main Rave window. The sole purpose of this input is to retrieve the handles structure. The second input (usually called "ev") is empty and unused, but must appear in the function definition at the top of the file. If you need to make additional functions used by any of the files below, you could include them as subfunctions inside one of the files listed below, or in separate files. Note that the preferred practice is to reserve the main identifying words that appear in the file names below (e.g. create, initialize, tab, etc...) for the files described below. To avoid confusion, other files you create should not include these words in their names.

Workspace Object Categories

Each type of object must fit into one of these six categories (folders):

• discrete - graphics whose primary purpose is to show data from a data set on coordinate axes
• continuous - graphics whose primary purpose is to show data that is generated on the fly by a user-supplied function
• special - everything else. Includes images, maps, etc.
• table - graphics whose primary purpose is to display numerical/text data in a table
• annotation - simple drawn objects such as text boxes, frames, shapes, arrows, etc.
• control - objects that give the user control over other workspace objects

"special" covers anything that doesnt fit neatly into one of the other categories

Each type of object gets its own folder that goes in one of these folders. That folder's name should be the objects's keyword

IMPORTANT: The object folders may optionally start with some numbers whose only purpose is to change the alphabetical order of the folders, and consequently, the order in which the objects are listed in the Create New Workspace Object gui. Be aware that if you change the number in front of an existing graph, you'll get a warning the next time you start MATLAB. Just type "savepath" at the command prompt to remove this warning in the future.

File List

graphinfo.txt (required)

A plain text file. The first line of this file must contain only the (long) name of the workspace object as it will appear when selected in the New Workspace Object gui. The remainder of the file must contain a short (a few lines) description of the object, which also appears in the New Workspace Object gui.

sample.png (optional)

A 400x400 pixel png image that will appear in the "New Workspace Object" gui as a preview. If sample.png is not supplied, no preview image will be shown. For objects that generally require more than 400x400 pixels, this file should show only a portion of the object rather than scaling it down to fit in this size.

graphpropertiesKEYWORD.m (required)

This file is not a function, it is just a list of the lines listed below. Everything to the left of the equals sign should appear exactly as it is written below. The text to the right of the equals sign below tells you the required data type and the options. Note that the words "true" and "false" are matlab functions, not strings. Thus they do not get written in quotes.

All lines should end with a semicolon.

• properties.axesformat= A string indicating the general axes format used by this object. Rave uses this to determine how to resize workspace objects. The string must be either: single, 3D, row, matrix, table, image, custom. If 'custom', you must include a file ravearrangeobjectsKEYWORD.m that does the resizing (See the section for this file below) These mean:
  • single - a single, 2D axes
  • 3D - a single, 3D axes
  • row - a 1*n row of 2D axes (example: histogram)
  • matrix - an m*n array of 2D axes
  • table - a table or anything that resizes like a table
  • image - resizes to maintain the aspect ratio of the image
  • custom - see ravearrangeobjectsKEYWORD.m below
• properties.hascolorbar= true or false, indicating whether or not this graph can ever have a colorbar
• properties.israsterizable= true or false indicating whether this graph is rasterizable (false for things that are already images or are too simple to bother, or that are known to have bugs when rasterizing).
• properties.minheight= an integer value indicating the smallest allowable height for this graph type, in pixels (normal value is 196)
• properties.minwidth= an integer value indicating the smallest allowable width for this graph type, in pixels (normal value is 196)
• properties.hidewhenmoving= true or false indicating whether to hide all lines/paches/etc in this graph when moving or resizing it. Use true for complex graphs that are otherwise sluggish when resizing.
• properties.inset= a 1x4 inset vector [left bottom right top] indicating how many empty pixels to leave between the object's blocker and its axes. (Use to allow for text or other objects that are placed outside of the axes.) Or the string 'custom'. If 'custom', you must also include a raveresizeaxesKEYWORD.m function that resizes the graph to fit within its blocker.
• properties.exploremethods= a cell array of strings, where the strings are the keywords of explore methods that this object can use. If this object has no explore methods, this should be an empty cell array: {};
• properties.updates= a cell array of strings, where the strings are updatetype keywords for raveupdateanalysis or raveupdatedataset. This graph will update whenever either of those functions is called with an updatetype in this list. If this object never needs to update, this shold be an empty cell array: {};
• properties.hasfilter= true or false indicating if workspace object has a mechanism for altering the handles.minfilter and handles.maxfilter values;
• properties.filtertype= if hasfilter=true, this must be 'simple'. Otherwise this is unused.
• properties.deletehandles= a cell array of strings, where each string is the full name of a field in udata (e.g. udata.view.scrollbar) that contains a handle(s) of an object that must be deleted when this graph is deleted. The main axes (handles.axes/fakeax/fakerax) and subaxes (handles.subax/subfakeax/subfakerax) do not need to be listed here, nor do any of their children. Only other axes/uipanels that get created as part of this object should be listed here. If no such axes/uipanels exist, properties.deletehandles does not need to appear in this file (or it may be set equal to an empty cell array)

Example file (graphpropertiesscatter.m)

properties.axesformat='single'; 
properties.hascolorbar=true;
properties.israsterizable=true; 
properties.minheight=196; 
properties.minwidth=196;
properties.hidewhenmoving=false;
properties.inset=[0 0 8 8]; 
properties.exploremethods={'alphashape';'boundaryexplorer';'derivativefield';...
    'oregontrail';'planeprofiler';'point2point';'possiblepaths';'quickmontecarlo';'royalsampler';'singlepointinfo';'spaceshift'};
properties.updates={'visiblerows';'isselected';'xdials';'rowcolors';'preferences';'targets';'addrows';'replaceall';'datachanged';'removerows';'isfiltered'};
properties.hasfilter=false;
properties.filtertype='simple';

raveinitializeKEYWORD.m (required)

This function is called only once for each workspace object you create, after you select it from the Create New Workspace Object gui. This function has two purposes:

1. Create the initial udata structure for this object
2. Call ravecreateKEYWORD.m to actually create the object (this will probably be the last line of this file)

This file should initialize ALL udata fields except those under udata.explore, so that it can serve as an easy reference for the udata field names. In other words, any field that doesn't need to be initialized to a particular value at this point should still be listed here and initialized to an empty matrix.

For information on the fields in udata, see The udata structure.

ravecreateKEYWORD.m (required)

Keep in mind the following points:

• This function never needs to create handles.axes, handles.fakeax, and handles.fakerax. These are created by ravenewgraph.m when a new object is created for the first time. However, if you need to replace these axes with uipanels (e.g. as in the file ravecreatetablesinglepoint.m) you should do that here.
• If your graph requires subaxes, you DO need to create them here, and store them in handles.subax{ai} etc. Like the main axes, all subaxes must come in threes (handles.subaxes, handles.subfakeaxes, handles.subfakeraxes)

viewtabKEYWORD.m (required)

This function runs when the user displays the View tab while this graph is selected. See Coding a View Tab.

formattabKEYWORD.m (required)

This function runs when the user displays the Format tab while this graph is selected. See Coding a Format Tab.

raveresizeaxesKEYWORD.M (required if graphproperties.inset='custom'; otherwise optional)

This function sets the size of the main graph axes (handles.allgraphs) to fit inside the screen space allotted to this object. If graphproperties.inset='custom', this function has to do all the work. If graphproperties.inset= something else, rave will run the default raveresizeaxes for the specified axes type (single, 3d, matrix, image, or row) and THEN will run this function if it exists. You can use this latter option if your graph is almost identical to one of the built-in axes formats and just needs a little tweaking at the end.

ravearrangeobjectsKEYWORD.m (required if graphproperties.axesformat='custom'; otherwise optional)

This function arranges all objects that comprise this workspace object relative to handles.allgraphs. This function is always called immediately after calling raveresizeaxes. If graphproperties.axesformat='custom', this function has to do all the work. If graphproperties.inset= something else, rave will run the default raveresizeaxes for the specified axes type (single, 3d, matrix, image, or row) and THEN will run this function if it exists. You can use this latter option if your graph is almost identical to one of the built-in axes formats and just needs a little tweaking at the end.

raveupdateUPDATETYPEKEYWORD.m (optional)

This filename contains two keywords: UPDATETYPE is one of the updates in raveupdateanalysis or raveupdatedataset. KEYWORD is the graph keyword. Whenever raveupdateanalysis or raveupdatedataset is called with an UPDATETYPE in the list properties.updates (see graphpropertiesKEYWORD.m above), Rave will first check for a corresponding file with this filename. If such a file is found, Rave will run that file. Otherwise Rave will run ravecreateKEYWORD.m

In other words, these functions are used as faster/simpler replacements for ravecreateKEYWORD.m Rather than recreating the object from scratch each time there is an update, these functions can be specialized to make only the minimum required changes to the object needed to reflect the update.

The easiest way to create these functions is begin by simply copying all the code in ravecreateKEYWORD.m and then deleting all the lines that aren't relevant to the update in question.

ravedrawconstraintsKEYWORD.m (optional)

ravesetselectionmodeKEYWORD.m (optional)

If present, this function will run any time you change the selection mode on the row tab or using some other method. This function should check what the new selection mode is, and change the object's hittests and buttondownfcns accordingly to reflect the new selection mode. NOTE: This function takes two inputs, the first is a src handle, the second is the activeindex of the target graph.

pointselectKEYWORD.m (optional)

This is the recommended name for the buttondownfcn that controls point selection, however Rave does not explicitly check for this name and you can name this function something else.

boxselectKEYWORD.m (optional)

This is the recommended name for the buttondownfcn that controls rectangle selection, however Rave does not explicitly check for this name and you can name this function something else.

lassoselectKEYWORD.m (optional)

This is the recommended name for the buttondownfcn that controls lasso selection, however Rave does not explicitly check for this name and you can name this function something else.

ravemakecolorbarKEYWORD.m (optional)

If present, this function is used to draw the colorbar(s) for this graph instead of the default function ravemakedefaultcolorbar.m. The limitations of ravemakedefaultcolorbar.m are:

• Only can be used to draw colorbars based on variables in the data set, for the variable listed in udata.view.c
• The colormap used must be defined by udata.format.mcmap