zoom

Enable zoom mode

Description

You can use zoom mode to explore data by interactively changing the limits of axes. Enable or disable zoom mode, and set other basic options, by using the zoom function. To further control zoom mode behavior, return and use a zoom object.

Most charts support zoom mode, including line, bar, histogram, and surface charts. Charts that support zoom mode typically display the zoom in and zoom out icons in the axes toolbar.

You can also interactively explore data using built-in axes interactions that are enabled by default. For example, you can zoom in and out of the view of the axes by scrolling or pinching. Built-in interactions do not require you to enable an interaction mode and respond faster than interaction modes. However, you can enable zoom mode to customize the zooming behavior. For more information about built-in interactions, see Control Chart Interactivity.

Creation

Syntax

zoom option

zoom

zoom(factor)

zoom(fig,___)

zoom(ax,___)

z = zoom

z = zoom(fig)

Description

zoom option sets the zoom mode for all axes in the current figure. For example, zoom on enables zoom mode, zoom xon enables zoom mode for the x-dimension only, and zoom off disables zoom mode.

When zoom mode is enabled, zoom the view of the axes using the cursor, the scroll wheel, or the keyboard.

Cursor — To zoom in, position your cursor where you want the center of the axes to be and click. To zoom out, hold Shift and click. To zoom into a rectangular region, click and drag. To return an axes object to its baseline zoom level, double-click within the axes.
Scroll wheel — To zoom in, scroll up. To zoom out, scroll down.
Keyboard — To zoom in, press the up arrow (↑) key. To zoom out, press the down arrow (↓) key.

Some built-in interactions remain enabled by default, regardless of the current interaction mode. To disable built-in zoom interactions that are independent of the zoom mode, use the disableDefaultInteractivity function.

example

zoom toggles the zoom mode. If zoom mode is disabled, then calling zoom restores the most recently used zoom option of on, xon, or yon.

zoom(factor) zooms the current axes by the specified zoom factor without affecting the zoom mode. Zoom in by specifying factor as a value greater than 1, for example, zoom(3). Zoom out by specifying factor as a value between 0 and 1, for example, zoom(0.5).

zoom(fig,___) sets the zoom mode for all axes in the specified figure for any of the previous syntaxes. Specify the additional argument as a zoom mode option or a zoom factor. For example, to enable zoom mode for all axes in the figure fig, use zoom(fig,'on'). To zoom all of the axes by a factor of 2, use zoom(fig,2).

zoom(ax,___) sets the zoom mode for the specified axes. Specify the additional argument as a zoom mode option or a zoom factor. For example, to enable zoom mode for the axes ax, use zoom(ax,'on'). To zoom the axes ax by a factor of 2, use zoom(ax,2). Use this syntax with apps created in App Designer and using the uifigure function. (since R2023a)

z = zoom creates a zoom object for the current figure. This syntax is useful for customizing the zoom mode, motion, and direction.

example

z = zoom(fig) creates a zoom object for the specified figure.

example

Input Arguments

expand all

`option` — Zoom mode option
`'on'` | `'off'` | `'reset'` | `'out'` | `'xon'` | `'yon'` | `'toggle'`

Zoom mode option, specified as one of these values:

'on' — Enable zoom mode.
'off' — Disable zoom mode. Some built-in interactions remain enabled by default, regardless of the current interaction mode. To disable built-in zoom interactions that are independent of the zoom mode, use the disableDefaultInteractivity function.
'reset' — Set the current zoom level as the baseline zoom level. Once you set the baseline zoom level, calling zoom out, double-clicking in the axes, or clicking the Restore View icon from the axes toolbar returns axes to this zoom level.
'out' — Return the current axes to its baseline zoom level.
'xon' — Enable zoom mode for the x-dimension only.
'yon' — Enable zoom mode for the y-dimension only.
'toggle' — Toggle the zoom mode. If zoom mode is disabled, then 'toggle' restores the most recently used zoom option of 'on', 'xon', or 'yon'. Using this option is the same as calling zoom without any arguments.

`factor` — Zoom factor
positive number

Zoom factor, specified as a positive number. Zoom in by specifying factor as a number greater than 1. Zoom out by specifying factor as a number between 0 and 1. In this case, the axes zoom out by 1/factor.

