Highlights
Follow


New in R2020a: Mouse Pointer control in apps & uifigures

Adam Danz on 25 Jun 2020 (Edited on 29 Apr 2021)
Latest activity Edit by Hans Scharler on 29 Apr 2021

Starting in r2020a , you can change the mouse pointer symbol in apps and uifigures.

The Pointer property of a figure defines the cursor’s default pointer symbol within the figure. You can also create your own pointer symbols (see part 3, below).

Part 1. How to define a default pointer symbol for a uifigure or app

For figures or uifigures, set the pointer property when you define the figure or change the pointer property using the figure handle.

% Set pointer when creating the figure
uifig = uifigure('Pointer', 'crosshair');
% Change pointer after creating the figure
uifig.Pointer = 'crosshair';

For apps made in AppDesigner, you can either set the pointer from the Design View or you can set the pointer property of the app’s UIFigure from the startup function using the second syntax shown above.

Part 2. How to change the pointer symbol dynamically

The pointer can be changed by setting specific conditions that trigger a change in the pointer symbol.

For example, the pointer can be temporarily changed to a busy-symbol when a button is pressed. This ButtonPushed callback function changes the pointer for 1 second.

function WaitasecondButtonPushed(app, event)
   % Change pointer for 1 second.
   set(app.UIFigure, 'Pointer','watch')
   pause(1)
   % Change back to default.
   set(app.UIFigure, 'Pointer','arrow')
   app.WaitasecondButton.Value = false;
end

The pointer can be changed every time it enters or leaves a uiaxes or any plotted object within the uiaxes. This is controlled by a set of pointer management functions that can be set in the app’s startup function.

iptSetPointerBehavior(obj,pointerBehavior) allows you to define what happens when the pointer enters, leaves, or moves within an object. Currently, only axes and axes objects seem to be supported for UIFigures.

iptPointerManager(hFigure,'enable') enables the figure’s pointer manager and updates it to recognize the newly added pointer behaviors.

The snippet below can be placed in the app’s startup function to change the pointer to crosshairs when the pointer enters the outerposition of a uiaxes and then change it back to the default arrow when it leaves the uiaxes.

% Define pointer behavior when pointer enter axes
pm.enterFcn = @(~,~) set(app.UIFigure, 'Pointer', 'crosshair');
pm.exitFcn  = @(~,~) set(app.UIFigure, 'Pointer', 'arrow');
pm.traverseFcn = [];
iptSetPointerBehavior(app.UIAxes, pm)
% Enable pointer manager for app
iptPointerManager(app.UIFigure,'enable'); 

Any function can be triggered when entering/exiting an axes object which makes the pointer management tools quite powerful. This snippet below defines a custom function cursorPositionFeedback() that responds to the pointer entering/exiting a patch object plotted within the uiaxes. When the pointer enters the patch, the patch color is changed to red, the pointer is changed to double arrows, and text appears in the app’s text area. When the pointer exits, the patch color changes back to blue, the pointer changes back to crosshairs, and the text area is cleared.

% Plot patch on uiaxes
hold(app.UIAxes, 'on')
region1 = patch(app.UIAxes,[1.5 3.5 3.5 1.5],[0 0 5 5],'b','FaceAlpha',0.07,...
    'LineWidth',2,'LineStyle','--','tag','region1');
% Define pointer behavior for patch
pm.enterFcn = @(~,~) cursorPositionFeedback(app, region1, 'in');
pm.exitFcn  = @(~,~) cursorPositionFeedback(app, region1, 'out');
pm.traverseFcn = [];
iptSetPointerBehavior(region1, pm)
% Enable pointer manager for app
iptPointerManager(app.UIFigure,'enable');
function cursorPositionFeedback(app, hobj, inout)
% When inout is 'in', change hobj facecolor to red and update textbox.
% When inout is 'out' change hobj facecolor to blue, and clear textbox.
% Check tag property of hobj to identify the object.
switch lower(inout)
    case 'in'
        facecolor = 'r';
        txt = 'Inside region 1';
        pointer = 'fleur';
    case 'out'
        facecolor = 'b';
        txt = '';
        pointer = 'crosshair';
end
hobj.FaceColor = facecolor;
app.TextArea.Value = txt;
set(app.UIFigure, 'Pointer', pointer)
end  

The app showing the demo below is attached.

Part 3. Create your own custom pointer symbol

  1. Set the figure’s pointer property to ‘custom’.
  2. Set the figure’s PointerShapeCData property to the custom pointer matrix. A custom pointer is defined by a 16x16 or 32x32 matrix where NaN values are transparent, 1=black, and 2=white.
  3. Set the figure’s PointerShapeHotSpot to [m,n] where m and n are the coordinates that define the tip or "hotspot" of the matrix.

This demo uses the attached mat file to create a black hand pointer symbol.

iconData = load('blackHandPointer.mat');
uifig = uifigure(); 
uifig.Pointer = 'custom'; 
uifig.PointerShapeCData = iconData.blackHandIcon; 
uifig.PointerShapeHotSpot = iconData.hotspot;

Also see Jiro's pointereditor() function on the file exchange which allows you to draw your own pointer.