Syntax

Description

pan on turns on mouse-based panning for axes in the current figure.

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

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

pan off turns panning off for axes in the current figure.

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

pan(fig,...) sets the pan state 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 getAxesZoomConstraint 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 setAxesZoomConstraint 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')

Alternatives

Use the Pan tool on the figure toolbar to enable and disable pan mode on a plot, or select Pan from the figure's Tools menu. For details, see Panning — Shifting Your View of the Graph.

See Also

linkaxes | rotate3d | zoom