Main Content

pan

Enable pan mode

expand all in page

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

pan option
pan
pan(fig,option)
pan(ax,option)
p = pan
p = pan(fig)

Description

pan option 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, and pan 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 (←) or right 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 calling pan restores the most recently used pan option of on, xon, or yon.

pan(fig,option) sets the pan mode for all axes in the specified figure. For example, to enable pan mode for all axes in the figure fig, use pan(fig,'on').

pan(ax,option) sets the pan mode for the specified axes. For example, to enable pan mode for the axes ax, use pan(ax,'on'). Use this syntax with apps created in App Designer and using the uifigure function. (since R2023a)

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

example

p = pan(fig) creates a pan object for the specified figure.

example

Input Arguments

expand all

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.

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 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 a panInteraction object.

Context menu, specified as a ContextMenu 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.

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.

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.

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.

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

This property is read-only.

Figure object that you specified when creating the pan object. If you did not specify a figure, then FigureHandle is the figure that was current when you created the pan 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 pan 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 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.

setAllowAxesPan

The setAllowAxesPan function sets permission to pan axes.

Calling setAllowAxesPan(p,axes,tf) on the pan object p, with a vector of axes objects axes and a logical scalar tf as inputs, allows or disallows a pan operation on the axes objects.

Enabling pan mode for axes using setAllowAxesPan does not enable pan mode for the figure. To do this, set the Enable property of the pan object.

isAllowAxesPan

The isAllowAxesPan function queries permission to pan axes.

Calling tf = isAllowAxesPan(p,axes) on the pan object p, with a vector of axes objects axes as an input, returns a logical array tf with the same size as axes. tf indicates whether a pan operation is permitted on the axes objects.

Returning the pan mode of axes using isAllowAxesPan does not return the pan mode for the figure. To do this, access the Enable property of the pan object.

setAxesPanConstraint

The setAxesPanConstraint function sets the pan dimension of axes.

Calling setAxesPanConstraint(p,axes,d) on the pan object p, with a vector of axes objects axes and a dimension value scalar d as inputs, sets the pan dimension of the axes objects as one of these dimension values: 'x', 'y', 'z', 'xy', 'xz', 'yz', or 'unconstrained'.

Setting the pan dimension for axes using setAxesPanConstraint does not set the pan dimension for the figure. To do this, set the Motion property of the pan object.

getAxesPanConstraint

The getAxesPanConstraint function returns the pan dimension of axes.

Calling d = getAxesPanConstraint(p,axes) on the pan object p, with a vector of axes objects axes as the input, returns a cell array d indicating the pan dimension of each axes object.

Returning the pan dimension of axes using getAxesPanConstraint does not return the pan dimension for the figure. To do this, access the Motion property of the pan object.

setAxes3DPanAndZoomStyle

The setAxes3DPanAndZoomStyle function sets the pan style of axes.

Calling setAxes3DPanAndZoomStyle(p,axes,s) on the pan object p, with a vector of axes objects axes and a pan style character array s as inputs, sets the pan style of the axes objects. By default, the pan style is 'limits', which pans by modifying the axes limits. Specify the pan style as 'camera' to pan by modifying the camera view angle.

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

getAxes3DPanAndZoomStyle

The getAxes3DPanAndZoomStyle function returns the pan style of axes.

Calling s = getAxes3DPanAndZoomStyle(p,axes) on the pan object p, with a vector of axes objects axes as an input, returns a cell array s indicating the pan style of each axes object.

setAxesPanMotion (not recommended)

This function is not recommended. Use setAxesPanConstraint instead.

Calling setAxesPanMotion(p,axes,d) on the pan object p, with a vector of axes objects axes and a pan dimension character array d as inputs, sets the pan dimension of the axes objects as one of these dimension values: 'horizontal', 'vertical', or 'both'.

The axes pan dimension that is set by setAxesPanMotion is not the same as the figure pan dimension that is set using the Motion property.

getAxesPanMotion (not recommended)

This function is not recommended. Use getAxesPanConstraint instead.

Calling d = getAxesPanMotion(p,axes) on the pan object p, with a vector of axes objects axes as an input, returns a cell array d indicating the pan dimension of each axes object.

The axes pan dimension that is returned using getAxesPanMotion is not the same as the figure pan dimension that is returned using the Motion property.

Examples

collapse all

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

plot(magic(10))
pan on

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

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

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

See Also

| |

Topics