User Tools

Site Tools



This shows you the differences between two versions of the page.

Link to this comparison view

xfigure [2011/04/04 20:27] (current)
jochen created
Line 1: Line 1:
 +====== 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.
 +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
xfigure.txt ยท Last modified: 2011/04/04 20:27 by jochen