zoom

Enable zoom mode

expand all in page

Description

Zoom mode allows you to explore data by changing the limits of axes. In releases prior to R2018b, use zoom mode to zoom in or out of axes. Turn zoom mode on and off, and set other basic options, using the zoom function. To further control zoom mode behavior, return and use a zoom object.

Starting in R2018b, you can zoom in and out using built-in interactions instead. Built-in interactions do not require you to enable a mode and respond faster than interaction modes. For more information about built-in interactions, see Control Chart Interactivity.

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

Creation

Syntax

zoom option
zoom
zoom(factor)
zoom(fig,___)
z = zoom
z = zoom(fig)

Description

example

zoom option enables or disables 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. For more zoom mode options, see option.

When zoom mode is on, to zoom in, position your cursor where you want the center of the axes to be and either scroll up or click. To zoom out, either scroll down or hold Shift and click. Each click zooms in or out by a factor of 2. To zoom into a rectangular region, click and drag. To return an axes object to its baseline zoom level, double-click within the axes.

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. Zoom out by specifying factor as a value between 0 and 1.

zoom(fig,___) sets the zoom mode for all axes in the specified figure. Specify the additional argument as 'on', 'off', 'out', 'reset', 'xon', 'yon', or a zoom factor. For example, use zoom(fig,'on') to enable zoom mode for the figure fig.

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

example

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

Input Arguments

expand all

Target figure, specified as a Figure object.

Zoom mode option, specified as one of these values:

  • 'on' – Turn on zoom mode.

  • 'off' – Turn off zoom mode. Some built-in interactions remain enabled by default, regardless of the mode. To disable built-in zoom interactions, 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, or selecting from the axes toolbar returns axes to this zoom level.

  • 'out' – Return the current axes to its baseline zoom level.

  • 'xon' – Turn on zoom mode for the x dimension only.

  • 'yon' – Turn on zoom mode for the y dimension only.

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

Properties

expand all

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

  • 'both' – Allow zooming in the x and y dimensions.

  • 'horizontal' – Allow zooming in the x dimension only.

  • 'vertical' – Allow zooming in the y dimension only.

This property only affects 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 on, you can always use the scroll wheel to zoom in or out, regardless of the value of Direction.

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

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

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

  • 'PostContextMenu' – Display a context menu.

  • 'InverseZoom' – Zoom out when you right-click.

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

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

  • Function handle

  • Cell array containing a function handle and additional arguments

  • Character vector that is 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 the axes in which you are zooming. This structure has 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 Callback Definition.

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

  • Function handle

  • Cell array containing a function handle and additional arguments

  • Character vector that is 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 the axes in which you are zooming. This structure has 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 Callback Definition.

Zoom suppression callback, specified as one of these values:

  • Function handle

  • Cell array containing a function handle and additional arguments

  • Character vector that is 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's output to a variable.

For more information about callbacks, see Callback Definition.

This property is read-only.

The Figure object 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 matlab.lang.OnOffSwitchState.

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

This property only applies to zoom objects for figures created using the uifigure function or in MATLAB Online™.

Object Functions

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

setAllowAxesZoom

setAllowAxesZoom(z,ax,tf) sets the zoom mode for axes objects in vector ax according to the logical values in vector tf. The sizes of ax and tf must match.

Enabling zoom for axes using setAllowAxesZoom does not enable zoom for the figure. To do this, set the Enable property of the zoom object.

isAllowAxesZoom

tf = isAllowAxesZoom(z,ax) returns the zoom mode for the axes objects in vector ax as the logical vector tf. The size of tf is the same as ax.

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

setAxesZoomConstraint(z,ax,d) sets the zoom dimension for the scalar axes object ax according to the dimension value d. Specify the dimension as one of these values: 'x', 'y', 'z', 'xy', 'xz', 'yz', or 'unconstrained'. For example, setAxesZoomConstraint(z,ax,'xy') allows you to zoom in the x and y dimensions only.

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

d = getAxesZoomConstraint(z,ax) returns the zoom dimension d for the scalar axes object ax as 'x', 'y', 'z', 'xy', 'xz', 'yz', or 'unconstrained'.

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

setAxes3DPanAndZoomStyle(z,ax,s) sets the zoom style s for the axes objects in vector ax. 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 example, use setAxes3DPanAndZoomStyle(z,ax,'camera').

For more information about the camera view angle, see Camera Graphics Terminology.

getAxes3DPanAndZoomStyle

s = getAxes3DPanAndZoomStyle(z,ax) returns the zoom style for axes objects in vector ax as the character cell array s. The elements of s are returned as 'limits' or 'camera'.

setAxesZoomMotion (not recommended)

This function is not recommended. Use setAxesZoomConstraint instead.

setAxesZoomMotion(z,ax,d) sets the zoom dimension d for axes objects in vector ax. Specify the zoom dimension as '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 setAxesZoomConstraint instead.

d = getAxesZoomMotion(z,ax) returns zoom dimensions for axes objects in vector ax as a character cell array d. The elements of d are returned as 'horizontal', 'vertical', or 'both'.

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 some data, zoom in, and then set the baseline zoom level. Future calls to zoom out return the axes to the baseline zoom level you set.

For example, get the coordinates of a predefined surface and plot them. Turn on zoom mode.

[X,Y,Z] = peaks(20);
surf(X,Y,Z)
zoom on

A surface with several peaks

Zoom into the tallest peak by clicking on it. Then, set the baseline zoom level.

zoom reset

The surface zoomed into the tallest peak

Zoom into the highest peak a second time, then call zoom out. 

zoom out
The axes return to the baseline zoom level you set.

Create a context menu that you can use while zoom mode is enabled. For this example, create a context menu that allows you to close the figure.

First, get the coordinates of a predefined surface and plot them.

[X,Y,Z] = peaks(20);
surf(X,Y,Z)

A surface with several peaks

Create a context menu using the uicontextmenu function. Then, add an item to the menu. Specify a label and a callback that closes the figure.

cm = uicontextmenu;
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, turn on zoom mode. 

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

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

Compatibility Considerations

expand all

Not recommended starting in R2020a

See Also

|

Topics

Introduced before R2006a

MATLAB Documentation

Support