Main Content

iptSetPointerBehavior

Store pointer behavior structure in graphics object

collapse all in page

Syntax

iptSetPointerBehavior(obj,pointerBehavior)
iptSetPointerBehavior(obj,[])
iptSetPointerBehavior(obj,fun)

Description

iptSetPointerBehavior(obj,pointerBehavior) stores the specified pointer behavior structure in the specified graphics object, obj. If obj is an array of objects, then iptSetPointerBehavior stores the same structure in each object.

If the figure has a pointer manager installed, then the pointer manager calls these functions when the mouse moves over and then exits an object in the figure. See iptPointerManager.

example

iptSetPointerBehavior(obj,[]) clears the pointer behavior from the graphics object or objects.

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.

Examples

collapse all

Open Script

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)
Open Script

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

collapse all

Graphics object, specified as a handle to a figure, axes, uipanel, or image graphics objects. obj can also be an array of graphics objects.

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. When the pointer manager calls the function handles, it passes two arguments: the figure object and the current position of the pointer.

FieldWhen Called
enterFcnCalled when the mouse pointer moves over the object.
traverseFcnCalled once when the mouse pointer moves over the object, and called again each time the mouse moves within the object.
exitFcnCalled when the mouse pointer leaves the object.

Pointer behavior when pointer moves over object, specified as a 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 iptPointerManager may not update to 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

See Also

|