MATLAB Function Reference

pan - Pan view of graph interactively

GUI 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 in the MATLAB^® Graphics documentation.

Syntax

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

Description

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

pan xon turns on panning only in the x direction in the current figure.

pan yon turns on panning only in the y direction in the current figure.

pan off turns panning off in the current figure.

pan toggles the pan state in the current figure on or off.

pan(figure_handle,...) sets the pan state in the specified figure.

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

Using Pan Mode Objects

Access the following properties of pan mode objects via get and modify some of them using set:

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.

FigureHandle <handle>

The associated figure handle. This read-only property cannot be set.

ButtonDownFilter <function_handle>

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 handle callbacks):

function [res] = myfunction(obj,event_obj)
% obj        handle to the object that has been clicked on.
% event_obj  handle to event object (empty in this release).
% res        a logical flag to determine whether the pan
%            operation should take place or the 'ButtonDownFcn'
%            property of the object should take precedence.

ActionPreCallback <function_handle>

Set this callback to listen to when a pan operation will start. The input function handle should reference a function with two implicit arguments (similar to handle callbacks):

function myfunction(obj,event_obj)
% obj         handle to the figure that has been clicked on.
% event_obj   handle to event object.

The event object has the following read-only property:

Axes

The handle of the axes that is being panned

ActionPostCallback <function_handle>

Set this callback to listen to when a pan operation has finished. The input function handle should reference a function with two implicit arguments (similar to handle callbacks):

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

flags = isAllowAxesPan(h,axes)

Calling the function isAllowAxesPan on the pan object, h, with a vector of axes handles, axes, 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,axes,flag)

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

info = getAxesPanMotion(h,axes)

Calling the function getAxesPanMotion on the pan object, h, with a vector of axes handles, axes, as input will return a character cell array of the same dimension as the axes handle vector, which indicates the type of pan operation for each axes. Possible values for the type of operation are 'horizontal', 'vertical' or 'both'.

setAxesPanMotion(h,axes,style)

Calling the function setAxesPanMotion on the pan object, h, with a vector of axes handles, axes, and a character array, style, sets the style of panning on each axes.

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;
set(h,'Motion','horizontal','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 M-file, execute it, and observe panning behavior:

function demo
% Allow a line to have its own 'ButtonDownFcn' callback.
hLine = plot(rand(1,10));
set(hLine,'ButtonDownFcn','disp(''This executes'')');
set(hLine,'Tag','DoNotIgnore');
h = pan;
set(h,'ButtonDownFilter',@mycallback);
set(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.
objTag = get(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 M-file, execute it, and observe panning behavior:

function demo
% Listen to pan events
plot(1:10);
h = pan;
set(h,'ActionPreCallback',@myprecallback);
set(h,'ActionPostCallback',@mypostcallback);
set(h,'Enable','on');
%
function myprecallback(obj,evd)
disp('A pan is about to occur.');
%
function mypostcallback(obj,evd)
newLim = get(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); 
set(hPan,'UIContextMenu',hCM); 
pan('on')

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

Remarks

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.

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.