no way to compare when less than two revisions

Differences

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

@@ 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.
+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>