MATLAB®

Color Palette

The Example

This example creates a GUI, colorPalette, that enables a user to select a color from a color palette or display the standard color selection dialog box. Another example, Icon Editor, embeds the colorPalette, as the child of a panel, in a GUI you can use to design an icon.

The colorPalette function populates a GUI figure or panel with a color palette. The figure below shows the palette as the child of a figure.

The Components

The colorPalette includes the following components:

• An array of color cells defined as toggle buttons

• An Eraser toggle button with the icon

• A button group that contains the array of color cells and the eraser button. The button group provides exclusive management of these toggle buttons.

• A More Colors push button

• A preview of the selected color, below the color cells, defined as a text component

• Text components to specify the red, blue, and green color values

Using the Color Palette

These are the basic steps for using the color palette.

1. Clicking a color cell toggle button:

   • Displays the selected color in the preview area.

   • The red, green, and blue values for the newly selected color are displayed in the R, G, and B fields to the right of the preview area.

   • Causes colorPalette to return a function handle that the host GUI can use to get the currently selected color.

2. Clicking the Eraser toggle button, causes colorPalette to return a value, NaN, that the host GUI can use to remove color from a data point.

   

3. Clicking the More Colors button displays the standard dialog box for setting a color.

   

Calling the colorPalette Function

You can call the colorPalette function with a statement such as

mGetColorFcn = colorPalette('Parent',hPaletteContainer)

The colorPalette function accepts property value pairs as input arguments. Only the custom property 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.

colorPalette returns a function handle that the host GUI can call to get the currently selected color. The host GUI can use the returned function handle at any time before the color palette is destroyed. For more information, see Sharing Data Between Two GUIs for implementation details. Icon Editor is an example of a host GUI that uses the colorPalette.

Back to Top

Techniques Used in the Example

This example illustrates the following techniques:

• Retrieving output from the GUI when it returns.

• Supporting custom input property/value pairs with data validation.

• Sharing data between two GUIs

See Icon Editor for examples of these and other programming techniques.

Note   This example uses nested functions. For information about using nested functions, see Nested Functions in the MATLAB® Programming Fundamentals documentation.

Back to Top

View and Run the Completed GUI M-File

If you are reading this in the MATLAB Help browser, you can click the following link to display the MATLAB Editor with a complete listing of the code that is discussed in the following sections.

Note   The following link executes MATLAB commands and is designed to work within the MATLAB Help browser. If you are reading this online or in PDF, you should go to the corresponding section in the MATLAB Help Browser to use the link.

• Click here to display the main GUI M-file in the MATLAB Editor.

• Click here to run the colorPalette GUI.

Back to Top

Subfunction Summary

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

Note   Three eventdata fields are defined for use with button groups (uibuttongroup). These fields enable you to determine the previous and current radio or toggle button selections maintained by the button group. See SelectionChangeFcn in the Uibuttongroup Properties reference page for more information.

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

Back to Top

M-File Structure

The colorPalette is programmed using nested functions. Its M-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. Return output if it is requested.

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

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

Note   For information about using nested functions, see Nested Functions in the MATLAB Programming Fundamentals documentation.

Back to Top

GUI Programming Techniques

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

• Passing Input Arguments to a GUI

• Passing Output to a Caller on Returning

• Sharing Data Between Two GUIs

See Icon Editor for additional examples of these and other programming techniques.

Passing 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 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

Processing 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.

Passing 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 host GUI can call the returned function at any time before the color palette is destroyed.

The data definition section of the colorPalette M-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

Sharing Data Between Two GUIs

The iconEditor embeds a GUI, the colorPalette, to enable the user to select colors for the icon cells. The colorPalette returns a function handle the iconEditor. The iconEditor can then call the returned function at any time to get the selected color.

The colorPalette GUI.   The colorPalette function defines a cell array, mOutputArgs, to hold its output arguments.

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

Just before returning, colorPalette assigns mOutputArgs the function handle for its getSelectedColor helper function and then assigns mOutputArgs to varargout to return the arguments.

% Return user defined output if it is requested
mOutputArgs{1} =@getSelectedColor;
if nargout>0
    [varargout{1:nargout}] = mOutputArgs{:};
end

The iconEditor executes the colorPalette's getSeclectedColor function whenever it invokes the function that colorPalette returns to it.

function color = getSelectedColor
% function returns the currently selected color in this
% colorPlatte
    color = mSelectedColor;

The iconEditor GUI.   The iconEditor function calls colorPalette only once and specifies its parent to be a panel in the iconEditor.

% Host the ColorPalette in the PaletteContainer and keep the
% function handle for getting its selected color for editing 
% icon.
mGetColorFcn = colorPalette('parent', hPaletteContainer);

This call creates the colorPalette as a component of the iconEditor and then returns a function handle that iconEditor can call to get the currently selected color.

The iconEditor's localEditColor helper function calls mGetColorFcn, the function returned by colorPalette, to execute the colorPalette's getSelectedColor function.

function localEditColor
% helper function that changes the color of an icon data 
% point to that of the currently selected color in 
% colorPalette 
    if mIsEditingIcon
        pt = get(hIconEditAxes,'currentpoint');
        x = ceil(pt(1,1));
        y = ceil(pt(1,2));
        color = mGetColorFcn();

        % update color of the selected block
        mIconCData(y, x,:) = color;

        localUpdateIconPlot();
    end
end

Back to Top

GUI with Axes, Menu, and Toolbar

Icon Editor