creates a standard uipanel object but with automatic management
- of the contained widget or layout. The properties available are largely
- the same as the builtin uipanel object. Where more than one child is
- added, the currently visible child is determined using the Selection property.
creates a new card panel which allows
- selection between the different child objects contained, making the
- selected child fill the space available and all other children
- invisible. This is commonly used for creating wizards or quick
- switching between different views of a single data-set.
Arrange a single element in a panel with boxed title
-
-
obj = uix.BoxPanel( )
-
creates a box-styled panel object with
- automatic management of the contained widget or layout. The
- properties available are largely the same as the builtin UIPANEL
- object. Where more than one child is added, the currently visible
- child is determined using the Selection property.
Function to call when panel is minimized or maximized. Note that if empty, no minimize button is shown. See advanced maneuvers with panels for details.
Padding
positive integer
Number of pixels of extra space around the outside of the layout.
Function to call when the selected tab is changed. The event-data supplied has fields OldValue and NewValue giving the previously selected and newly selected tab indices.
TabContextMenus
cell array of context menus
The context menu (or []) for each tab.
TabEnables
cell array of on | off
A list of the enabled state of each tab (default is all 'on').
TabTitles
cell array of strings
A list of the names of the tabs with one entry per tab.
Function to call when the layout is being deleted.
Heights
double vector
Height of each of the children. Positive entries indicate fixed sizes in pixels, negative values indicate relative weights for resizing. The size of this vector must always match the size of Contents.
HorizontalOffsets
double vector
Horizontal offset of each of the children. Each value is limited to between 0 and the difference between the width of child and the width of the panel. The size of this vector must always match the size of Contents.
HorizontalSteps
positive double vector
Horizontal slider step for each of the children. The size of this vector must always match the size of Contents.
MinimumHeights
double vector
Minimum height in pixels of each of the children. The size of this vector must match the size of Contents.
MinimumWidths
double vector
Minimum width in pixels of each of the children. The size of this vector must match the size of Contents.
Vertical offset of each of the children. Each value is limited to between 0 and the difference between the height of child and the height of the panel. The size of this vector must always match the size of Contents.
VerticalSteps
positive double vector
Vertical slider step for each of the children. The size of this vector must always match the size of Contents.
Visible
on | off
Visibility.
Widths
double vector
Width of each of the children. Positive entries indicate fixed sizes in pixels, negative values indicate relative weights for resizing. The size of this vector must always match the size of Contents.
-
-
For example:
-
f = figure( 'Name', 'uix.ScrollingPanel Help Example' );
-f.Position(3:4) = 400;
-p = uix.ScrollingPanel( 'Parent', f );
-a = axes( 'Parent', p );
-[x, y, z] = peaks();
-surf( a, x, y, z )
-a.ActivePositionProperty = 'position';
-set( p, 'Widths', 600, 'Heights', 600, 'HorizontalOffsets', 100, 'VerticalOffsets', 100 )
creates a new horizontal box layout with all properties set to defaults.
- The output is a new layout object that can be used as the parent for other user-interface components.
Width of each of the children. Positive entries indicate fixed sizes in pixels, negative values indicate relative weights for resizing. The size of this vector must always match the size of Contents.
creates a new vertical box layout with all properties set to defaults.
- The output is a new layout object that can be used as the parent for other user-interface components.
Function to call when the layout is being deleted.
Heights
double vector
Height of each of the children. Positive entries indicate fixed sizes in pixels, negative values indicate relative weights for resizing. The size of this vector must always match the size of Contents.
MinimumHeights
double vector
Minimum height in pixels of each of the children. The size of this vector must match the size of Contents.
Padding
positive integer
Number of pixels of extra space around the outside of the layout.
Arrange elements horizontally with draggable dividers
-
-
obj = uix.HBoxFlex( )
-
creates a new horizontal box layout with draggable dividers and with all properties set to defaults.
- The output is a new layout object that can be used as the parent for other user-interface components.
Width of each of the children. Positive entries indicate fixed sizes in pixels, negative values indicate relative weights for resizing. The size of this vector must always match the size of Contents.
Arrange elements vertically with draggable dividers
-
-
obj = uix.VBoxFlex( )
-
creates a new vertical box layout with draggable dividers and with all properties set to defaults.
- The output is a new layout object that can be used as the parent for other user-interface components.
-
-
obj = uix.VBoxFlex( prop, value, ... )
-
also sets one or more property values from the list below.
Function to call when the layout is being deleted.
DividerMarkings
on | off
Show markings on the draggable dividers (default 'on').
Heights
double vector
Height of each of the children. Positive entries indicate fixed sizes in pixels, negative values indicate relative weights for resizing. The size of this vector must always match the size of Contents.
MinimumHeights
double vector
Minimum height in pixels of each of the children. The size of this vector must match the size of Contents.
Padding
positive integer
Number of pixels of extra space around the outside of the layout.
is a type of HBox specialised for
- arranging a row of buttons, check-boxes or similar graphical
- elements. All buttons are given equal size and by default are
- centered in the drawing area. The justification can be changed as
- required.
is a type of VBox specialised for
- arranging a column of buttons, check-boxes or similar graphical
- elements. All buttons are given equal size and by default are
- centered in the drawing area. The justification can be changed as
- required.
creates a new new grid layout with all properties set to defaults. The number of rows and
- columns to use is determined from the number of elements in the
- Heights and Widths properties respectively. Child elements are
- arranged down column one first, then column two etc. If there are insufficient
- columns then a new one is added.
- The output is a new layout object that can be used as the parent for other user-interface components.
Arrange elements in a two dimensional grid with draggable dividers
-
-
obj = uix.GridFlex( )
-
creates a new new grid layout with draggable dividers between elements. The number of rows and
- columns to use is determined from the number of elements in the
- Heights and Widths properties respectively. Child elements are
- arranged down column one first, then column two etc. If there are insufficient
- columns then a new one is added.
- The output is a new layout object that can be used as the parent for other user-interface components.
GUI Layout Toolbox provides a package of MATLAB objects that allow for complex
- arrangement of graphical user interface elements within a figure window. The
- main capabilities provided are:
-
-
Automatic element arrangement horizontally, vertically or in grids
-
Ability to specify fixed sizes or resizing weights for each element
-
Ability to "nest" layouts to produce virtually any element arrangement
-
Divider bars for user-resizing of elements
-
-
These element arrangement capabilities are designed to match those found as
- standard in other user-interface toolkits such as Java Swing, GTK, QT etc.
This is version 2 of GUI Layout Toolbox, designed to work with the new
- MATLAB graphics system that was introduced in R2014b.
-
Version 1 works with MATLAB releases prior to R2014b that use the old
- graphics system.
-
-
-
2.2: Compatibility with version 1
-
-
If you are upgrading from version 1, there are a number of compatibility
- considerations:
-
-
Package name
-
Version 1 classes were contained in the package "uiextras". Version 2 classes are
-contained in the package "uix". In version 2, a package "uiextras" is included
-to provide support for legacy code. Classes in "uiextras" extend
-corresponding classes in "uix", and contain only compatibility-related
-code.
-
-
Contents property
-
The contents of version 1 objects were accessible via the property Children.
-The contents of version 2 objects are accessible via the property Contents.
-Version 2 objects also provide a property Children, but this controls the
-vertical stacking order rather than the layout order. Legacy code that accesses
-Children will run without error, but will not achieve the desired change in
-layout order, and should be modified to access Contents instead.
-
-
An upcoming release of version 1 will include support for code that references
-contents via Contents. That way, code modified to work in version 2 will also
-work in version 1.
-
-
The background to this change is as follows. Version 1 objects were wrappers
-for built-in graphics objects, and presented contents in layout order via
-the property Children. Version 2 objects extend built-in graphics objects,
-and as such, inherit properties, methods and events. One such property is
-Children which is used to control the top-to-bottom stacking order.
-MATLAB stacking rules, e.g. controls are always on top of axes, mean that
-some reasonable layout orders may be invalid stacking orders, so a new
-property for layout order is required.
-
-
Auto-parenting
-
The new MATLAB graphics system introduces unparented objects, i.e. those with property Parent
-empty. The new system also introduces a separation between formal class constructors, e.g.
-matlab.ui.container.Panel, and informal construction functions, e.g. uipanel.
-Construction functions are auto-parenting, i.e. if Parent is not specified then it is set to
-gcf, whereas class constructors return objects with Parent empty unless
-explicitly specified. Version 2 presents a formal interface of class constructors which follow this new
-convention.
-
-
Classes in "uiextras" are auto-parenting so the behavior of legacy code is
-unchanged. However, best practice is to specify parent explicitly during
-construction.
-
-
Defaults mechanism
-
Version 1 provided a defaults mechanism (uiextras.get, uiextras.set
-and uiextras.unset) that mimicked get and set in the MATLAB
-graphics system itself. This feature has been removed from version 2. Users should use an
-alternative programming pattern, e.g. factory function, to create objects with standard settings.
-
-
Enable and disable
-
Version 1 provided a mechanism to enable and disable container contents using the property
-Enable. This feature has been removed from version 2. Users should enable and disable
-controls directly rather than via containers.
A number of property names have changed to achieve greater consistency
-across the package. For example, RowSizes and ColumnSizes in
-uiextras.Grid are now Heights and Widths in uix.Grid. The package
-"uiextras" provides support for legacy property names.
-
-
RowSizes in "uiextras" is Heights in "uix"
-
ColumnSizes in "uiextras" is Widths in "uix"
-
ShowMarkings in "uiextras" is DividerMarkings in "uix"
-
-
-
Property shape changes
-
Version 2 contents companion properties are now of the same size as Contents,
-i.e. column vectors. In version 1, these properties were row vectors. The
-package "uiextras" provides support for legacy property values.
-
-
Tab selection behavior
-
In version 1, after adding a tab to a tab panel, the new tab is selected.
-
In version 2, the original selection is preserved, except if the tab panel was
- empty, in which case the new tab is selected. This is consistent with the
- behavior of uitabgroup.
- The GUI Layout Toolbox version numbers take the form major.minor.iter. The
- current version you have installed can be checked by typing ver
- at the MATLAB command prompt.
-
- This chapter describes the purpose and overall design of the layout
- tools that the toolbox provides. It also provides some examples of
- creating some user interfaces using layouts.
-
The purpose of a "layout" is to manage the positioning of one
- or more user-interface components. This means that instead of
- worrying about the exact position of each user interface component
- you instead worry about the relative positioning of them; are they
- arranged in a vertical list, horizontal list, a grid pattern, etc.
-
The best way to understand what layouts are and why they are a good user-interface
- design tool is to see some examples. The sections below go through the
- basics of building an interface using layouts and how to build complex
- interfaces using them.
Now let's create the horizontal layout and add it to the figure. Note
- that in common with other MATLAB graphics objects, one object is added to
- another by setting the Parent property - this will automatically
- adjust the list of Children in the parent object. The job of a
- horizontal box layout is to arrange its contents in a horizontal line,
- setting the position of each element to best fill the space:
Nothing's changed! That's because the layout is for arranging
- other user-interface components - it doesn't draw anything itself. Let's
- add some buttons. Note how after creating each button the existing contents
- of the box make room for the new addition; we don't need to set the position of
- any user-interface component!
Panels: show a single child element with some decoration. Other children
- of the layout are hidden from view. The visible child can be switched. Available
- panels include
- Panel,
- CardPanel,
- BoxPanel,
- TabPanel and
- ScrollingPanel.
-
-
Boxes: arrange children linearly in a single row or column. Available boxes include
- HBox,
- VBox,
- HBoxFlex and
- VBoxFlex.
-
-
Grids: (also known as tables) arrange children in a two-dimensional grid. Available grids include
- Grid and
- GridFlex.
In the previous section we noted that when using layouts
- you never need to set the position or size of a user-interface
- component yourself - the layouts take care of it. So how do
- you control the sizes of the components?
-
Each layout that arranges multiple items within its drawing area
- has a sizing property: for horizontal boxes this is Widths
- and for vertical boxes Heights; for grids we have both Widths
- and Heights. These all obey the same convention:
-
-
Positive numbers indicate sizes in pixels (similar to "pixel" units)
-
Negative numbers indicate a weighting for variable sizing (similar to "normalized" units)
-
-
By default all sizes are set to -1 (variable size with unit weighting).
We can set the middle element to be twice as wide as the others
- (but still variable width) by setting its weight to -2 with the others at -1:
-
-
layout.Widths = [-1 -2 -1]
-
-
-
Alternatively we might want the first element to have a
- fixed width of 100 pixels with the others filling any remaining
- space equally:
-
-
layout.Widths = [100 -1 -1]
-
-
-
-
This ability to mix fixed and variable sized elements is
- crucial in interface design. It really comes into its own when building
- a hierarchy of layouts, described next.
Many of the multi-element layouts also provide a MinimumWidths
- or MinimumHeights
- property to prevent an element becoming too small. This is measured in
- pixels and defaults to one pixel. Take care to ensure that the available
- space is at least the sum of the minimum sizes, plus any padding and
- spacing.
Instead of thinking of this in terms of three elements that need
- positioning, we can break it up into two simple linear ("box") arrangements:
- a vertical box with the axes at the top and a control area at the bottom and
- a horizontal box containing two buttons:
-
.
-
By placing the second layout (horizontal box) inside the first (vertical box)
- we arrive at the complete layout. Since the sizes of the elements in each list
- can be set to be fixed or flexible we can achieve a user-interface that is not just
- arranged correctly when created, but also behaves well when resized.
-
-
Note that the buttons have stayed fixed height as the window grows and the
- axes grow to fill the remaining space.
The example above can be created programmically pretty
- much as described in text
- (the completed example code is here:
- [ view
- | edit
- | run ]
- )
4. Set the sizes We want the axes to grow with the window so
- set the first size to be -1 (which means variable size with wieght 1) and the buttons to stay fixed height so set the
-second size to 35 (fixed height of 35 pixels)
MATLAB ships with a GUI design tool called GUIDE. This
- doesn't use layouts, but forces users to manually position each element. This approach
- is a much faster way to build simple user-interfaces, so why would you want to
-use layouts?
-
The over-riding reason for using layouts or layout managers is
- to gain control of the resizing behaviour of the interface without
- having to write a complex "ResizeFcn". If you simply position user-interface elements
- directly (either using GUIDE or programmatically), you
- have two choices about what happens when the window resizes:
-
-
For example:
- 1. The user-interface components scale with the window (normalised units) We didn't really want the buttons to grow but everything resizes in proportion.
-
-
- 2. The user-interface components stay fixed and the window resize creates empty space (pixel units) Although the buttons don't now grow, neither does the axes, which looks very odd.
-
Neither of these alternatives is particularly useful for a serious
- user-interface. Typically there are user-interface components that should
- be fixed size: icons, buttons, selectors etc; and others that should resize
- with the window: graphs, images, prose text etc. To achieve this one needs
- to be able to specify which interface components should be fixed size and
- which variable. Over the last two decades, layouts have been shown to be
- the method of choice for achieving this.
-
For example:
- Using layouts, some user-interface components scale with the window, others stay fixed
-
- Unlike other MATLAB user interface components, axes
- have two position properties: Position and
- OuterPosition. This means one has some extra
- options as to how the layout will arrange the axes.
-
Typically one
- would position some axes using their OuterPosition so that the
- axis labels, title and other annotations are all contained within the
- specified area. Sometimes, particularly if drawing images, one might want
- to instead make the axes canvas (the white bit!) fill the specified area.
- This is done by setting the Position property instead.
-
(The code for this example can be found here:
- [ view
- | edit
- | run ]
- )
-
- When using layouts to position axes, the position property
- is set by the layout, not the user. Whether the Position
- or OuterPosition property is used is determined by the
- ActivePositionProperty property of the axes.
- Note that the default setting is "outerposition".
-
-
- The following example illustrates the two usages.
-
-
-
Open a window
-
Open a new figure window and remove the toolbar and menus.
The layout involves two axes side by side. This is done using a flexible horizontal box. The left-hand axes is left with the ActivePositionProperty set to "outerposition", but the right-hand axes is switched to use Position.
Using OuterPosition (left-hand axes) is the normal mode and looks good for virtually any plot type. Using Position is only really useful for 2D plots with the axes turned off, such as images.
(The code for this example can be found here:
- [ view
- | edit
- | run ]
- )
-
- When using layouts to position axes that can also have a
- colorbar or legend it is very important to group the axes
- with its colorbar and legend by putting them inside a uicontainer.
-
-
- The following example illustrates this.
-
-
-
Open a window
-
Open a new figure window and remove the toolbar and menus.
- The uix.BoxPanel provides some extra buttons
- and callbacks that can be used to design advanced user-interface
- layouts. In particular, the sections below illustrate how to create
- interfaces with context help, and panels that can be minimized or undocked.
-
- When a uix.BoxPanel has its HelpFcn
- filled in, a help button (?) is shown in the upper-right of the
- title-bar. When the user clicks this button the specified function
- is called.
-
-
For example:
- Here we hookup the HelpFcn to simply bring up
- the MATLAB documentation for each command. Clicking any of the "?" buttons
- will cause the MATLAB help browser to open.
-
- When a uix.BoxPanel has its MinimizeFcn
- filled in, a minimize/maximize button (â–´/â–¾) is shown in the upper-right of the
- title-bar. When the user clicks this button the specified function
- is called. Since the behaviour of the parent container is
- different in different use-cases, it is up to the user to write
- some code to actually resize the panel. Note that minimizing
- a panel to its title-bar only really makes sense inside a
- uix.VBox or uix.VBoxFlex.
-
-
The following simple example shows how to add minimize/maximize
- functionality to a box full of panels. Save the code into
- a file called "minimizeexample.m" to run it.
-
-
(The code for this example can be found here:
- [ view
- | edit
- | run ]
- )
We set each panel to call the same minimize/maximize function.
- This function is nested inside the main function so that it has access
- to the main function's variables. A better way to do this is to make the
-main function into a class, but this nested-function approach is fine
-for simple applications.
-
Note that as soon as we set the "MinimizeFcn" property the minimize/maximize
- icon appears in the top-right of each panel. We use a cell-array to pass an
- extra argument, the panel number, to the minimize function. This extra argument appears after the usual
- eventSource and eventData arguments.
-
% Hook up the minimize callback.
-set( panel{1}, 'MinimizeFcn', {@nMinimize, 1} );
-set( panel{2}, 'MinimizeFcn', {@nMinimize, 2} );
-set( panel{3}, 'MinimizeFcn', {@nMinimize, 3} );
-
-%-------------------------------------------------------------------------%
- function nMinimize( eventSource, eventData, whichpanel )
- % A panel has been maximized/minimized
- s = get( box, 'Heights' );
- pos = get( fig, 'Position' );
- panel{whichpanel}.Minimized = ~panel{whichpanel}.Minimized;
- if panel{whichpanel}.Minimized
- s(whichpanel) = pheightmin;
- else
- s(whichpanel) = pheightmax;
- end
- set( box, 'Heights', s );
-
- % Resize the figure, keeping the top stationary
- delta_height = pos(1,4) - sum( box.Heights );
- set( fig, 'Position', pos(1,:) + [0 delta_height 0 -delta_height] );
- end% Minimize
-
-end% Main function
-
-
-
-
-
Click the minimize buttons
-
Minimizing the middle panel causes it to shrink to just its
- title-bar and the window shrinks accordingly. The
- "Minimize" icon is replaced by a "Maximise" icon.
-
-
Re-maximizing the panel would
- cause it to re-appear in full and the window to grow again.
- When a uix.BoxPanel has its DockFcn
- filled in, a dock/undock button (↘/↗) is shown in the upper-right of the
- title-bar. When the user clicks this button the specified function
- is called. Since re-docking the panel into its previous parent
- depends on the type of parent, it is up to the user to write
- some code to actually extract or insert the panel.
-
-
The following simple example shows how to add dock/undock
- functionality to a box full of panels. Save the code into
- a file called "dockexample.m" to run it.
-
-
(The code for this example can be found here:
- [ view
- | edit
- | run ]
- )
We set each panel to call the same dock/undock function.
- This function is nested inside the main function so that it has access
- to the main function's variables. A better way to do this is to make the
-main function into a class, but this nested-function approach is fine
-for simple applications.
-
Note that as soon as we set the "DockFcn" property the Dock/Undock
- icon appears in the top-right of each panel. We use a cell-array to pass an
- extra argument, the panel number, to the minimize function. This extra argument appears after the usual
- eventSource and eventData arguments.
-
% Set the dock/undock callback
-set( panel{1}, 'DockFcn', {@nDock, 1} );
-set( panel{2}, 'DockFcn', {@nDock, 2} );
-set( panel{3}, 'DockFcn', {@nDock, 3} );
-
-%-------------------------------------------------------------------------%
- function nDock( eventSource, eventData, whichpanel )
- % Set the flag
- panel{whichpanel}.IsDocked = ~panel{whichpanel}.IsDocked;
- if panel{whichpanel}.IsDocked
- % Put it back into the layout
- newfig = get( panel{whichpanel}, 'Parent' );
- set( panel{whichpanel}, 'Parent', box );
- delete( newfig );
- else
- % Take it out of the layout
- pos = getpixelposition( panel{whichpanel} );
- newfig = figure( ...
- 'Name', get( panel{whichpanel}, 'Title' ), ...
- 'NumberTitle', 'off', ...
- 'MenuBar', 'none', ...
- 'Toolbar', 'none', ...
- 'CloseRequestFcn', {@nDock, whichpanel} );
- figpos = get( newfig, 'Position' );
- set( newfig, 'Position', [figpos(1,1:2), pos(1,3:4)] );
- set( p{whichpanel}, 'Parent', newfig, ...
- 'Units', 'Normalized', ...
- 'Position', [0 0 1 1] );
- end
- end% nDock
-
-
-
Add the close callback
-
If the user closes the main window we need to also close any
- other windows that were created. This can be done by finding
- the window that contains each panel and deleting it.
-
%-------------------------------------------------------------------------%
- function nCloseAll( ~, ~ )
- for ii=1:numel( panel )
- ifisvalid( panel{ii} ) && ~strcmpi( panel{ii}.BeingDeleted, 'on' )
- figh = ancestor( panel{ii}, 'figure' );
- delete( figh );
- end
- end
-
- end% nCloseAll
-end% Main function
-
-
-
-
Click the dock buttons
-
Undocking the middle panel causes the other two to fill the
- vacated space. The undocked panel appears in its own window, with the
- "Undock" icon replaced by a "Dock" icon.
-
.
-
Re-docking the panel would
- cause it to be appended to the right of the list in the original window. Closing the main window
- causes all panels, docked or undocked, and their enclosing windows to be closed.
Whilst the layouts in this toolbox do not integrate into the
- MATLAB Graphical User Interface Design Environment (GUIDE), it
- is possible to insert layouts into a GUIDE-built GUI as follows:
-
Create the GUIDE GUI
-
Create you GUIDE application as usual, placing a panel where you
- want to insert the layout. You can turn the panel border and title
- off if you do not want them.
-
-
-
Insert the layout
-
Edit the "OpeningFcn" in the GUIDE-created code and insert your
- layout into the panel, making it fill the space. In the example below
-four boxpanels are inserted into a grid, which itself is placed inside
- uipanel1:
-
-
% --- Executes just before guideApp is made visible.
-function guideApp_OpeningFcn(hObject, eventdata, handles, varargin)
-
-% Choose default command line output for guideApp
-handles.output = hObject;
-
-% Update handles structure
-guidata(hObject, handles);
-
-% Put a layout in the panel
-g = uix.GridFlex( 'Parent', handles.uipanel1, ...
- 'Units', 'Normalized', 'Position', [0 0 1 1], ...
- 'Spacing', 5 );
-uix.BoxPanel( 'Parent', g, 'Title', 'Panel 1' );
-uix.BoxPanel( 'Parent', g, 'Title', 'Panel 2' );
-uix.BoxPanel( 'Parent', g, 'Title', 'Panel 3' );
-uix.BoxPanel( 'Parent', g, 'Title', 'Panel 4' );
-g.Heights = [-1 -1];
-
-
-
(Full source code for this application is available here:
- [ view
- | edit
- | run ]
- )
Applications built using these layout tools can be deployed as standalone
- executables using the MATLAB Compiler in
- the same way as any other MATLAB application. There is, however, one thing to watch out for:
-
-
You must explicitly include the "Resources" folder within the +uix package
-
-
Example
-
Below is a screen-shot of the deploytool setup
- used to build the example application.
- The "Resources" folder from the toolbox has been explicitly added as a
-shared resource so that the mouse-pointers and panel icons continue to work.
The following example application uses many of the layout features
- discussed above in order to create a good-looking user interface that
- scales well when resized. It is not designed to showcase all the
- layout functionality, but shows how callbacks are added to provide
- user interaction. It also exemplifies separating the data from the GUI,
- a fundamental part of creating modular and maintainable applications.
There are many ways to build graphical applications in MATLAB, but
- here we will take a very simple approach. If the application were to become
-larger and more complex, this approach would be changed to better mitigate
- the complexity. Some notes on this are contained at the end.
-
-
The application is structured as a single function with callbacks and other helper
- functions stored as "nested" subfunctions, i.e. functions inside the main function. This has
- the advantage that the nested subfunctions can share access to any variables
- declared in the main function. This is also a risk as anything we accidentally
- declare in the main function becomes "global" within the application. For that reason
- all logic is put into subfunctions and we restrict the main
- function to just declaring two shared variables:
-
-
data: a structure containing all shared data
-
gui: a structure containing handles to GUI widgets
-
-
-function demoBrowser()
-
- % Declare shared variables
- data = createData();
- gui = createInterface( data.DemoNames );
-
- % Now update the GUI with the current data
- updateInterface();
- redrawDemo();
-
- % Helper subfunctions.
- function data = createData() ... end;
- function gui = createInterface(names) ... end;
- function updateInterface() ... end;
- function redrawDemo() ... end;
-
- % Callback subfunctions.
- function onMenuSelection() ... end;
- function onListSelection() ... end;
- function onDemoHelp() ... end;
- function onHelp() ... end;
- function onExit() ... end;
-
-end % Main function
-
-
-
Note that all of the work is done in subfunctions. Most subfunctions
-are callbacks executed when a button is pressed or a menu selected. The four used
-at startup are helper functions:
-
-
createData: build the structure which contains all application data
-
createInterface: build the user interface
-
updateInterface: update selectors etc in response to a change in the data
-
redrawDemo: redraw the plot part of the interface
-
-
We will not dig into all the subfunctions and callbacks, but instead
- concentrate on the GUI creation (createInterface)
- and update (updateInterface).
-
-
(Full source code for this application is available here:
- [ view
- | edit
- | run ]
- )
The interface creation is handled in the createInterface
- subfunction. This has two distinct sections: menu building and widget arrangement.
- The menus are built using the standard MATLAB menu building command uimenu,
- so let's concentrate on the widget arrangement.
-
-
The top-level layout is a horizontal arrangement, placing the controls
-to the left of the main plot. We make the layout draggable by using the
-"flex" variant of HBox, and put a panel in each side. Note that setting the
-"HelpFcn" for the view panel adds a small "?" icon for bringing up help. See
-here for more details.
The controls panel is filled with a vertical layout containing the listbox
-and a button. Note the callbacks that are specified for both the list and button. These
-both call further subfunctions that are able to access the common "data" and "gui"
-shared structures.
-
-% Create the controls
-controlLayout = uix.VBox( 'Parent', controlPanel, ...
- 'Padding', 3, 'Spacing', 3 );
-gui.ListBox = uicontrol( 'Style', 'list', ...
- 'BackgroundColor', 'w', ...
- 'Parent', controlLayout, ...
- 'String', demoList(:), ...
- 'Value', 1, ...
- 'Callback', @onListSelection);
-gui.HelpButton = uicontrol( 'Style', 'PushButton', ...
- 'Parent', controlLayout, ...
- 'String', 'Help for <demo>', ...
- 'Callback', @onDemoHelp );
-set( controlLayout, 'Heights', [-1 28] ); % Make the list fill the space
-
-
-
-
Finally, the view itself is simply an axes placed inside the view panel:
The second subfunction we will look at, updateInterface, uses the
- current selections to update the interface. This uses the structure
- "data" to update various parts of the interface. For this simple example this just means:
-
menus = get( gui.ViewMenu, 'Children' );
-set( menus, 'Checked', 'off' );
-% Use the name to work out which menu item should be ticked
-whichMenu = strcmpi( demoName, get( menus, 'Label' ) );
-set( menus(whichMenu), 'Checked', 'on' );
-
-
-
In general, this update function is called whenever the underlying
- shared "data" structure is changed. This happens when the user clicks
- a button, selects a list item or a menu. Next we will look at a typical
- callback.
-
(Full source code for this application is available here:
- [ view
- | edit
- | run ]
- )
Finally, let's have a look at how one of the callbacks works: "onListSelection", the function
- that is called when an item is selected in the listbox. The other
- callbacks obey the same pattern.
-
The basic rule of thumb is that a callback should not update any part of
- the user interface directly - it's job is to respond to user interaction by changing the "data" structure.
- In this example, each callback changes the underlying data structure
- then asks the interface to refresh. This might mean that things update in the
-interface that don't need to, but ensures the callbacks remain simple and that all
-interface update logic is in one place. Extending this to more granular interface updates
- is straightforward. See Scalability for more details.
-
For the listbox callback, the "src" argument is a handle to the
- listbox and we simply need to update the SelectedDemo field of "data"
- to reflect the new selection. We then ask the rest of the interface to
- update in response to the change.
-
-
- % User selected a demo from the list - update "data" and refresh
-data.SelectedDemo = get( src, 'Value' );
-updateInterface();
-redrawDemo();
-
-
-
(Full source code for this application is available here:
- [ view
- | edit
- | run ]
- )
When the main function is launched (click
- here)
- it first creates the data, then the GUI, then updates the GUI using the data. At this point the
- function exits and control is returned to the command prompt. Note, however,
- that the GUI is still onscreen and will still respond to user interaction.
-
This works because the "shared" variables in the main function are not cleared when the
- function exits. They are only cleared once the GUI is closed. This is a slightly
- unusual, but very useful, feature of using nested functions for building
- applications.
-
For example:
-
>> demoBrowser
-
-
-
(Full source code for this application is available here:
- [ view
- | edit
- | run ]
- )
As applications get bigger the code gets more complex. The simple
- application structure used here does not scale well to large applications,
- however some small adjustments can make life much better:
-
-
Convert the "data" structure into a handle object. This allows
- a single "data" object to be shared between mutliple graphical interfaces, and in turn means that the interface
- need not be built as a single monolithic entity.
-
Use the events system to trigger updates
- to specific parts of the GUI in response to bits of the data object changing. This removes the need
- for a single large "UpdateInterface" function and reduces coupling between parts of the interface. For example,
- the "SelectedDemo" property would have an associated event such that when it is changed by a callback (or from the command-line) it
- notifies other interface components of the change. Each interface component (or group thereof) can
- just listen for the events that affect it.
-
-
Advice on how to build large-scale applications is beyond the scope
- of this document. If you need help in this area, please contact your MathWorks
- account manager who will be able to put you in touch with a technical specialist.
-
- Getting Started
- 1. What is GUI Layout Toolbox?
- 2. Compatibility considerations
- 3. Release notes
- 4. Installation
- 5. Support
- 6. Acknowledgements
-
-
- Examples
-
-
- User guide
- 1. Understanding layouts
- 2. Positioning axes
- 3. Controlling visibility
- 4. Advanced maneuvers with panels
- 5. Using layouts inside GUIDE GUIs
- 6. Deploying GUIs using the MATLAB Compiler
- 7. A complete example
-
-
- Function reference
-
- Index
-
-
diff --git a/widgets/GUI Layout Toolbox 2.3.1/layoutdoc/helptoc.xml b/widgets/GUI Layout Toolbox 2.3.1/layoutdoc/helptoc.xml
deleted file mode 100644
index 1d3398e..0000000
--- a/widgets/GUI Layout Toolbox 2.3.1/layoutdoc/helptoc.xml
+++ /dev/null
@@ -1,12 +0,0 @@
-
-
-
-
- GUI Layout
- Getting Started1. What is GUI Layout Toolbox?2. Compatibility considerations3. Release notes4. Installation5. Support6. Acknowledgements
- Examples
- User guide1. Understanding layouts1.1. Layout basics1.2. Types of layout1.3. Sizes and units1.4. Layout hierarchies1.5. Why use layouts?2. Positioning axes2.1. Position vs OuterPosition2.2. Axes inside layouts2.3. Colorbars and legends3. Controlling visibility3.1. Visible example4. Advanced maneuvers with panels4.1. Context help4.2. Minimize and maximize4.3. Dock and undock5. Using layouts inside GUIDE GUIs6. Deploying GUIs using the MATLAB Compiler7. A complete example7.1. Application structure7.2. createInterface7.3. updateInterface7.4. onListSelection7.5. Running it7.6. Scalability
- Function reference1. Panels1.1. uix.Panel1.2. uix.CardPanel1.3. uix.BoxPanel1.4. uix.TabPanel1.5. uix.ScrollingPanel2. Boxes2.1. uix.HBox2.2. uix.VBox2.3. uix.HBoxFlex2.4. uix.VBoxFlex2.5. uix.HButtonBox2.6. uix.VButtonBox3. Grids3.1. uix.Grid3.2. uix.GridFlex4. Other functions4.1. uix.Empty4.2. uix.tracking4.3. layoutRoot
- Index
-
-
diff --git a/widgets/GUI Layout Toolbox 2.3.1/layoutdoc/index.html b/widgets/GUI Layout Toolbox 2.3.1/layoutdoc/index.html
deleted file mode 100644
index 8cd9683..0000000
--- a/widgets/GUI Layout Toolbox 2.3.1/layoutdoc/index.html
+++ /dev/null
@@ -1,59 +0,0 @@
-
-
-
- GUI Layout Toolbox documentation
-
-
-
-
-
-
-
-
-
-
-
-
GUI Layout Toolbox documentation
- Version: 2.3.1
-
- GUI Layout Toolbox is a layout manager for creating MATLAB graphical user
- interfaces that resize gracefully. The classes supplied can be used in
- combination to produce virtually any user interface layout.
-
-
-
-
Arrange MATLAB user interface components horizontally, vertically or in grids
-
Mix fixed- and variable-size components
-
Resize components interactively by dragging dividers
-
Show and hide components using tabs and panels
-
Show part of a large component in a scrollable panel
- 
- 
- 
- 
-
-
-
-
-
-
-
-
-
-
-
-
-
- 
- 
- 
- 
- 
- 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- 
- 
-
-
-
-
-
- 
.
.
.
.
.
.
- 
GUI Layout
Getting Started
1. What is GUI Layout Toolbox?
Examples
User guide
Function reference
Index
-
-
diff --git a/widgets/GUI Layout Toolbox 2.3.1/layoutdoc/helptoc.xml b/widgets/GUI Layout Toolbox 2.3.1/layoutdoc/helptoc.xml
deleted file mode 100644
index 1d3398e..0000000
--- a/widgets/GUI Layout Toolbox 2.3.1/layoutdoc/helptoc.xml
+++ /dev/null
@@ -1,12 +0,0 @@
-
-
-
-
- 