Coding Workspace Objects with Java Components

From Rave Documentation
Jump to: navigation, search

Coding workspace objects that use java components is complicated by the fact that java objects cannot be saved in a .rve project file. Because of this limitation, you need to follow certain rules to make sure that ravesavestate can correctly save a .rve project file, and that raveloadstate can load .rve files that use your object.

The rules

  • Any workspace object that uses java objects MUST have the string 'unsaveable' in its udata.attributes cell array. (Set this in raveinitializeudataWORKSPACEOBJECT.m).
  • Java objects cannot be saved in the .rve project file, so ravesavestate deletes them first, then raveloadstate recreates them by calling ravecreateWORKSPACEOBJECT. Because of this:
    • Your ravecreateWORKSPACEOBJECT.m function must be able to recreate the java objects from just the information stored in udata. For example, if you have a java-based text box in which the user can enter text, this text must be stored in udata in addition to being stored in the java text box itself.
    • Your ravecreateWORKSPACEOBJECT.m function must not give errors if the java objects have been deleted (since they WILL be deleted by ravesavestate). If your workspace object creates the java object only once during raveinitializeWORKSPACEOBJECT, then ravecreateWORKSPACEOBJECT must have a check that if the java objects do not exist, it recreates them in the same way they initially get created by raveinitializeWORKSPACEOBJECT.
    • Similarly, if you recreate your java objects each time ravecreateWORKSPACEOBJECT.m is called, you probably delete them at the beginning of that function. Make sure you properly code this so it doesnt give an error if they've already been deleted.
  • Java objects that appear on screen (e.g., swing objects) MUST be children of either handles.fig, handles.wspanel, or a uipanel whose handle is stored in handles.allgraphs, handles.fakeax, or handles.fakerax. These are the only places that ravesavestate will look for java objects to be deleted.
  • You MUST include a property in your graphpropertiesWORKSPACEOBJECT.m file named "unsaveablehandles". This is a cell array of strings that are the field names in udata (including the "udata." part) where java objects have been stored. All non-graphical java objects must ONLY be stored in a udata field that appears in this list (i.e. do not store them in handles, only store them in udata, and then include the place that you store them in this list.) Any stored handles to graphical java objects that you placed using javacomponent may ONLY be stored in udata in a field that appears in this list.
  • Do NOT directly replace handles.allgraphs, handles.fakeax, or handles.fakerax with a java object. Instead, replace (one of) them with a uipanel, and put your java object(s) in that panel.

In short: ravesavestate needs to be able to remove all of your java objects from the .rve file it saves. It only looks for graphical java objects in the list of children of handles.fig, handles.wspanel, and (if they are uipanels) handles.allgraphs, handles.fakeax, and handles.fakerax. If you have created your graphical java objects using the javacomponent function, which generates a regular hg handle for the java object, ravesavestate must also remove all references to that handle from the .rve file. Otherwise it will generate an invalid handle error later. Rave only looks for these handles in the list of udata fields you specify in graphproperties.unsaveablehandles. Note that you do not actually store the handle itself in unsaveable handles; rather unsaveable handles is a cell array of strings, in which each string says where you have stored the handle. For example, a string might be 'udata.view.jScrollPane'. Ravesavestate then simply sets all of these fields to [].