Main Content

uitoggletool

Create toggle tool in toolbar

collapse all in page

Syntax

tt = uitoggletool
tt = uitoggletool(parent)
tt = uitoggletool(___,Name,Value)

Description

tt = uitoggletool creates a toggle tool in the toolbar of the current figure and returns the ToggleTool object.

The current figure must be one created with the figure function. If the current figure does not have a child toolbar, then MATLAB® creates one in the current figure to serve as the parent. If a figure created with the figure function does not exist, then MATLAB creates one and calls the uitoolbar function to create a toolbar to serve as the parent.

Toggle tools have two states: 'off' or 'on'. The state of the button changes every time you click it.

tt = uitoggletool(parent) creates a toggle tool in the specified parent toolbar.

example

tt = uitoggletool(___,Name,Value) creates a toggle tool with property values specified using one or more name-value pair arguments. Specify name-value pairs with either of the previous syntaxes.

example

Examples

collapse all

Create a figure by calling the figure function. Add a toolbar to the figure. It appears below the default figure toolbar.

f = figure;
tb = uitoolbar(f);

Figure that displays the default toolbar and another empty toolbar below it.

Create a toggle tool in the toolbar. Create a 16-by-16-by-3 array of zeroes to be its icon. Set the CData property value to this array to display a black square icon in the toggle tool.

tt = uitoggletool(tb);
ttImage = zeros(16,16,3);
tt.CData = ttImage;

Figure that displays the default toolbar and a custom toolbar below it. The custom toolbar displays a black square as a toggle tool.

Create a toggle tool that changes its icon and the background color of a UI figure each time you click it.

First, create a program file called toggleColor.m. Within the program file:

  • Create a UI figure.

  • Create a toolbar in the UI figure.

  • Add a toggle tool to the toolbar.

  • Create a blue truecolor image array. Set the toggle tool Icon property value to it.

  • Set the ClickedCallback property to a function handle that references a callback function called toggleFigureColor.

  • Create a callback function called toggleFigureColor. In it, query the value of the State property for the toggle tool. If the state is 'on', change the background color of the figure to blue and make the toggle tool black. Similarly, if the state is 'off', then change the figure background color to black and the make the toggle tool blue.

function toggleColor
fig = uifigure;
tb = uitoolbar(fig);
tt = uitoggletool(tb);

ttImage = zeros(16,16,3);
ttImage(:,:,3) = ones(16);
tt.Icon = ttImage;
tt.ClickedCallback = @toggleFigureColor;

    function toggleFigureColor(src,event)
        state = src.State;
        
        if strcmp(state,'on')
            fig.Color = 'blue';
            tt.Icon = zeros(16,16,3);
        else
            fig.Color = 'black';
            tt.Icon = ttImage;
        end
        
    end

end

Run toggleColor. Click the toggle tool to change the background color of the figure.

toggleColor
UI figure that displays a toolbar and a toggle tool with a blue square icon.

Input Arguments

collapse all

Parent toolbar, specified as a Toolbar object. Use this property to specify the parent toolbar when creating a toggle tool or to move an existing tool to a different tool bar.

If a parent toolbar is not specified, then MATLAB creates a toggle tool in the toolbar of the current figure. The current figure must be one created with the figure function. If the current figure does not have a child toolbar, then MATLAB creates one in the current figure to serve as the parent. MATLAB does not create the toggle tool in the default figure tool bar.

If a figure created with the figure function does not exist, then MATLAB creates one and calls the uitoolbar function to create a toolbar that serves as the parent.

If you add multiple push tools or toggle tools to a toolbar, they are added left to right, in the order that they are created.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'Separator','on' sets the separator line mode to 'on'.

Note

The properties listed here are only a subset. For a complete list, see ToggleTool.

Toggle button state, specified as 'off' or 'on', or as numeric or logical 0 (false) or 1 (true). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

When this property value is 'on', the toggle button appears in the down (depressed) position. When this property value is 'off', the toggle button appears in the up position. Changing the state causes the appropriate OnCallback or OffCallback function to execute.

Icon source or file, specified as a character vector, string scalar, or an m-by-n-by-3 truecolor image array. If you specify a character vector or string scalar, it can be an image file name on the MATLAB path or a full path to an image file. If you plan to share your app with others, put the image file on the MATLAB path to facilitate app packaging. Supported image formats include JPEG, PNG, GIF, and SVG.

If you specify an m-by-n-by-3 array, it is interpreted as a truecolor image array. For more information about truecolor image arrays, see Working with Image Types in MATLAB.

If the image you specify is larger than 16-by-16 pixels, then the Icon property scales the image down so that the entire image fits within the tool. If the image you specify is smaller than 16-by-16 pixels, it is not scaled up to fit the available space.

The Icon property is supported only in App Designer and uifigure-based apps. If the Icon and CData properties are both set, then the CData property is ignored.

Example: 'icon.png' specifies an image file on the MATLAB path.

Example: 'C:\Documents\icon.png' specifies a full path to an image file.

Image array, specified as an m-by-n-by-3 truecolor image array. The values in the array can be:

  • Double-precision values between 0.0 and 1.0

  • uint8 values between 0 and 255

To prevent the image from appearing clipped or distorted, specify an array with m and n less than or equal to 16. If the image is clipped, then only the center 16-by-16 part of the array is used.

Note

For App Designer and uifigure-based apps, use the Icon property to specify push and toggle tool icons instead.

Tips

  • Toolbar objects (and their child PushTool and ToggleTool objects) do not appear in figures whose WindowStyle property is set to 'modal'. If a figure containing a toolbar child has its WindowStyle changed to 'modal', the toolbar child still exists in the Children property of the figure. However, the toolbar does not appear while WindowStyle is set to 'modal'.

Version History

Introduced before R2006a

expand all

See Also

Functions

Properties