GUI That Accepts and Returns Arguments

About the Example

This example shows how to create a GUI that supports optional input and output arguments. The example also shows how to present a standard color selection dialog box to the user.

Use the Color Palette

These are the basic steps for using the color palette.

  1. Clicking a color cell toggle button makes the program perform these actions:

    • Display the selected color in the preview area.

    • Display the red, green, and blue values for the newly selected color are displayed in the R, G, and B fields in the GUI.

  2. Clicking the Eraser toggle button is equivalent to selecting no color.

  3. Clicking the More Colors button displays a second dialog box containing more colors.

  4. Clicking the close box on the main dialog returns a function handle. You can call the returned function to get the RGB values of the selected color. For example, this code calls the ColorPalette program, which returns a function handle in the variable, getmycolor. The second line calls getmycolor to get the RGB values.

    getmycolor = colorPalette;
    rgb = getmycolor();

    The getmycolor function returns a 1-by-3 vector of values. It returns a NaN value if the user selects the Eraser button.

Call the colorPalette Function With Input Arguments

You can call the colorPalette function with input arguments:

mGetColorFcn = colorPalette('Parent',hPaletteContainer)

The colorPalette function accepts property name-value pairs as input arguments. Only the Parent is supported. This property specifies the handle of the parent figure or panel that contains the color palette. If the call to colorPalette does not specify a parent, it uses the current figure, gcf. Unrecognized property names or invalid values are ignored.

Copy and View the Color Palette Code

To obtain copies of the GUI files for this example, follow these steps:

  1. Set your current folder to one for which you have write access.

  2. Copy the example code to your folder. Then, open colorPalette.m in the Editor:

    copyfile(fullfile(docroot, 'techdoc','creating_guis','examples',...
       'colorPalette.m')), fileattrib('colorPalette.m', '+w');
    copyfile(fullfile(docroot, 'techdoc','creating_guis','examples',...
       'iconRead.m')), fileattrib('iconRead.m', '+w');
    copyfile(fullfile(docroot, 'techdoc','creating_guis','examples',...
       'eraser.gif')), fileattrib('eraser.gif', '+w');
    edit colorPalette.m
    

    Caution   Do not modify and save the files to the examples folder from which you copied them.

Local Function Summary for Color Palette

The color palette example includes the callbacks listed in the following table.

Function

Description

colorCellCallback

Called by hPalettePanelSelectionChanged when any color cell is clicked.

eraserToolCallback

Called by hPalettePanelSelectionChanged when the Eraser button is clicked.

hMoreColorButtonCallback

Executes when the More Colors button is clicked. It calls uisetcolor to open the standard color-selection dialog box, and calls localUpdateColor to update the preview.

hPalettePanelSelectionChanged

Executes when the GUI user clicks on a new color. This is the SectionChangeFcn callback of the uibuttongroup that exclusively manages the tools and color cells that it contains. It calls the appropriate callback to service each of the tools and color cells.

The example also includes the helper functions listed in this table.

Function

Description

layoutComponent

Dynamically creates the Eraser tool and the color cells in the palette. It calls localDefineLayout.

localUpdateColor

Updates the preview of the selected color.

getSelectedColor

Returns the currently selected color which is then returned to the colorPalette caller.

localDefineLayout

Calculates the preferred color cell and tool sizes for the GUI. It calls localDefineColors and localDefineTools

localDefineTools

Defines the tools shown in the palette. In this example, the only tool is the Eraser button.

localDefineColors

Defines the colors that are shown in the array of color cells.

processUserInputs

Determines if the property in a property-value pair is supported. It calls localValidateInput.

localValidateInput

Validates the value in a property-value pair.

Code File Organization

The color palette code uses nested functions. Its code file is organized in the following sequence:

  1. Comments displayed in response to the help command.

  2. Data creation. Because the example uses nested functions, defining this data at the top level makes the data accessible to all functions without having to pass them as arguments.

  3. Command line input processing.

  4. GUI figure and component creation.

  5. GUI initialization.

  6. Callback definitions. These callbacks, which service the GUI components, are local functions of the colorPalette main function and so have access to the data and component handles created at the top level, without their having to be passed as arguments.

  7. Helper function definitions. These helper functions are local functions of the colorPalette main function and so have access to the data and component handles created at the top level, without their having to be passed as arguments.

GUI Programming Techniques

This topic explains the following GUI programming techniques as they are used in the creation of the colorPalette.

Pass Input Arguments to a GUI

Inputs to the GUI are custom property-value pairs. colorPalette allows one such property: Parent. The names are case-insensitive. The colorPalette syntax is

mGetColorFcn = colorPalette('Parent',hPaletteContainer)

Definition and Initialization of the Properties

The colorPalette function first defines a variable mInputArgs as varargin to accept the GUI user input arguments.

mInputArgs = varargin;  % Command line arguments when invoking
                        % the GUI

The colorPalette function then defines the valid custom properties in a 3-by-3 cell array.

mPropertyDefs = {...    % The supported custom property/value 
                        % pairs of this GUI
               'parent',   @localValidateInput, 'mPaletteParent';
  • The first column contains the property name.

  • The second column contains a function handle for the function, localValidateInput, that validates the input property values.

  • The third column is the local variable that holds the value of the property.

colorPalette then initializes the properties with default values.

mPaletteParent = [];  % Use input property 'parent' to initialize

Process the Input Arguments

The processUserInputs helper function processes the input property-value pairs. colorPalette calls processUserInputs before it creates the components, to determine the parent of the components.

% Process the command line input arguments supplied when 
% the GUI is invoked 
processUserInputs();
  1. processUserInputs sequences through the inputs, if any, and tries to match each property name to a string in the first column of the mPropertyDefs cell array.

  2. If it finds a match, processUserInputs assigns the value that was input for the property to its variable in the third column of the mPropertyDefs cell array.

  3. processUserInputs then calls the helper function specified in the second column of the mPropertyDefs cell array to validate the value that was passed in for the property.

Pass Output to a Caller on Returning

If a host GUI calls the colorPalette function with an output argument, it returns a function handle that the host GUI can call to get the currently selected color.

The host GUI calls colorPalette only once. The call creates the color palette in the specified parent and then returns the function handle.

The data definition section of the colorPalette code file creates a cell array to hold the output:

mOutputArgs = {};  % Variable for storing output when GUI returns

Just before returning, colorPalette assigns the function handle, mgetSelectedColor, to the cell array mOutputArgs and then assigns mOutputArgs to varargout to return the arguments.

mOutputArgs{} = @getSelectedColor;
if nargout>0
    [varargout{1:nargout}] = mOutputArgs{:};
end
Was this topic helpful?