pan

Pan view of graph interactively

Syntax

pan on
pan xon
pan yon
pan off
pan
pan(fig,...)
h = pan(fig)


Description

pan on turns on pan mode for axes in the current figure.

pan xon turns on pan mode and enables panning only in the x direction for axes in a 2-D view in the current figure.

pan yon turns on pan mode and enables panning only in the y direction for axes in a 2-D view in the current figure.

pan off turns off pan mode for axes in the current figure. Starting in R2018b, some pan interactions are enabled by default, regardless of the pan mode. If you want to disable these default interactions, then use the disableDefaultInteractivity function.

pan toggles the pan mode for axes in the current figure to on or off.

pan(fig,...) sets the pan mode for axes in the specified figure.

h = pan(fig) returns the figure's pan mode object for the figure fig for you to customize the mode's behavior.

Using Pan Mode Objects

Access the following properties of pan mode objects.

• Enable 'on'|'off' — Specifies whether this figure mode is currently enabled on the figure.

• Motion 'horizontal'|'vertical'|'both' — The type of panning enabled for the figure. This property only affects axes in a 2-D view ([0 90]).

• FigureHandle <handle> — The associated figure handle, a read-only property that cannot be set.

Pan Mode Callbacks

You can program the following callbacks for pan mode operations.

• ButtonDownFilter <function_handle> — Function to intercept ButtonDown events

  The application can inhibit the panning operation under circumstances the programmer defines, depending on what the callback returns. The input function handle should reference a function with two implicit arguments (similar to graphics object callbacks):

  function [res] = myfunction(obj,event_obj)
  % obj          handle to the object clicked on
  % event_obj    event data (empty in this release)
  % res [output] a logical flag to determine whether the pan
  %              operation should take place(for 'res' set to 'false') 
  %              or the 'ButtonDownFcn' property of the object should 
  %              take precedence (when 'res' is 'true')
  

• ActionPreCallback <function_handle> — Function to execute before panning

  Set this callback to if you need to execute code when a pan operation begins. The function handle should reference a function with two implicit arguments (similar to graphics object callbacks):

  function myfunction(obj,event_obj)
  % obj         handle to the figure that has been clicked on
  % event_obj   object containing struct of event data
  

  The event data struct has the following field:

  Axes	The handle of the axes that is being panned

• ActionPostCallback <function_handle> — Function to execute after panning

  Set this callback if you need to execute code when a pan operation ends. The function handle should reference a function with two implicit arguments (similar to graphics object callbacks):

  function myfunction(obj,event_obj)
  % obj         handle to the figure that has been clicked on
  % event_obj   object containing struct of event data 
  %             (same as the event data of the 
  %             'ActionPreCallback' callback)
  

Pan Mode Utility Functions

The following functions in pan mode query and set certain of its properties.

• flags = isAllowAxesPan(h,ax) — Function querying permission to pan axes.

  Calling the function isAllowAxesPan on the pan object, h, with a vector of axes handles, ax, as input returns a logical array of the same dimension as the axes handle vector, which indicates whether a pan operation is permitted on the axes objects.

• setAllowAxesPan(h,ax,flag) — Function to set permission to pan axes.

  Calling the function setAllowAxesPan on the pan object, h, with a vector of axes handles, ax, and a logical scalar, flag, either allows or disallows a pan operation on the axes objects.

• cn = getAxesPanConstraint(h,ax) — Function to get constraints of pan operations.

  Calling the function getAxesPanConstraint on the pan object, h, with an axes object, ax, as input returns the constraint for the axes. The returned constraint is one of these values: 'x', 'y', 'z', 'xy', 'xz', 'yz', or 'unconstrained'.

• setAxesPanConstraint(h,ax,cnstr) — Function to set constraints of pan operations.

  Calling the function setAxesPanConstraint on the pan object, h, with an axes object, ax, and a constraint option, cnstr, sets the constraint for the axes. Specify the constraint as one of these values: 'x', 'y', 'z', 'xy', 'xz', 'yz', or 'unconstrained'.

