Main Content

axtoolbar

Create axes toolbar

Description

example

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.

example

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

collapse all

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'});

Figure with zoom in, zoom out, and restore view buttons in the axes toolbar

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'});

Figure with two plots. The bottom plot has data tip and pan buttons in the axes toolbar.

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'});

Figure with two plots. The top plot has zoom in, zoom out, and restore view buttons in the axes toolbar.

Input Arguments

collapse all

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.

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 NameIconDescription
'export'Export icon

Display menu of export options.

'brush'Data brushing iconToggle data brushing mode.
'datacursor'Data cursor iconToggle data cursor mode.
'rotate'Rotate iconToggle rotate mode.
'pan'Pan iconToggle pan mode.
'zoomin'Zoom in iconToggle zoom-in mode.
'zoomout'Zoom out iconToggle zoom-out mode.
'restoreview'Restore view iconRestore 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 as icon: Save the content as a tightly cropped image or PDF.

  • Copy as image icon: Copy the content as an image.

  • Copy as vector graphic icon: 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.

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'

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

collapse all

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

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 Open in Figure Window button in the upper-right corner of the figure.

Version History

Introduced in R2018b