====== xfigure (class for UI object handling) ======

===== Motivation =====
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|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.)

===== Reference ('help xfigure') =====
<file>  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.</file>

===== subsref overloading =====
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):

<code matlab 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);</code>

===== Object sub-types =====
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)

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

<code matlab xfigure_rootref.m>% get a reference to the xfigure ROOT object
xfig = xfigure;</code>

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

<code matlab xfigure_root_daf.m>% delete all figures, also hidden figures, etc.
xfig.DeleteAllFigures;</code>

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

==== figure objects ====
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:

<code matlab xfigure_createfigfromfile.m>% create the figure of the tdclient UI
tdclient_ui = xfigure([neuroelf_path '/_core/tfg/tdclient.tfg']);</code>

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

<code matlab xfigure_setfigvisible.m>% set Position of tdclient
tdclient_ui.Position(1:2) = [200, 400];</code>

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

<code matlab 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;</code>