`fig` — Target figure
`Figure` object

Target figure, specified as a Figure object. Specifying a target figure sets the mode for all current or future Axes children.

`ax` — Target axes
`Axes` object

Target axes, specified as an Axes object.

Properties

expand all

`Motion` — Dimension
`'both'` (default) | `'horizontal'` | `'vertical'`

Dimension to allow zooming in and out, specified as one of these values:

'both' — Allow zooming in the x-dimension and the y-dimension.
'horizontal' — Allow zooming in the x-dimension only.
'vertical' — Allow zooming in the y-dimension only.

This property affects only axes in a 2-D view, such as when you call view([0 90]). To control the zoom dimension in 3-D views, use a ZoomInteraction object.

`Direction` — Direction
`'in'` (default) | `'out'`

Direction of zooming, specified as one of these values:

'in' — Click to zoom in.
'out' — Click to zoom out.

When zoom mode is enabled, you can use the scroll wheel to zoom in or out, regardless of the value of Direction.

`RightClickAction` — Action to perform on right-click
`'PostContextMenu'` (default) | `'InverseZoom'`

Action to perform on right-click, specified as one of these values:

'PostContextMenu' — Display a context menu.
'InverseZoom' — Zoom out on right-click.

Setting the RightClickAction property sets the default for future zoom objects. The value of RightClickAction persists between MATLAB^® sessions.

`ContextMenu` — Context menu
empty `GraphicsPlaceholder` array (default) | `ContextMenu` object

Context menu, specified as a ContextMenu object. Use this property to display a context menu when you right-click in axes where zoom mode is enabled. Create the context menu using the uicontextmenu function.

This property has no effect if the RightClickAction property has a value of 'InverseZoom'.

`ButtonDownFilter` — Zoom suppression callback
[ ] (default) | function handle | cell array | character vector

Zoom suppression callback, specified as one of these values:

Function handle
Cell array containing a function handle and additional arguments
Character vector containing a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)

Use this property to suppress zooming under conditions that you define. A numeric or logical output of 1 (true) suppresses zooming, and a numeric or logical output of 0 (false) allows zooming. If you specify this property using a function handle, then MATLAB passes two arguments to the callback function:

axes — The axes object in which you are zooming.
eventData — Empty argument. Replace it with the tilde character (~) in the function definition to indicate that this argument is not used.

If you specify this property using a function handle, then you must assign the function output to a variable.

For more information about callbacks, see Create Callbacks for Graphics Objects.

`ActionPreCallback` — Function to execute before zooming
[ ] (default) | function handle | cell array | character vector

Function to execute before zooming, specified as one of these values:

Function handle
Cell array containing a function handle and additional arguments
Character vector containing a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)

Use this property to execute code as you start zooming in or out. If you specify this property using a function handle, then MATLAB passes two arguments to the callback function:

figure — Figure object in which you are zooming.
axesStruct — Structure that contains one field, Axes, the axes object in which you are zooming. If you do not use this argument in your callback function, then replace it with the tilde character (~).

For more information about callbacks, see Create Callbacks for Graphics Objects.

`ActionPostCallback` — Function to execute after zooming
[ ] (default) | function handle | cell array | character vector

Function to execute after zooming, specified as one of these values:

Function handle
Cell array containing a function handle and additional arguments
Character vector containing a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)

Use this property to execute code after you finish zooming. If you specify this property using a function handle, then MATLAB passes two arguments to the callback function:

figure — Figure object in which you are zooming.
axesStruct — Structure that contains one field, Axes, the axes object in which you are zooming. If you do not use this argument in your callback function, then replace it with the tilde character (~).

For more information about callbacks, see Create Callbacks for Graphics Objects.

`Enable` — Zoom mode state
`'off'` (default) | `'on'` | on/off logical value

Zoom mode state, 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 OnOffSwitchState.

`FigureHandle` — Figure object
`Figure` object

This property is read-only.

Figure object that you specified when creating the zoom object. If you did not specify a figure, then FigureHandle is the figure that was current when you created the zoom object.

