%
%   The information in this file superceeds that in uiguide.m which
%   was previously shipped in the ../matlab/graphics directory.
%
%   MATLAB4 User Interface and Handle Graphics Programming Guidelines 
%
%   This help file contains useful tips, tricks, and methods for crafting
%   MATLAB4 applications with a graphical user interface.  Following
%   the guidelines listed has been found to yield code which is efficient 
%   (executes quickly and requires fewer lines), changeable, extensible, and 
%   intuitive.  
%
%
%                AN EFFECTIVE GUI PROGRAMMING METHODOLOGY
%
%  o Callbacks should be short and call functions.
%    When MATLAB evals a string, it must interpret it statement by statement.
%    MATLAB must do the same with a script m-file.  It behaves differently with
%    a function: the first time MATLAB encounters the function, it compiles it.
%    MATLAB does not re-interpret the function on subsequent calls.  Thus of 
%    the three possibilities (function m-file, script m-file, and long string),
%    making the callback a function m-file is by far the fastest, especially
%    if the callback is long.
%
%  o Switchyard concept of GUI programming.
%    This involves coding of an application with several actions of the GUI 
%    grouped into big functions. Try to limit the function to about 5 actions 
%    which are preferably related. Inside the function is a large if-then-else 
%    construct which executes portions of the function based on an input switch. 
%    Callback functions of UI objects (uicontrols and uimenus) and mouse Button
%    functions (down/motion/up) simply call the function with the appropriate 
%    input argument.  Callbacks are therefore very short and editing them is 
%    easier than changing multi-line string definitions.  A call to the function
%    with no input argument could by default start the program.  Program 
%    specific data and UI object handles are stored either as globals to the 
%    function or in the UserData of the objects.  This makes the application
%    "clear-proof".  For an example of this sort of programming, see "sigdemo1".
%
%  o Hierarchical GUI programming
%    Creating several functions for different actions has two major benefits.
%    It is easier to manage than one large switchyard that does everything.
%    The smaller functions compile as needed so you don't encounter a one time 
%    long performance hit waiting for the a large M-file to compile.
%
%
%  o The findobj command and the Tag property
%    The function findobj can be used to manage objects according to their 
%    properties.  The Tag property allows you to name and logically group the 
%    objects, without the need for using globals or the userdata property.  
%    There are numerous advantages to this approach:
%
%    Findobj does not introduce state to be managed, along with the ensuing 
%    drawbacks. Alternatives to findobj require that some sort of data structure 
%    be defined, created, managed, maintained, documented and protected. This 
%    makes applications more difficult to write, change, debug and understand.
%
%    Findobj solutions are extensible. Alternative solutions do not allow for
%    extension of applications without the developer learning the positions of
%    the handles and altering existing code.  The findobj method for changing
%    all text object fonts to helvetica, for example, is independent of both 
%    the environment and the number of text objects. Memorized handle solutions
%    require finding all of the objects of interest, which, especially in a
%    dynamic environment, can be complex. Grouping related items closely in the
%    user data can help some but that solution admits to only a single dimension
%    of grouping. Findobj allows objects to be gathered by any property or
%    combination of properties, and without careful layout and management of
%    handle arrays.  The solutions survive m-file-ization. A findobj based window 
%    can be saved to an m-file, and re-loaded and will still run. Applications 
%    that explicitly memorize handles will not survive this as the handle values 
%    will change.  Custom, hand-written m-files can be produced that generate 
%    working interfaces, but self-contained applications (figure == m-file) 
%    require findobj. This is actually just one of the benefits of being 
%    stateless.
%
%    Findobj Examples:
%
%    generate a list of all selected objects from the root down:
%        all_selected = findobj('selected','on');
%
%    if you typed into the editable text, then find the slider to modify:
%        the_slider = findobj(get(gco,'parent'),'type','uicontrol',...
%        'string','Gain Slider')
%
%    does the Demo menu figure exist, or do we need to create one?
%        menu_fig = findobj(get(0,'chil'),'flat','type','figure',...
%        'name','Select A Demo')
%
%    find a group of objects
%        group1 = findobj('tag','group1')
%    
%
%                GETTING THE MOST OUT OF HANDLE GRAPHICS 
%      (or, how to create fast and smooth click and drag applications)
%
%  o Draw movable or changing objects with the 'erasemode' property set to 
%    'xor' or 'background'.  This prevents re-rendering the axes when changing 
%    these objects. 'erasemode' is a property of all objects which are children
%    of axes (line, text, surface, image, patch).
%
%  o Set 'drawmode' (an axes property) to 'fast'.  This prevents MATLAB from
%    sorting 3D objects, which can speed things up significantly.  The side-
%    effect is that 3D surface plots will not work in this mode.
%
%  o Set 'backingstore' (a figure property) to 'off'.  This should give 
%    roughly a factor of two speed-up in normal drawing but turns off the 
%    instantaneous update that normally ocurrs when windows are uncovered.
%
%  o Set 'nextplot' (a figure property) to 'new' when creating a GUI.  That 
%    way when you make plots from the command window they don't appear in the
%    axes of the GUI's figure window.
%
%  o Wherever possible, recycle figure windows by using the 'visible' property
%    of figures instead of creating and destroying them.  When done with the
%    window, set 'visible' to 'off'; when you need the window again, make any
%    changes to the window and THEN set 'visible' to 'on'.  Creating figure
%    windows involves much more overhead than un-hiding them.
%
%  o Set a uicontrol's style upon creation.  E.g. uicontrol('Style','edit')
%    is much faster than h=uicontrol;set(h,'Style','edit').
% 
%  o Set a figure's position upon creation.  E.g. figure('Pos',[10 10 200 100])
%    is much faster than f=figure;set(f,'Pos',[10 10 200 100]).
% 
%  o Don't change directories during a callback or during the creation of
%    uicontrols.  It introduces significant delay because changing directories
%    will cause M-files to recompile.
%
%  o It is faster to create all your menus first, do a drawnow,  and then 
%    create the other uicontrols.
%
%  o Set up your figure with units set to pixels and then change to normalized 
%    for addition speed on creation.
%  
%  o Try to limit the number of objects you have on the screen at any one time 
%    to a reasonable amount.  Unusually large amounts of figures and objects 
%    will cause performance to suffer.

%-----------------------------------------------------------------------------
%	Copyright (c) 1984-94 by The MathWorks, Inc.
%   $Revision: 1.6 $  $Date: 1995/01/17 22:55:22 $
%-----------------------------------------------------------------------------



