This shows you the differences between two versions of the page.
— |
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. | ||
+ | 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> | ||