axtoolbar

Create axes toolbar

Syntax

tb = axtoolbar(buttons)

tb = axtoolbar(ax,buttons)

tb = axtoolbar

tb = axtoolbar(ax)

tb = axtoolbar(___,Name,Value)

[tb,btns] = axtoolbar(___)

Description

tb = axtoolbar(buttons) replaces the default toolbar that appears above the top-right corner of the current axes with a toolbar that contains only the specified buttons. For example, axtoolbar({'pan','restoreview'}) specifies a button to pan and a button to restore the original view. The function returns the AxesToolbar object created.

tb = axtoolbar(ax,buttons) replaces the toolbar for the axes or tiled chart layout specified by ax, instead of the current axes.

tb = axtoolbar replaces the toolbar for the current axes with an empty toolbar.

tb = axtoolbar(ax) replaces the toolbar for the specified axes or tiled chart layout with an empty toolbar, instead of the current axes.

tb = axtoolbar(___,Name,Value) specifies toolbar properties using one or more name-value arguments.

[tb,btns] = axtoolbar(___) also returns the toolbar button objects created, which are either ToolbarStateButton, ToolbarPushButton, or ToolbarDropdown objects. You can use the objects to modify the toolbar and toolbar buttons after you create them.

Examples

Create Toolbar with Subset of Default Buttons

Create a plot. Replace the standard axes toolbar with a custom toolbar that includes buttons to zoom in, zoom out, and restore the view. Return the AxesToolbar object and the button objects created as output arguments.

plot(magic(5))
[tb,btns] = axtoolbar({'zoomin','zoomout','restoreview'});

Create Toolbar for Specific Axes Object

Create two subplots with a custom toolbar for each one.

First, create two subplots and assign the Axes objects to the variables ax1 and ax2. Replace the toolbar for the upper subplot with a custom toolbar by specifying ax1 as the first input argument to the axtoolbar function. Then, replace the toolbar for the lower subplot. Hover over each subplot to see its toolbar.

ax1 = subplot(2,1,1);
plot(ax1,magic(5))
[tb1,btns1] = axtoolbar(ax1,{'zoomin','zoomout','restoreview'});

ax2 = subplot(2,1,2);
plot(ax2,magic(5))
[tb2,btns2] = axtoolbar(ax2,{'pan','datacursor'});

Create Toolbar for Tiled Chart Layout

Create a tiled chart layout with one axes toolbar.

First, create a 2-by-1 layout and display a different chart in each tile. Then, create a custom axes toolbar for the tiled chart layout. Display the toolbar by hovering over the layout.

t = tiledlayout(2,1);
nexttile
plot(magic(5));
nexttile
plot(magic(5));

tb = axtoolbar(t,{'zoomin','zoomout','restoreview'});

Input Arguments

ax — Target axes

Axes object | TiledChartLayout object

Target axes, specified as one of the following:

• Axes object – Create a custom axes toolbar for the specified set of axes.

• TiledChartLayout object – Create a single axes toolbar that applies to all axes in the specified tiled chart layout.

buttons — Toolbar buttons

'default' | cell array with one or more button names

Toolbar buttons, specified as 'default' for the default set of buttons or a cell array containing one or more button names listed in this table. The buttons appear in a standard order on the toolbar regardless of the order in which you specify them. Each button can appear only once in the toolbar.

Button Name	Icon	Description
'export'		Display menu of export options.
'brush'		Toggle data brushing mode.
'datacursor'		Toggle data cursor mode.
'rotate'		Toggle rotate mode.
'pan'		Toggle pan mode.
'zoomin'		Toggle zoom-in mode.
'zoomout'		Toggle zoom-out mode.
'restoreview'		Restore original view of axes or tiled chart layout.

Hovering over the 'export' button reveals a drop-down menu with options for exporting the axes or tiled chart layout content:

• : Save the content as a tightly cropped image or PDF.

• : Copy the content as an image.

• : Copy the content as a vector graphic.

Example: axtoolbar({'zoomin','zoomout','restoreview'})

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: axtoolbar({'zoomin','zoomout'},'SelectionChangedFcn',@mycallback)

Note

The properties listed here are only a subset. For a full list, see AxesToolbar Properties.

SelectionChangedFcn — Callback for selection changes

'' (default) | function handle | cell array | character vector

Callback for selection changes, specified as one of these values:

• A function handle.

• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• A character vector containing a valid MATLAB^® expression (not recommended). MATLAB evaluates this expression in the base workspace.

This callback executes when you click a state button. It does not execute if a state button Value property changes programmatically.

This callback function can access specific information about interaction with the buttons. MATLAB passes this information in a SelectionChangedEventData object as the second argument to your callback function. You can query the object properties using dot notation. For example, event.Selection returns the currently selected button. The SelectionChangedEventData object is not available to callback functions specified as character vectors.

This table lists the properties of the SelectionChangedEventData object.

Property	Description
Axes	Array of Axes objects associated with the toolbar
Selection	Currently selected button
PreviousSelection	Previously selected button
Source	AxesToolbar object
EventName	'SelectionChanged'

Visible — State of visibility

"on" (default) | on/off logical value

State of visibility, specified as "on" or "off", or as numeric or logical 1 (true) or 0 (false). 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.

• "on" — Display the object.

• "off" — Hide the object without deleting it. You still can access the properties of an invisible object.

Output Arguments

tb — Toolbar

AxesToolbar object

Toolbar, returned as an AxesToolbar object. Use tb to modify the toolbar after you create it. For a list of properties, see AxesToolbar Properties.

btns — Toolbar buttons

graphics array

Toolbar buttons, returned as a graphics array containing one or more ToolbarPushButton, ToolbarStateButton, or ToolbarDropdown objects. Use the elements in the btns array to modify the buttons after you create them. For a list of properties, see ToolbarStateButton Properties, ToolbarPushButton Properties, and ToolbarDropdown Properties.

Limitations

• Custom toolbars do not appear in figures in the Live Editor. To see the custom toolbar, open the figure in a separate figure window by clicking the button in the upper-right corner of the figure.

Version History

Introduced in R2018b