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

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

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'

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 a PNG image.

  • : Copy the content as a vector graphic.

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

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

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 one of these values:

  • '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 button in the upper-right corner of the figure.

Introduced in R2018b