`UseLegacyExplorationModes` — Legacy mode
`'off'` (default) | `'on'` | on/off logical value

Legacy mode, 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 OnOffSwitchState.

This property applies only to zoom objects for figures created using the uifigure function or in MATLAB Online™. Setting this property to 'on' changes the behavior of interaction modes in UI figures so they match the behavior of modes in traditional figures. For more information, see enableLegacyExplorationModes.

Once this property is set to 'on', it cannot be changed back to 'off'.

Object Functions

Use zoom object functions to customize the zooming behavior of axes objects within a figure. For all of these functions, the axes and zoom objects must be associated with the same figure.

`setAllowAxesZoom`	The `setAllowAxesZoom` function sets permission to zoom axes. Calling `setAllowAxesZoom(z,axes,tf)` on the zoom object `z`, with a vector of axes objects `axes` and a logical scalar `tf` as inputs, either allows or disallows a zoom operation on the axes objects. Enabling zoom mode for axes using `setAllowAxesZoom` does not enable zoom mode for the figure. To do this, set the `Enable` property of the zoom object.
`isAllowAxesZoom`	The `isAllowAxesZoom` function queries permission to zoom axes. Calling `tf = isAllowAxesZoom(z,axes)` on the zoom object `z`, with a vector of axes objects `axes` as an input, returns a logical array `tf` of the same size as `axes`. `tf` indicates whether a zoom operation is permitted on the axes objects. Returning the zoom mode of axes using `isAllowAxesZoom` does not return the zoom mode for the figure. To do this, access the `Enable` property of the zoom object.
`setAxesZoomConstraint`	The `setAxesZoomConstraint` function sets the zoom dimension of axes. Calling `setAxesZoomConstraint(z,axes,d)` on the zoom object `z`, with a vector of axes objects `axes` and a dimension value scalar `d` as inputs, sets the zoom dimension of the axes objects as one of these dimension values: `'x'`, `'y'`, `'z'`, `'xy'`, `'xz'`, `'yz'`, or `'unconstrained'`. Setting the zoom dimension for axes using `setAxesZoomConstraint` does not set the zoom dimension for the figure. To do this, set the `Motion` property of the zoom object.
`getAxesZoomConstraint`	The `getAxesZoomConstraint` function returns the zoom dimension of axes. Calling `d = getAxesZoomConstraint(z,axes)` on the zoom object `z`, with a vector of axes objects `axes` as an input, returns a cell array `d` indicating the zoom dimension of each axes object. Returning the zoom dimension of axes using `getAxesZoomConstraint` does not return the zoom dimension for the figure. To do this, access the `Motion` property of the zoom object.
`setAxes3DPanAndZoomStyle`	The `setAxes3DPanAndZoomStyle` function sets the zoom style. Calling `setAxes3DPanAndZoomStyle(z,axes,s)` on the zoom object `z`, with a vector of axes objects `axes` and a zoom style character array `s` as inputs, sets the zoom style of the axes objects. By default, the zoom style is `'limits'`, which zooms by modifying the axes limits. Specify the zoom style as `'camera'` to zoom by modifying the camera view angle. For more information about the camera view angle, see Camera Graphics Terminology.
`getAxes3DPanAndZoomStyle`	The `getAxes3DPanAndZoomStyle` function returns the zoom style. Calling `s = getAxes3DPanAndZoomStyle(z,axes)` on the zoom object `z`, with a vector of axes objects `axes` as an input, returns a cell array `s` indicating the zoom style of each axes object.
`setAxesZoomMotion` (not recommended)	This function is not recommended. Use `setAxesZoomConstraint` instead. Calling `setAxesZoomMotion(z,axes,d)` on the zoom object `z`, with a vector of axes objects `axes` and a zoom dimension `d` as inputs, sets the zoom dimension of the axes objects as one of these dimension values: `'horizontal'`, `'vertical'`, or `'both'`. The axes zoom dimension that is set by `setAxesZoomMotion` is not the same as the figure zoom dimension that is set using the `Motion` property.
`getAxesZoomMotion` (not recommended)	This function is not recommended. Use `getAxesZoomConstraint` instead. Calling `d = getAxesZoomMotion(z,axes)` on the zoom object `z`, with a vector of axes objects `axes` as an input, returns a cell array `d` indicating the zoom dimension of each axes object. The axes zoom dimension that is returned using `getAxesZoomMotion` is not the same as the figure zoom dimension that is returned using the `Motion` property.

