xfigure (class for UI object handling)

When I started writing Matlab code for handling UI events (using Matlab R11), I noticed that certain tasks were not at all easy to accomplish and that using the built-in figure editor was a bit cumbersome (for me, at least). I thus decided to come up with a set of functions that would manipulate Matlab's handle graphics objects (particularly figures and uicontrols), which ended up becoming a class implementation, xfigure.

Major features include:

• figure definitions (type, position and extended properties of controls and menus) can be stored in human-readable text files (see tfgparse for more information), supporting relative positioning of uicontrols to the previous control (making it easier to extend a figure)
• properties can be read out and written to using the struct notation (see @xfigure/subsref and @xfigure/subsasgn)
• groups of uicontrols and uimenus can be set enabled/disabled and visible/hidden with one single call (see xfigure.SetGroupEnabled and xfigure.SetGroupVisible methods)
• groups of uicontrols can be moved with one single call (see xfigure.SlideGroupXY method)
• uicontrols can be put on “pages” of figures, which can be selected (visibility) easily (see xfigure.ShowPage method)
• groups of uicontrols with Style = 'radiobutton' can be grouped into a RadioGroup (see xfigure.RadioGroupSetOne method)
• content of fields (edit fields, checkboxes, etc.) can be “linked” to an xini file/object, allowing to automatize retaining settings across uses of a dialog window
• multi-string uicontrols (listbox) have extended syntax available (e.g. to splice the content, move the selected portion, etc.)

  xfigure (Object class)
 
  This class handles MATLAB's UI related stuff with an OO interface.
  Returned
  objects can have a subtype of either
 
   -> ROOT            (the factory itself, corresponds to MATLAB handle 0)
   -> Figure          (MATLAB figure objects)
   -> UIControl       (MATLAB uicontrols objects)
   -> UIMenu          (MATLAB uimenu objects)
   -> UIContextMenu   (MATLAB uicontextmenu objects)
 
  The following constructors are available:
 
  xfigure
  xfigure(matlabhandle [, 'delete'])
  xfigure(objecttype, xfighandle)
  xfigure(filename [, options])
  xfigure(objecttag)
 
  For better object access, the struct notation
 
  uiobject.Property
 
  is implemented for both reading/writing.
 
  Note: due to a MATLAB restriction of a maximum length for variable
        names (31 characters), Tags longer than 27 won't work.

Just as with the xff class, fields of Matlab handles (e.g. the Value property of a uicontrol with style = 'checkbox') can be read out and written to using the struct notation (reducing the number of parantheses in the code):

xfigure_struct_overload.m

% original way to invert the state of a checkbox:
set(checkbox, 'Value', 1 - double(get(checkbox, 'Value') > 0));
 
% xfigure way
checkbox.Value = 1 - double(checkbox.Value > 0);

There are a few important differences to be aware of when working with xfigure objects. First of all, there are the five different major sub-types of objects:

• sub-type ROOT object (which represents handle 0, is unique and can not be deleted/created but just referenced)
• sub-type figure objects (which represent handles of Type = 'figure')
• sub-type uicontrol objects (which represent handles of Type = 'uicontrol', and in some instances 'axes')
• sub-type uimenu objects (which represent handles of Type = 'uimenu') and
• sub-type uicontextmenu objects (which represent handles of Type = 'uicontextmenu', rarely used)

A reference to the (unique, singleton) ROOT object can be created by calling xfigure without arguments (comparable to the xff class):

xfigure_rootref.m

% get a reference to the xfigure ROOT object
xfig = xfigure;

With that object, one important method, DeleteAllFigures, is available, which is accessible via the struct (subsref) notation:

xfigure_root_daf.m

% delete all figures, also hidden figures, etc.
xfig.DeleteAllFigures;

And naturally, ROOT properties (such as ScreenSize) can be read out and, if applicable, set via the struct notation.

First of all, a figure object can be created by passing a valid TFG filename (see tfgparse for more information) as argument to the ROOT object:

xfigure_createfigfromfile.m

% create the figure of the tdclient UI
tdclient_ui = xfigure([neuroelf_path '/_core/tfg/tdclient.tfg']);

And figure properties can then be set (and read out) via the struct notation:

xfigure_setfigvisible.m

% set Position of tdclient
tdclient_ui.Position(1:2) = [200, 400];

Additionally, the following methods are available for sub-type figure objects:

xfigure_figuremethods.m

% en-/disabling a group of uicontrols
tdclient_ui.SetGroupEnabled('NoLabel', 'off');
 
% hide a group of controls (as an example, the figure lacks the group!)
tdclient_ui.SetGroupVisible('Output', 'off');
 
% setting the first of a group of radio buttons to be selected
tdclient_ui.RadioGroupSetOne('SType', 1);
 
% "slide" a group of controls to a different position (X: -40, Y: +120)
tdclient_ui.SlideGroupXY('Inputs', [-40, 120]);
 
% delete (close) the figure
tdclient_ui.Delete;