No BSD License  

Highlights from
Graphic User Object (GUO) Toolbox

image thumbnail

Graphic User Object (GUO) Toolbox

by

 

02 Jun 2004 (Updated )

Programming tool for creating reusable Graphic User Interface (GUI) components.

contents.m
%                      The Graphic User Object Toolbox            version 2.08
%                      ===============================
% 
% The graphicuserobject (GUO) class supports the grouping of uicontrol and axes
% objects ("child objects") as well as other graphicuserobjects ("child GUOs")
% into a composite object which can itself be placed on figures or as a child
% GUO in other graphicuserobjects.  This is a powerful tool for structuring and
% reusing elements of user interfaces together with their associated 
% functionality.  The graphicuserobject class provides a frame of reference
% together with maintenance, access and display functions for its child objects
% and GUOs.  The complete GUO with all its children can be positioned or
% resized easily, hidden and re-shown.  GUOdemo.m demonstrates the main 
% features of the graphicuserobject class;  detailed descriptions of the 
% functions are provided below and in their header comments.
% 
% The graphicuserobject constructor method creates a GUO.  Internally, an axes
% object (referred to as the GUO frame) is used to define the position of the
% graphicuserobject and to provide a frame of reference for its children.  The
% GUO frame, which is NOT a child object, is automatically provided with a
% unique Tag and its properties can be set either on creation or later (using
% the "set" method).
% 
% The child objects are created with the overloaded uicontrol or axes functions.
% They have the same parent figure as the graphicuserobject but are positioned
% relative to the graphicuserobject rather than relative to the parent figure.
% Furthermore, child objects whose Units are 'normalized' are also sized
% relative to the graphicuserobject.  Class methods are provided for accessing
% the child objects, which may be identified either by name or number (see 
% "uicontrol").
% 
% Direct access via the handles of the child objects should be avoided wherever
% possible because the integrity of the graphicuserobject can be compromised
% when properties such as Parent, Position or Units are set directly.  However,
% the only case where such direct access has been found necessary is when the
% callback function of a child object requires access to other child objects,
% and then only if the graphicuserobject itself is not available for assignment
% (see "setuserdata"), otherwise the methods listed below should be sufficient.
% Furthermore, handles of objects below axes in the object hierarchy (Image,
% Light, Line, Patch, Rectangle, Surface and Text objects) may be used freely,
% because these objects already have an axes object as their natural frame of
% reference.
% 
% An existing GUO instance can be made a child of another existing GUO by means
% of the "addchildguo" method, after which the child GUO exists within the
% properties of the parent GUO and is no longer directly assigned to.  Child
% GUOs are positioned/sized relative to their parent GUO in the same way as
% child objects are;  they may also be identified either by name or number
% (child GUOs are numbered separately from child objects - see "addchildguo").
% Methods of a child GUO may be executed by means of the "guoeval" method.
% 
% The following methods are available for the graphicuserobject class:
% 
% function GUO = graphicuserobject(varargin)
% Class constructor for graphicuserobject.  The argument list "varargin", if
% supplied, is passed on to the axes function when creating the GUO frame.  In
% particular, the Position property would normally be supplied and, for
% example, Visible can be specified as 'on' in order to provide a border for
% the GUO.
% 
% function GUO = uicontrol(GUO, varargin)
% Creates a child control within "GUO".  The argument list "varargin" is as for
% the standard MATLAB uicontrol function except that "GUO" is supplied instead
% of "parent".  Child controls are positioned relative to the GUO frame, and
% sized relative to the GUO frame if the Units property of the control is
% 'normalized' (the default here), in which case the control is set (internally)
% to the GUO frame's units.  Specifying the Tag property for the child control
% allows it to be referenced by name;  child controls (and child axes) may also
% be referenced by number (in order of their creation, starting with 1).
% 
% function GUO = axes(GUO, varargin)
% Creates or makes current a child axes object within "GUO".  To create a child
% axes object, the argument list "varargin" is as for the standard MATLAB axes
% function (i.e. property name/value pairs);  positioning and referencing is
% performed as described in "uicontrol".  To make an axes object (either a
% child or the GUO frame) the current axes, "varargin" must have exactly one
% element referencing the axes by name or number;  to make the GUO frame the
% current axes, the element may be supplied as empty, zero or the Tag of the
% GUO frame.
% 
% function GUO = addchildguo(GUO, ChildGUO)
% Inserts "ChildGUO" within "GUO", whereby both "ChildGUO" and "GUO" are 
% graphicuserobjects.  Child GUOs are positioned relative to the GUO frame of 
% their parent, and sized relative to this GUO frame if the Units property of
% the child GUO is 'normalized' (the default here).  Specifying the Tag property
% for the child GUO allows it to be referenced by name;  child GUOs may also be
% referenced by number (in order of their creation, starting with 1).  Child 
% GUOs are numbered separately from child objects (uicontrols and axes).
% 
% function display(GUO)
% Lists number, style and tag for the GUO frame, child GUOs and child objects
% of "GUO" in the MATLAB command window;  this method is executed by MATLAB
% when the GUO name is typed without a semicolon.
% 
% function val = get(GUO, varargin)
% Gets GUO frame (axes) properties of "GUO".  The "val" and "varargin" arguments
% are as for the standard MATLAB "get" function.
% 
% function val = set(GUO, varargin)
% Sets properties for the GUO frame of "GUO" (in which case the modified GUO is
% returned as "val") or returns information as for the standard MATLAB "set"
% function.  Property changes which affect the children of "GUO" are taken into
% consideration (e.g. Parent, Position and Units).
% 
% function GUO = delete(GUO)
% Deletes the GUO frame, child objects and child GUOs of "GUO".
% 
% function val = getuserdata(DummyGUO, Tag)
% Gets the UserData property from the GUO frame object identified by "Tag"
% (for use in callback functions - see also "setuserdata").  "DummyGUO" is 
% ignored - it is required by MATLAB in order to be able to find this method.
% 
% function setuserdata(DummyGUO, Tag, UserData)
% Sets the UserData property for the GUO frame object identified by "Tag".
% "DummyGUO" is ignored - it is required by MATLAB in order to be able to find
% this method.
% 
% The "getuserdata" and "setuserdata" methods allow callback functions in
% particular to access data associated with a GUO.  Although this is a
% fundamental breach of the object-oriented paradigm, the only alternative
% in MATLAB would be to define all such GUOs globally in order that they may be
% assigned to;  however, this would also be a breach of the paradigm and would
% be inappropriate in particular for general-purpose, reusable GUOs.  For an
% excellent definition of the object-oriented paradigm, see "Object-oriented
% Software Construction" by Bertrand Meyer (Prentice Hall).
% 
% function var = getchild(GUO, Child, varargin)
% Gets properties of GUO child object;  "Child" may be a Tag name or the number
% of the child object (see "uicontrol").
% 
% function valOrGUO = setchild(GUO, Child, varargin)
% Sets properties for GUO child object;  "Child" may be a Tag name or the number
% of the child object (see "uicontrol").  The return value valOrGUO must be
% assigned to the GUO in all cases except where the MATLAB set function would
% return a result (property information - see MATLAB help).
% 
% function GUO = deletechild(GUO, Child)
% Deletes GUO child object;  "Child" may be a Tag name or the number of the 
% child object (see "uicontrol").
% 
% function [nObjects, nGUOs] = nchildren(GUO)
% Returns the number of children within "GUO".
% "nObjects" is the number of child objects (uicontrols and axes) and "nGUOs" 
% is the number of child GUOs within "GUO".
% 
% function h = childhandles(GUO)
% Returns the handles of the children (uicontrols and axes) within "GUO". This
% method should only be used when absolutely necessary, because the integrity
% of a graphicuserobject can be compromised when child object properties such
% as Parent, Position or Units are set via handles.  Such properties should 
% only be set via the "setchild" method.
% 
% function GUO = deletechildguo(GUO, ChildGUO)
% Deletes "ChildGUO" from "GUO".
% "ChildGUO" may be a Tag name or a child GUO number (see "addchildguo").
% 
% function [GUO, ExpressionResult] = guoeval(GUO, ChildGUO, Expression)
% Evaluates expression for a child GUO within "GUO".
% "ChildGUO" may be a Tag name or a child GUO number (see "addchildguo").
% "Expression" is a string containing the function to be evaluated, the first 
% argument of which (the child GUO) must be omitted - this will be inserted
% automatically.  If the result is a GUO, it replaces the child GUO within 
% "GUO", otherwise it is returned as "ExpressionResult".
% "GUO" is always returned, whether changed or not.
% 
% function [GUO, WasHidden] = hide(GUO)
% Makes "GUO" invisible.  The Visible property is set to 'off' for the GUO
% frame (axes) and the children (uicontrols and axes) of "GUO", as well as for
% all children (e.g. text and rectangle objects) of the various axes.  The
% previous status of the Visible property for each of these objects is saved
% so that it can be restored by the "show" function.  The "hide" function
% applies itself recursively to the child GUOs. 
% "WasHidden" indicates whether "GUO" was already hidden.
% 
% function [GUO, WasHidden] = show(GUO)
% Makes "GUO" (if previously hidden) visible again.  The Visible property is
% set to its previous value for all objects affected by the "hide" function. 
% "WasHidden" indicates whether "GUO" was already hidden.
% 
% function GUO = resizefcn(GUO)
% Corrects the position of children and child GUOs of "GUO" after the parent
% figure is resized.  However, most cases are handled automatically:  it is 
% only necessary to call this function (from the figure's ResizeFcn) if "GUO"
% has Units 'normalized' and contains one or more children or child GUOs having
% Units other than 'normalized' (e.g. 'pixels').
%
% function h = figure(GUO)
% Makes the parent figure of "GUO" the current figure and returns its handle.
%
%
% Copyright (c) SINUS Messtechnik GmbH 2002-2003
% www.sinusmess.de - Sound & Vibration Instrumentation
%                  - PCB Services
%                  - Electronic Design & Production

Contact us