Examples

collapse all

Set Baseline Zoom Level

Plot a surface and enable zoom mode.

surf(peaks)
zoom on

A surface with several peaks

Zoom into the tallest peak by clicking on it. Then, set the baseline zoom level. Future calls to zoom out, double-clicking in the axes, or clicking the Restore View icon from the axes toolbar return axes to this baseline zoom level.

zoom reset

The surface zoomed into the tallest peak

Zoom into the highest peak a second time by clicking on it. Then, return to the baseline zoom level you set by zooming out.

zoom out

Constrain Zoom in Tiled Chart Layout

Create four axes in a tiled chart layout, and assign each a different zoom behavior. Then, interactively zoom the axes.

tiledlayout(2,2)
ax1 = nexttile;
plot(1:10);
z = zoom;

ax2 = nexttile;
plot(rand(3));
setAllowAxesZoom(z,ax2,false);

ax3 = nexttile;
surf(peaks);
setAxesZoomConstraint(z,ax3,'xy');

ax4 = nexttile;
contour(peaks);
setAxesZoomMotion(z,ax4,'horizontal');

Create Mode Context Menu

Plot a surface and create a context menu using the uicontextmenu function.

surf(peaks)
cm = uicontextmenu;

A surface with several peaks

Then, add an item to the menu. Specify a label and a callback that closes the figure.

m = uimenu(cm);
m.Label = 'Close figure';
f = gcf;
m.Callback = @(src,event)close(f);

Create a zoom object. Add the context menu to the zoom object by setting its ContextMenu property. Then, enable zoom mode.

z = zoom(f);
z.ContextMenu = cm;
z.Enable = 'on';

Close the figure by right-clicking and selecting Close figure.

More About

expand all

Changing Callback Functions

You can create a zoom object and use it to customize the behavior of different axes. You can also change its callback functions on the fly.

Note

Do not change figure callbacks within an interactive mode. While a mode is active (such as when zoom mode is enabled), you will receive a warning if you attempt to change any of the figure's keyboard callbacks or window callbacks, and the operation will not succeed. The one exception to this rule is the figure WindowButtonMotionFcn callback, which can be changed from within a mode. Therefore, if you are creating a UI that updates a figure's callbacks, the UI should keep track of and check which interactive mode is active, if any, before attempting to change a callback.

When you assign different zoom behaviors to different axes in a figure by using mode objects and then link them using the linkaxes function, the behavior of the axes you manipulate with the mouse carries over to the linked axes, regardless of the behavior you previously set for the other axes.

Alternative Functionality

Axes Toolbar

For some charts, enable zoom mode by clicking the zoom in or zoom out icons in the axes toolbar.

Version History

Introduced before R2006a

expand all

R2023a: Set zoom mode for specified axes in apps

For apps created in App Designer and using the uifigure function, set the zoom mode for axes by specifying the axes as the first input of zoom. When setting the zoom mode for axes, the function does not return a zoom object.

R2020a: `UIContextMenu` property is not recommended

Starting in R2020a, using the UIContextMenu property to assign a context menu to a graphics object or UI component is not recommended. Use the ContextMenu property instead. The property values are the same.

There are no plans to remove support for the UIContextMenu property at this time. However, the UIContextMenu property no longer appears in the list returned by calling the get function on a graphics object or UI component.

R2018b: Explore data with zooming enabled by default

Interactively explore your data using built-in axes interactions that are enabled by default. For example, you can use the scroll wheel to zoom into your data without enabling zoom mode. For more information, see Control Chart Interactivity.

Previously, no axes interactions were enabled by default.

zoom

Description

Creation

Syntax

Description

Input Arguments

`option` — Zoom mode option
`'on'` | `'off'` | `'reset'` | `'out'` | `'xon'` | `'yon'` | `'toggle'`

`factor` — Zoom factor
positive number

`fig` — Target figure
`Figure` object

`ax` — Target axes
`Axes` object

