pan - Enable pan mode - MATLAB (original) (raw)

Description

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

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

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

Creation

Syntax

Description

pan [option](#mw%5Ff1e28797-35d6-4d01-8def-170ad9de8b0a) sets the pan mode for all axes in the current figure. For example, pan on enables pan mode, pan xon enables pan mode for the _x_-dimension only, pan yon enables pan mode for the _y_-dimension only, andpan off disables pan mode.

When pan mode is enabled, pan the view of the axes using the cursor or the keyboard.

• Cursor — Click and drag the cursor in the axes.
• Keyboard — To pan vertically, press the up arrow (↑) or down arrow (↓) key. To pan horizontally, press the left arrow (←) orright arrow (→) key.

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

example

pan toggles the pan mode. If pan mode is disabled, then callingpan restores the most recently used pan option of on,xon, oryon.

pan([fig](#mw%5F4c3b7b39-c841-4e27-a959-42e38a22bcf0),[option](#mw%5Ff1e28797-35d6-4d01-8def-170ad9de8b0a)) sets the pan mode for all axes in the specified figure. For example, to enable pan mode for all axes in the figure fig, usepan(fig,'on').

pan([ax](#mw%5F30f55433-fc76-4840-a13f-a3ffcd119c3f),[option](#mw%5Ff1e28797-35d6-4d01-8def-170ad9de8b0a)) sets the pan mode for the specified axes. For example, to enable pan mode for the axesax, usepan(ax,'on'). Use this syntax with apps created in App Designer and using theuifigure function. (since R2023a)

p = pan creates apan object for the current figure. This syntax is useful for customizing the pan mode and motion.

example

p = pan([fig](#mw%5F4c3b7b39-c841-4e27-a959-42e38a22bcf0)) creates a pan object for the specified figure.

example

Input Arguments

expand all

option — Pan mode option

'on' | 'off' | 'xon' | 'yon' | 'toggle'

Pan mode option, specified as one of these values:

• 'on' — Enable pan mode.
• 'off' — Disable pan mode. Some built-in interactions remain enabled by default, regardless of the current interaction mode. To disable built-in pan interactions that are independent of the pan mode, use the disableDefaultInteractivity function.
• 'xon' — Enable pan mode for the _x_-dimension only.
• 'yon' — Enable pan mode for the _y_-dimension only.
• 'toggle' — Toggle the pan mode. If pan mode is disabled, then'toggle' restores the most recently used pan option of'on', 'xon', or 'yon'. Using this option is the same as calling pan without any arguments.

fig — Target figure

Figure object

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

ax — Target axes

Axes object

Target axes, specified as anAxes object.

Properties

expand all

Motion — Dimension

'both' (default) | 'horizontal' | 'vertical'

Dimension to allow panning, specified as one of these values:

• 'both' — Allow panning in the _x_-dimension and the _y_-dimension.
• 'horizontal' — Allow panning in the_x_-dimension only.
• 'vertical' — Allow panning 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 pan dimension in 3-D views, use apanInteraction object.

— Context menu

emptyGraphicsPlaceholder array (default) | ContextMenu object

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

ButtonDownFilter — Pan suppression callback

[ ] (default) | function handle | cell array | character vector

Pan 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 panning under conditions that you define. A numeric or logical output of 1 (true) suppresses panning, and a numeric or logical output of 0 (false) allows panning. 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 panning.
• 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 panning

[ ] (default) | function handle | cell array | character vector

Function to execute before panning, 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 panning. 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 panning.
• axesStruct — Structure that contains one field,Axes, the axes object in which you are panning. 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 panning

[ ] (default) | function handle | cell array | character vector

Function to execute after panning, 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 panning. 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 panning.
• axesStruct — Structure that contains one field,Axes, the axes object in which you are panning. 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 — Pan mode state

'off' (default) | 'on' | on/off logical value

Pan mode state, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of'on' is equivalent totrue, and'off' is equivalent tofalse. 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 pan object. If you did not specify a figure, thenFigureHandle is the figure that was current when you created thepan object.

UseLegacyExplorationModes — Legacy mode

'off' (default) | 'on' | on/off logical value

Legacy mode, specified as 'on' or'off', or as numeric or logical1 (true) or0 (false). A value of 'on' is equivalent totrue, and'off' is equivalent tofalse. 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 pan objects for figures created using theuifigure function or inMATLAB 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 the pan object functions to customize the panning behavior of axes objects within a figure. For all of these functions, the axes and pan mode objects must be associated with the same figure.

Examples

collapse all

Enable Pan Mode

Plot a graph and enable pan mode. Then, interactively pan the axes.

Constrain Pan in Tiled Chart Layout

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

tiledlayout(2,2) ax1 = nexttile; plot(1:10); p = pan;

ax2 = nexttile; plot(rand(3)); setAllowAxesPan(p,ax2,false);

ax3 = nexttile; plot(peaks); setAxesPanConstraint(p,ax3,'x');

ax4 = nexttile; contour(peaks); setAxesPanMotion(p,ax4,'horizontal');

Create Button Down Callback

Create a button down callback for pan mode objects to trigger. Copy the following code to a new file and execute it, and observe the panning behavior.

function demo % Allow a line to have its own 'ButtonDownFcn' callback hLine = plot(rand(1,10)); hLine.ButtonDownFcn = 'disp(''This executes'')'; hLine.Tag = 'DoNotIgnore'; h = pan; h.ButtonDownFilter = @mycallback; h.Enable = 'on'; % Mouse click on the line end

function [flag] = mycallback(obj,event_obj) % If the object tag is 'DoNotIgnore', then return true

% Indicate what the target is
disp(['Clicked ' obj.Type ' object'])
objTag = obj.Tag;
if strcmpi(objTag,'DoNotIgnore')
    flag = true;
else
    flag = false;
end

end

Define Pre- and Post-Callback Behavior

Create callbacks for pre- and post-button down events for pan mode objects to trigger. Copy the following code to a new file, execute it, and observe the panning behavior.

function demo % Listen to pan events plot(1:10); p = pan; p.ActionPreCallback = @myprecallback; p.ActionPostCallback = @mypostcallback; p.Enable = 'on'; end

function myprecallback(obj,evd) disp('A pan is about to occur.'); end

function mypostcallback(obj,evd) newLim = evd.Axes.XLim; msgbox(sprintf('The new X-Limits are [%.2f,%.2f].',newLim)); end

Create Mode Context Menu

Create a context menu that lets the user switch to zoom mode by right-clicking.

figure plot(magic(10)); pCM = uicontextmenu; pMenu = uimenu('Parent',pCM,'Label','Switch to zoom',... 'Callback','zoom(gcbf,''on'')'); pPan = pan(gcf); pPan.ContextMenu = pCM; pan('on')

More About

expand all

Changing Callback Functions

You can create a pan 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 pan 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 pan behaviors to different axes in a figure by using mode objects and then link them using thelinkaxes 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 pan mode by clicking the pan icon in the axes toolbar.

Version History

Introduced before R2006a

expand all

R2023a: Set pan mode for specified axes in apps

For apps created in App Designer and using theuifigure function, set the pan mode for axes by specifying the axes as the first input ofpan. When setting the pan mode for axes, the function does not return a pan 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 theContextMenu property instead. The property values are the same.

There are no plans to remove support for theUIContextMenu 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 panning enabled by default

Interactively explore your data using built-in axes interactions that are enabled by default. For example, you can click and drag to pan the axes (2-D view) without enabling pan mode. For more information, see Control Chart Interactivity.

Previously, no axes interactions were enabled by default.