Pan view of graph interactively
pan on
pan xon
pan yon
pan off
pan
pan(fig,...)
h = pan(fig)
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.
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.
ContextMenu <handle> —
Specifies a custom context menu to be displayed
during a right-click action.
UseLegacyExplorationModes
'off' (default) | on/off logical
value – 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 matlab.lang.OnOffSwitchState.
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'.
This property only applies to pan objects for
figures created using the
uifigure function or in
MATLAB®
Online™.
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:
| 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)
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'.
Plot a graph and turn on Pan mode:
plot(magic(10)); pan on % pan on the plot
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.
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.
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
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));
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.ContextMenu = hCM; pan('on')
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.
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.