iptSetPointerBehavior

Store pointer behavior structure in graphics object or UI component

Syntax

iptSetPointerBehavior(obj,pointerBehavior)

iptSetPointerBehavior(obj,fun)

iptSetPointerBehavior(obj,[])

Description

iptSetPointerBehavior(obj,pointerBehavior) stores a pointer behavior structure in a graphics container, obj. A pointer behavior structure controls what happens when the mouse pointer moves over and then exits the graphics container. A graphics container can be a graphics object or a UI component. If obj is an array of graphics containers, then iptSetPointerBehavior stores the same pointer behavior structure in each container.

For the pointer to perform the desired pointer behavior, you must also create a pointer manager in the parent figure of the graphics container obj. For more information about creating a pointer manager for a figure, see iptPointerManager.

iptSetPointerBehavior(obj,fun) creates a pointer behavior structure, setting the enterFcn field to the specified function fun, and setting the traverseFcn and exitFcn fields to []. This syntax is provided as a convenience because, for many common uses, only the enterFcn field is necessary.

iptSetPointerBehavior(obj,[]) clears the pointer behavior from the graphics container or containers.

Examples

Change Figure Properties When Pointer Is over Graphics Objects

Show a figure with two rectangular patch graphics objects.

patchobj1 = patch([.25 .75 .75 .25 .25],...
               [.25 .25 .75 .75 .25], 'r');
patchobj2 = patch([.05 .15 .15 .05 .05],...
               [.05 .05 .95 .95 .05], 'b');
xlim([0 1])
ylim([0 1])

Specify the pointer behavior by creating a structure with three fields, enterFcn, exitFcn, and traverseFcn.

Whenever the pointer crosses over a specified object, change the mouse pointer to a fleur and change the title of the figure. Specify this behavior using the enterFcn field.

pb.enterFcn = @(fig,currentPoint) set(fig, ...
    'Name','Over Patch', ...
    'Pointer','fleur');

When the pointer moves off the object, restore the original pointer and the figure title. Specify this behavior using the exitFcn field.

pb.exitFcn = @(fig,currentPoint) set(fig, ...
    'Name','', ...
    'Pointer','arrow');

Do not change the figure as the pointer traverses the object. Set the traverseFcn field as [].

pb.traverseFcn = [];

Create a pointer manager in the current figure. Then, associate the pointer behavior structure pb with both patch objects. Move the mouse around the figure to see the pointer behavior change.

iptSetPointerBehavior([patchobj1,patchobj2],pb);
iptPointerManager(gcf)

Change Appearance of Pointer While Traversing Figure

Show a figure with a rectangular patch graphics object. Increase the x- and y-limits of the image to add some white space around the patch.

patchobj = patch([.25 .75 .75 .25 .25],...
               [.25 .25 .75 .75 .25], 'r');
xlim([0 1])
ylim([0 1])

Specify the pointer behavior by creating a structure named pb with three fields.

• The enterFcn and exitFcn fields are set to [] so the pointer takes no action when it moves across the boundary of a graphics object.

• The traverseFcn field is set as a handle to the function overMe, which is defined as a helper function at the end of this example. As the pointer moves over the graphics object, the helper function changes the pointer symbol depending on the location of the pointer.

pb.enterFcn = [];
pb.exitFcn = [];
pb.traverseFcn = @overMe;

Create a pointer manager in the current figure. Then, associate the pointer behavior structure pb with the Patch graphics object patchobj. Move the mouse around the figure to see changes in the pointer behavior.

iptPointerManager(gcf);
iptSetPointerBehavior(patchobj,pb);

Helper Function

function overMe(hFigure,currentPoint)
%overMe Set figure pointer depending on pointer location.
%   overMe(hFigure,currentPoint) sets the hFigure mouse pointer to be
%   either 'topr', 'topl', 'botr', 'botl', depending on whether
%   currentPoint is in the top right, top left, bottom right, or bottom
%   left of the hFigure's current axes.

hAxes = get(hFigure,'CurrentAxes');

% Get the axes position in pixel units.
oldUnits = get(hAxes,'Units');
set(hAxes,'Units','pixels');
axesPosition = get(hAxes,'Position');
set(hAxes,'Units',oldUnits);

x_middle = axesPosition(1) + 0.5*axesPosition(3);
y_middle = axesPosition(2) + 0.5*axesPosition(4);

x = currentPoint(1,1);
y = currentPoint(1,2);

if (x > x_middle)
    if (y > y_middle)
        pointer = 'topr';
    else
        pointer = 'botr';
    end
else
    if (y > y_middle)
        pointer = 'topl';
    else
        pointer = 'botl';
    end
end

set(hFigure,'Pointer',pointer);
end

Input Arguments

obj — Graphics container

graphics object | UI component

Graphics container in which to store the pointer behavior structure, specified as a graphics object or a UI component. For example, obj can be a figure, axes, or image graphics object, or a uifigure or uipanel UI component. obj can also be an array of graphics objects and UI components.

pointerBehavior — Pointer behavior

structure

Pointer behavior, specified as a structure with three fields.

To define the specific actions of the pointer, set the value of these fields to function handles. If you set a field to [], then no action is taken. Each function handle must have two input arguments: a Figure object and the current position of the pointer.

Field	When Called
enterFcn	Called when the mouse pointer moves over the graphics container.
traverseFcn	Called once when the mouse pointer moves over the graphics container, and called again each time the mouse moves within the graphics container.
exitFcn	Called when the mouse pointer leaves the graphics container.

For more information about function handles, see Create Function Handle.

fun — Pointer behavior when pointer moves over graphics container

function handle

Pointer behavior when the pointer moves over the graphics container, specified as a function handle. The function must have two input arguments: a Figure object and the current position of the pointer. For more information about function handles, see Create Function Handle.

Data Types: function_handle

Tips

• If you specify a pointer behavior using iptSetPointerBehavior and then change the figure pointer without using iptSetPointerBehavior, then the pointer manager of the parent figure may not reflect the new behavior. Some ways to change the figure pointer without using iptSetPointerBehavior include using ROI objects such as Polygon, another graphics object, another custom UI, or code that modifies the pointer from within a callback.

Version History

Introduced in R2006a