uipushtool

Create push tool in toolbar

collapse all in page

Syntax

pt = uipushtool
pt = uipushtool(parent)
pt = uipushtool(___,Name,Value)

Description

pt = uipushtool creates a push tool in the toolbar of the current figure and returns the PushTool object.

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.

Push tools behave like push buttons. When you click them, they appear to depress until you release the mouse button.

pt = uipushtool(parent) creates a push tool in the specified parent toolbar.

example

pt = uipushtool(___,Name,Value) creates a push tool with property values specified using one or more name-value arguments. Specify name-value arguments with either of the previous syntaxes.

example

Examples

collapse all

Create a UI figure by calling the uifigure function. Create a toolbar in the UI figure.

fig = uifigure;
tb = uitoolbar(fig);

UI figure with an empty toolbar

Add a push tool to the toolbar. The push tool displays the default icon.

pt = uipushtool(tb);

UI figure that displays a toolbar and a push tool with the default icon

Add an icon to the push tool by setting the Icon property to the image file peppers.png.

pt.Icon = "peppers.png";

UI figure that displays a toolbar and a push tool with an image of peppers

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 push tool in the toolbar. Read a new icon from the indexed image file, matlabicon.gif. Convert the indexed image to an RGB truecolor image array. Add the icon to the push tool by setting the CData property to the truecolor image array.

pt = uipushtool(tb);

[img,map] = imread(fullfile(matlabroot,...
            'toolbox','matlab','icons','matlabicon.gif'));
ptImage = ind2rgb(img,map);

pt.CData = ptImage;

Figure that displays the default toolbar and another toolbar below it that contains a push tool with the MathWorks logo.

Create a push tool that opens the uisetcolor dialog box when you click it. Change the background color of the UI figure to the color selected from the color picker.

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

  • Create a UI figure.

  • Create a toolbar in the UI figure.

  • Create a push tool in the toolbar.

  • Add an appropriate icon to the push tool by setting the Icon property value to the full file path to paintbrush.gif.

  • Create a tooltip for the push tool.

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

  • Create a callback function called colorToolClicked. In it, call the uisetcolor function so that a color picker dialog box opens when you click the push tool in the toolbar. Set the default color of the color picker to be the color of the UI figure and specify the title of the color picker as 'Select UI Figure Color'. Make the UI figure the current figure so that it displays on top of all other figures.

function colorPickerPushTool
fig = uifigure('Position',[350 500 400 300]);
tb = uitoolbar(fig);

pt = uipushtool(tb);
pt.Icon = fullfile(matlabroot,'toolbox','matlab','icons','paintbrush.gif');
pt.Tooltip = 'Change UI Figure Color';
pt.ClickedCallback = @colorToolClicked;

    function colorToolClicked(src,event)
        c = uisetcolor(fig,'Select UI Figure Color');
        figure(fig)
    end

end

Run colorPickerPushTool. Click the push tool to open the color picker. Then, select a color to change the background color of the UI figure.

colorPickerPushTool

UI figure that displays a paintbrush icon in a toolbar push tool. The color picker dialog box displays to the right of the UI figure.

Input Arguments

collapse all

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

If a parent toolbar is not specified, then MATLAB creates a push tool in the toolbar of the current figure. 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 push tool in the default figure tool bar.

If there is no current figure, then MATLAB creates a figure using the figure function 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

collapse all

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.

Example: uitoolbar(Separator="on") sets the separator line mode to 'on'.

Note

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

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.

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.

Note

The Icon property is recommended over the CData property for specifying push and toggle tool icons, because it supports more image formats.

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.

Separator line mode, 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.

Setting this property to 'on' draws a dividing line to the left of a tool in the toolbar.

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

  • Unlike UIControl push buttons, push tools do not set the figure SelectionType property to 'open' on the second click.

Version History

Introduced before R2006a

expand all

See Also

Functions

Properties