Main Content

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

Description

example

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

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)

example

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.

Input Arguments

expand all

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.

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.

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

Target axes, specified as an Axes object.

Properties

expand all

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

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.

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

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.

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:

  • figureFigure 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.

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:

  • figureFigure 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.

Zoom mode state, specified as 'off' or 'on'.

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.

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

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

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

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

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