Documentation

iptSetPointerBehavior

Store pointer behavior structure in Handle Graphics object

Syntax

iptSetPointerBehavior(h, pointerBehavior)
iptSetPointerBehavior(h, [])
iptSetPointerBehavior(h, enterFcn)

Description

iptSetPointerBehavior(h, pointerBehavior) stores the specified pointer behavior structure in the specified Handle Graphics object, h. If h is an array of objects, iptSetPointerBehavior stores the same structure in each object.

When used with a figure's pointer manager (see iptPointerManager), a pointer behavior structure controls what happens when the figure's mouse pointer moves over and then exits an object in the figure. For details about this structure, see Pointer Behavior Structure.

iptSetPointerBehavior(h, []) clears the pointer behavior from the Handle Graphics object or objects.

iptSetPointerBehavior(h, enterFcn) creates a pointer behavior structure, setting the enterFcn field to the function handle specified, and setting the traverseFcn and exitFcn fields to []. See Pointer Behavior Structure for details about these fields. This syntax is provided as a convenience because, for most common uses, only the enterFcn is necessary.

Pointer Behavior Structure

A pointer behavior structure contains three fields: enterFcn, traverseFcn, and exitFcn. You set the value of these fields to function handles and use the iptSetPointerBehavior function to associate this structure with an HG object in a figure. If the figure has a pointer manager installed, the pointer manager calls these functions when the following events occur. If you set a field to[], no action is taken.

Function HandleWhen 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.

When the pointer manager calls the functions you create, it passes two arguments: a handle to the figure and the current position of the pointer.

Examples

Example 1

Change the mouse pointer to a fleur whenever it is over a specific object and restore the original pointer when the mouse pointer moves off the object. The example creates a patch object and associates a pointer behavior structure with the object. Because this scenario requires only an enterFcn, the example uses the iptSetPointerBehavior(n, enterFcn) syntax. The example then creates a pointer manager in the figure. Note that the pointer manager takes care of restoring the original figure pointer.

 hPatch = patch([.25 .75 .75 .25 .25],...
                [.25 .25 .75 .75 .25], 'r');
 xlim([0 1]);
 ylim([0 1]);
 
 enterFcn = @(figHandle, currentPoint)...
       set(figHandle, 'Pointer', 'fleur');
 iptSetPointerBehavior(hPatch, enterFcn);
 iptPointerManager(gcf);

Example 2

Change the appearance of the mouse pointer, depending on where it is within the object. This example sets up the pointer behavior structure, setting the enterFcn and exitFcn fields to [], and setting traverseFcn to a function named overMe that handles the position-specific behavior. overMe is an example function (in \toolbox\images\imdemos) that varies the mouse pointer depending on the location of the mouse within the object. For more information, edit overMe.

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

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

iptSetPointerBehavior(hPatch, pointerBehavior);
iptPointerManager(gcf);

Example 3

Change the figure's title when the mouse pointer is over the object. In this scenario, enterFcn and exitFcn are used to achieve the desired side effect, and traverseFcn is [].

 hPatch = patch([.25 .75 .75 .25 .25],...
                [.25 .25 .75 .75 .25], 'r');
 xlim([0 1])
 ylim([0 1])
 
 pointerBehavior.enterFcn = ...
     @(figHandle, currentPoint)...
          set(figHandle, 'Name', 'Over patch');
 pointerBehavior.exitFcn  = ...
     @(figHandle, currentPoint) set(figHandle, 'Name', '');
 pointerBehavior.traverseFcn = [];
 
 iptSetPointerBehavior(hPatch, pointerBehavior);
 iptPointerManager(gcf)
Was this topic helpful?