Properties

`Motion` — Dimension
`'both'` (default) | `'horizontal'` | `'vertical'`

`Direction` — Direction
`'in'` (default) | `'out'`

`RightClickAction` — Action to perform on right-click
`'PostContextMenu'` (default) | `'InverseZoom'`

`ContextMenu` — Context menu
empty `GraphicsPlaceholder` array (default) | `ContextMenu` object

`ButtonDownFilter` — Zoom suppression callback
[ ] (default) | function handle | cell array | character vector

`ActionPreCallback` — Function to execute before zooming
[ ] (default) | function handle | cell array | character vector

`ActionPostCallback` — Function to execute after zooming
[ ] (default) | function handle | cell array | character vector

`Enable` — Zoom mode state
`'off'` (default) | `'on'` | on/off logical value

`FigureHandle` — Figure object
`Figure` object

`UseLegacyExplorationModes` — Legacy mode
`'off'` (default) | `'on'` | on/off logical value

Object Functions

Examples

Set Baseline Zoom Level

Constrain Zoom in Tiled Chart Layout

Create Mode Context Menu

More About

Changing Callback Functions

Alternative Functionality

Axes Toolbar

Version History

R2023a: Set zoom mode for specified axes in apps

R2020a: `UIContextMenu` property is not recommended

R2018b: Explore data with zooming enabled by default

See Also

Functions

Topics

zoom

Description

Creation

Syntax

Description

Input Arguments

option — Zoom mode option 'on' | 'off' | 'reset' | 'out' | 'xon' | 'yon' | 'toggle'

factor — Zoom factor positive number

fig — Target figure Figure object

ax — Target axes Axes object

Properties

Motion — Dimension 'both' (default) | 'horizontal' | 'vertical'

Direction — Direction 'in' (default) | 'out'

RightClickAction — Action to perform on right-click 'PostContextMenu' (default) | 'InverseZoom'

ContextMenu — Context menu empty GraphicsPlaceholder array (default) | ContextMenu object

ButtonDownFilter — Zoom suppression callback [ ] (default) | function handle | cell array | character vector

ActionPreCallback — Function to execute before zooming [ ] (default) | function handle | cell array | character vector

ActionPostCallback — Function to execute after zooming [ ] (default) | function handle | cell array | character vector

Enable — Zoom mode state 'off' (default) | 'on' | on/off logical value

FigureHandle — Figure object Figure object

UseLegacyExplorationModes — Legacy mode 'off' (default) | 'on' | on/off logical value

Object Functions

Examples

Set Baseline Zoom Level

Constrain Zoom in Tiled Chart Layout

Create Mode Context Menu

More About

Changing Callback Functions

Alternative Functionality

Axes Toolbar

Version History

R2023a: Set zoom mode for specified axes in apps

R2020a: UIContextMenu property is not recommended

R2018b: Explore data with zooming enabled by default

See Also

Functions

Topics

`option` — Zoom mode option
`'on'` | `'off'` | `'reset'` | `'out'` | `'xon'` | `'yon'` | `'toggle'`

`factor` — Zoom factor
positive number

`fig` — Target figure
`Figure` object

`ax` — Target axes
`Axes` object

`Motion` — Dimension
`'both'` (default) | `'horizontal'` | `'vertical'`

`Direction` — Direction
`'in'` (default) | `'out'`

`RightClickAction` — Action to perform on right-click
`'PostContextMenu'` (default) | `'InverseZoom'`

`ContextMenu` — Context menu
empty `GraphicsPlaceholder` array (default) | `ContextMenu` object

`ButtonDownFilter` — Zoom suppression callback
[ ] (default) | function handle | cell array | character vector

`ActionPreCallback` — Function to execute before zooming
[ ] (default) | function handle | cell array | character vector

`ActionPostCallback` — Function to execute after zooming
[ ] (default) | function handle | cell array | character vector

`Enable` — Zoom mode state
`'off'` (default) | `'on'` | on/off logical value

`FigureHandle` — Figure object
`Figure` object

`UseLegacyExplorationModes` — Legacy mode
`'off'` (default) | `'on'` | on/off logical value

R2020a: `UIContextMenu` property is not recommended