• sty = getAxes3DPanAndZoomStyle(h,ax) — Function to get style of pan operations.

  Calling the function getAxes3DPanAndZoomStyle on the pan object, h, with a vector of axes handles, ax, as input returns the style of panning for each axes. The returned value for each axes is either 'limits' or 'camera'.

• setAxes3DPanAndZoomStyle(h,ax,style) — Function to set style of pan operations.

  Calling the function setAxes3DPanAndZoomStyle on the pan object, h, with a vector of axes handles, ax, and a character array, style, sets the style of panning on each axes. Specify the style as either 'limits' or 'camera'.

• cns = getAxesPanMotion(h,ax) — Function to get constraints of pan operations (not recommended, use getAxesPanConstraint).

  Calling the function getAxesPanMotion on the pan object, h, with a vector of axes objects, ax, as input returns a character cell array of the same dimension as ax, which indicates the constraint for each axes. The returned value for each axes is 'horizontal', 'vertical' or 'both'.

• setAxesPanMotion(h,ax,constraints) — Function to set constraints of pan operations (not recommended, use setAxesPanConstraint).

  Calling the function setAxesPanMotion on the pan object, h, with a vector of axes objects, ax, and a character array, constraints, sets the constraint for each axes. Specify the constraints as 'horizontal', 'vertical' or 'both'.

Examples

Example 1 — Entering Pan Mode

Plot a graph and turn on Pan mode:

plot(magic(10));
pan on
% pan on the plot

Example 2 — Constrained Pan

Constrain pan to x-axis using set:

plot(magic(10));
h = pan;
h.Motion = 'horizontal';
h.Enable = 'on';
% pan on the plot in the horizontal direction.

Example 3 — Constrained Pan in Subplots

Create four axes as subplots and give each one a different panning behavior:

ax1 = subplot(2,2,1);
plot(1:10);
h = pan;
ax2 = subplot(2,2,2);
plot(rand(3));
setAllowAxesPan(h,ax2,false);
ax3 = subplot(2,2,3);
plot(peaks);
setAxesPanMotion(h,ax3,'horizontal');
ax4 = subplot(2,2,4);
contour(peaks);
setAxesPanMotion(h,ax4,'vertical');
% pan on the plots.

Example 4 — Coding a ButtonDown Callback

Create a buttonDown callback for pan mode objects to trigger. Copy the following code to a new file, execute it, and observe 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
%
function [flag] = mycallback(obj,event_obj)
% If the tag of the object 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

Example 5 — Coding Pre- and Post-Callback Behavior

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

function demo
% Listen to pan events
plot(1:10);
h = pan;
h.ActionPreCallback = @myprecallback;
h.ActionPostCallback = @mypostcallback;
h.Enable = 'on';
%
function myprecallback(obj,evd)
disp('A pan is about to occur.');
%
function mypostcallback(obj,evd)
newLim = evd.Axes.XLim;
msgbox(sprintf('The new X-Limits are [%.2f,%.2f].',newLim));

Example 6 — Creating a Context Menu for Pan Mode

Coding a context menu that lets the user to switch to zoom mode by right-clicking:

figure
plot(magic(10)); 
hCM = uicontextmenu; 
hMenu = uimenu('Parent',hCM,'Label','Switch to zoom',...
        'Callback','zoom(gcbf,''on'')'); 
hPan = pan(gcf); 
hPan.UIContextMenu = hCM; 
pan('on')

You cannot add items to the built-in pan context menu, but you can replace it with your own.

Tips

You can create a pan mode object once and use it to customize the behavior of different axes, as Example 3 illustrates. 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 (when panning, zooming, etc.), you will receive a warning if you attempt to change any of the figure's 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 some keep track of which interactive mode is active, if any, before attempting to do this.

When you assign different pan behaviors to different subplot axes via a mode object 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.

Alternatives

Use the Pan tool on the toolbar to enable and disable pan mode on a plot, or select Pan from the figure's Tools menu.