- Undocumented Matlab - https://undocumentedmatlab.com -

Undocumented mouse pointer functions

Posted By Yair Altman On September 24, 2009 | 33 Comments

Matlab contains several well-documented functions and properties dealing with the mouse pointer. However, for some reason, some very-useful functions have remained undocumented and unsupported despite having a very long history (as far back as Matlab 6, a decade ago).

getptr, setptr, moveptr and overobj are all semi-documented functions (help section available, but online doc and official support not) which are used for internal Matlab purposes and relate to the mouse pointer. All these files are pure-Matlab non-Java files, which can be edited and modified. getptr and setptr (%Matlabroot\toolbox\matlab\uitools\getptr.m and setptr.m) access the pointer shape for a figure; moveptr (%Matlabroot\toolbox\shared\controllib\moveptr.m) moves the pointer across the screen; overobj (%Matlabroot\toolbox\matlab\uitools\overobj.m) determines which figure component is currently beneath the pointer.

getptr and setptr

While undocumented Java code is needed for setting component-specific pointer shapes, figure-wide shapes can be set using pure-Matlab. Setting the mouse pointer shape is normally achieved by modifying the figure’s Pointer property, which is fully documented. The following pointer shapes are supported: ‘arrow’ (the default Matlab pointer), ‘crosshair’, ‘fullcrosshair’ (used for ginput), ‘ibeam’, ‘watch’, ‘topl’, ‘topr’, ‘botl’, ‘botr’, ‘left’, ‘top’, ‘right’, ‘bottom’, ‘circle’, ‘cross’, ‘fleur’, and ‘custom’. For example:

set(hFig, 'Pointer', 'crosshair');

Using setptr enables access to a far greater variety of pointer shapes, in addition to all the standard shapes above: ‘hand’, ‘hand1’, ‘hand2’, ‘closedhand’, ‘glass’, ‘glassplus’, ‘glassminus’, ‘lrdrag’, ‘ldrag’, ‘rdrag’, ‘uddrag’, ‘udrag’, ‘ddrag’, ‘add’, ‘addzero’, ‘addpole’, ‘eraser’, ‘help’, ‘modifiedfleur’, ‘datacursor’, and ‘rotate’. It also has a few entirely-undocumented shapes: ‘forbidden’, and ‘file’ (which expects a cursor data filepath as the following argument):

setptr(gcf, 'hand');
setptr(gcf, 'file', 'my137byteFile.data');

getptr returns a cell array of parameter name/value pairs that can be stored and later used to restore the pointer shape for a specified figure:

ptr = getptr(gcf);
% do some stuff...
set(gcf, ptr{:});

moveptr

moveptr is used to move the mouse pointer programmatically across a specific plot axes. This function is poorly and incorrectly documented and contains quite a few bugs [3] (as of R2008b). However, with minor fixes and slight attention to usage, it can be quite useful.

The regular and fully documented/supported method of moving the mouse pointer across the screen is by modifying the root (0) handle’s PointerLocation property. In many cases we may wish to programmatically move the pointer from to a specific location in a plot axes. This can be done of course by computing the figure’s dimensions and position in screen pixel coordinates, and the internal figure components dimensions/position within the figure, and their internal components and so on, not forgetting to translate data or normalized coordinates into screen pixel units, and taking care of logarithmic and reverse axes. After adding all these up, and assuming we’ve made no mistake in the computation (no easy task), we can now set the root handle’s PointerLocation property.

Comes moveptr to the rescue:

moveptr accepts a handle(hAxes) as first parameter (note that handle(hAxes) must be passed, not hAxes!), and one of the following; either ‘init’ to initialize the move (creating a transformation from local axes data units to screen pixels), or ‘move’ followed by X,Y (axes data units) to actually move the mouse pointer. X and Y may well be outside the axes boundaries:

moveptr(handle(gca),'init');
moveptr(handle(gca),'move',-5,7);  % so easy

moveptr is only available in Matlab 7, not Matlab 6. moveptr also has a bug/limitation (fixed in R2008a) in that it expects the supplied axes to be a direct child of the figure. Finally, it accepts handle(hAxes) as first parameter – not the regular numeric hAxes handle as its help section would have us believe. These may not of course be the case in a more general case. Note that R2008a’s fix for the direct-figure-child limitation, using hgconvertunits (another semi-documented function), is incompatible with Matlab 6, which did not have this function. The fix for all these issues, which accepts both hAxes and handle(hAxes), removes the direct-figure-child limitation and also works on Matlab 6, is outlined below:

%% Moveptr replacement for Matlab 6 compatibility
function moveptr(hAx, x, y)
  % Compute normalized axis coordinates
  NormX = getNormCoord(hAx, 'x', x);
  NormY = getNormCoord(hAx, 'y', y);
 
  % Compute the new coordinates in screen units
  Transform = axis2Screen(hAx);
  NewLoc = Transform(1:2) + Transform(3:4) .* [NormX NormY];
 
  % Move the pointer
  set(0,'PointerLocation',NewLoc);
%end  % moveptr
 
%% Get normalized axis coordinates
function normCoord = getNormCoord(hAx, axName, curPos)
  limits = get(hAx, [axName 'Lim']);
  if strcmpi(get(hAx,[axName 'Scale']), 'log')
    normCoord = (log2(curPos) - log2(limits(1))) /diff(log2(limits));
  else
    normCoord = (curPos-limits(1)) / diff(limits);
  end
%end  % getNormCoord
 
%% Axis to screen coordinate transformation
function T = axis2Screen(ax)
  % computes a coordinate transformation T = [xo,yo,rx,ry] that
  % relates normalized axes coordinates [xa,ya] of point [xo,yo]
  % to its screen coordinate [xs,ys] (in the root units) by:
  %     xs = xo + rx * xa
  %     ys = yo + ry * ya
  % Note: this is a modified internal function within moveptr()
  % Get axes normalized position in figure
  T = getPos(ax,'normalized');
  % Loop all the way up the hierarchy to the root
  % Note: this fixes a bug in Matlab 7's moveptr implementation
  parent = get(ax,'Parent');
  while ~isempty(parent)
    % Transform normalized axis coords -> parent coords
    if isequal(parent,0)
      parentPos = get(0,'ScreenSize');  % Save screen units
    else
      parentPos = getPos(parent, 'normalized'); % Norm units
    end
    T(1:2) = parentPos(1:2) + parentPos(3:4) .* T(1:2);
    T(3:4) = parentPos(3:4) .* T(3:4);
    parent = get(parent,'Parent');
  end
%end  % axis2Screen

overobj and hittest

overobj is a related semi-documented function. It returns a handle to the first visible element beneath the mouse pointer that has visible handles (i.e., can be found with findobj , as opposed to hidden handles that can only be found using findall). The mandatory Type argument specifies the requested handle’s Type property value.

There are several overobj usage samples in CSSM [4]. Here is an example for modifying the mouse cursor over axes:

% Modify mouse pointer over axes
hAxes = overobj('axes');
if ~isempty(hAxes)
    set(gcf,'Pointer','fleur');
else
    set(gcf,'Pointer','arrow');
end

A CSSM reader has noted [5] that since overobj uses the findobj function, it is rather slow. Therefore, do not use overobj in a complex figure’s WindowButtonMotionFcn callback.

overobj has other annoying limitations: it only searches direct figure children, not inner descendants. Therefore, anything contained within a uipanel, uibuttongroup etc. cannot be found. Also, it assumes the root and figure units are both ‘pixel’: often they are not. Also, it only searches visible objects: hidden axes are not retrieved. Finally, it would be a great benefit to have an overobj variant in which the Type argument is optional, so the function would return the handle of the first object found, of whichever type. Here’s this variant overobj2, adapted from Matlab’s overobj. Note that overobj and overobj2 only work on objects having a Position property, and so cannot be used for axes plot children:

function h = overobj2(varargin)
%OVEROBJ2 Get handle of object that the pointer is over.
%   H = OVEROBJ2 searches all objects in the PointerWindow
%   looking for one that is under the pointer. Returns first
%   object handle it finds under the pointer, or empty matrix.
%
%   H = OVEROBJ2(FINDOBJ_PROPS) searches all objects which are
%   descendants of the figure beneath the pointer and that are
%   returned by FINDOBJ with the specified arguments.
%
%   Example:
%       h = overobj2('type','axes');
%       h = overobj2('flat','visible','on');
%
%   See also OVEROBJ, FINDOBJ
 
% Ensure root units are pixels
oldUnits = get(0,'units');
set(0,'units','pixels');
 
% Get the figure beneath the mouse pointer & mouse pointer pos
try
   fig = get(0,'PointerWindow');  % HG1: R2014a or older
catch
   fig = matlab.ui.internal.getPointerWindow;  % HG2: R2014b or newer
end
p = get(0,'PointerLocation');
set(0,'units',oldUnits);
 
% Look for quick exit (if mouse pointer is not over any figure)
if fig==0,  h=[]; return;  end
 
% Compute figure offset of mouse pointer in pixels
figPos = getpixelposition(fig);
x = (p(1)-figPos(1));
y = (p(2)-figPos(2));
 
% Loop over all figure descendants
c = findobj(get(fig,'Children'),varargin{:});
for h = c'
   % If descendant contains the mouse pointer position, exit
   r = getpixelposition(h);  % Note: cache this for improved performance
   if (x>r(1)) && (x<r(1)+r(3)) && (y>r(2)) && (y<r(2)+r(4))
      return
   end
end
h = [];


An alternative to overobj or overobj2 is to use the undocumented hittest built-in function [6] – separate cases may dictate preferring one alternative to the other:

hObj = hittest(hFig);

p.s. – while most of Matlab’s undocumented stuff indeed lies in the Java domain, there are quite a few non-Java pearls to be exposed, as in this article. From time to time I will take time off from Java and describe these aspects.

Categories: Figure window, GUI, Low risk of breaking in future versions, Semi-documented function, Stock Matlab function


33 Comments (Open | Close)

33 Comments To "Undocumented mouse pointer functions"

#1 Comment By Sebastian On April 1, 2010 @ 6:31 am

Hi Yair,

I have a problem using setptr in my GUI. I turn the pointer into a watch during computing a complex plot. But if i leave the GUI window or move the mouse over an edittext it turns back into an arrow until i move it over an other uicontrol. Could you gess an explanation or anser to this problem.

Thanks
Sebastian

#2 Comment By Yair Altman On April 1, 2010 @ 6:49 am

@Sebastian – Editboxes have a dedicated mouse pointer (an “I” bar) when the mouse pointer hovers over the edit box area. Each uicontrol can have a similar dedicated pointer, although only edit boxes have such a pointer set up by default. You can modify a uicontrol’s pointer by setting the Cursor property (or using the setCursor accessor method) of the underlying Java control, as explained in other articles on this website.

#3 Comment By Joel Lim On May 28, 2010 @ 10:52 am

hello Yair,

Im trying to use a piece of coloured paper to move the mouse for my project.
I’ve done all the processing and able to detect the desired piece as well as the coordinate.

However I have no idea how this moveptr or set(pointerlocation) works..can you explain more on using this code to me please?

#4 Comment By Yair Altman On May 30, 2010 @ 6:06 am

@Joel – moveptr usage is explained [13] and the root’s PointerLocation property is explained [14].

#5 Pingback By GUI automation using a Robot | Undocumented Matlab On September 15, 2010 @ 11:03 am

[…] we could use the semi-documented moveptr function, which was described here last […]

#6 Comment By Rahul Singh On April 11, 2011 @ 1:19 am

hello Yair
i have made a project on gesture based control over pc using matlab. but i m able to execute left click function only once. as soon as it detects my finger (blue colour object) left click executes. then to again execute i have to close the editor and run .m file again. please tell my how to make it execute multiple times without having to run the code again and again

#7 Comment By Yair Altman On April 11, 2011 @ 1:25 am

@Rahul – this blog is dedicated to undocumented Matlab features and functionality. If you need general Matlab help, please use the [15], or ask MathWorks technical support, or email me directly for consulting.

#8 Comment By Anubhav Jain On August 8, 2011 @ 5:26 am

Hi,

I am looking for the mouse over event in Simulink editor window so that I can get an object as soon as I bring my mouse pointer over any block in my simulink editor window …
Can you please help me out with this..
Anubhav Jain

#9 Comment By subir On October 22, 2011 @ 11:19 am

Joel Lim @ Here is the matlab code to move cursor by detecting specific color……

 import java.awt.Robot;
   import java.awt.event.*;
   mouse=Robot;
   mouse.mouseMove(round((width/640)*cent(1)),round((height/480)*cent(2)));

#10 Comment By farfyy On December 7, 2011 @ 10:25 pm

Hi,
I found a very useful function in Matlab r2010a which change the mouse pointer when we hover over an object.
see: iptPointerManager and iptSetPointerBehavior

example:

h = plot(1:10);
iptPointerManager(gcf);
enterFcn = @(hFigure, currentPoint) set(hFigure, 'Pointer', 'fleur');
iptSetPointerBehavior(h, enterFcn);

best regards

#11 Comment By Yair Altman On December 8, 2011 @ 3:15 am

@farfyy – thanks. Users should note that this requires the Image Processing Toolbox.

#12 Comment By Liya s On January 21, 2012 @ 4:25 am

Hello yair,
I am doing a project on controlling the mouse pointer using fingers by detecting colours using webcam in matlab.i have used red colour for mouse movement.But i am unable to control the pointer.when i run the program the pointer starts moving randomly.it is not under my control.Will u please help me solve this problem.can u please send me the exact code for this.

#13 Comment By Yair Altman On January 21, 2012 @ 9:32 am

@Liya – I will be happy to help you with your application, for a consulting fee. Please contact me by email (using the link at the top-right of the webpage or altmany at gmail) with your exact requirements.

#14 Comment By matt dash On February 23, 2012 @ 11:56 am

hittest also lets you give it an optional second input, which is a 1×2 vector of x/y coordinates of a point other than the current pointer location. Giving it only one input is the same as:
hittest(fighandle,get(fighandle,’currentpoint’)). For me it runs marginally slower with two inputs, though.

#15 Comment By Yair Altman On February 25, 2012 @ 3:38 pm

@Matt – Thanks for the tip

#16 Comment By Oytun Peksel On October 23, 2012 @ 5:00 am

Hi,

Is there anyway to do the thing moveptr does but on a 3d axis. moveptr does not accept 3 inputs as coordinates.

Thanks

#17 Comment By Yair Altman On October 23, 2012 @ 5:22 am

@Oytun, I fear that you will need to do the 3D-2D transformation yourself.

#18 Comment By Oytun Peksel On October 24, 2012 @ 12:32 am

Thank you Yair.

#19 Comment By Oytun Peksel On November 6, 2012 @ 3:28 am

Hello again,

I was trying to make the 3d-2d transformation and the use the moveptr, it doesnt seem to be working.
What I did was:

mvpt= view * [x y z 1]'
mvpt=mvpt(1:2)
moveptr(handle(gca),'init')
moveptr(handle(gca),'move',mvpt(1),mvpt(2))

where x y z are the 3d axis coordinates that I wanna move the mouse pointer on.

Then I tried to modify moveptr function itself to apply the conversion on to the normalized axes coordinates as:

...
 if isLogY,
       NormY = (log2(Y)-log2(Ylim(1))) / (log2(Ylim(2))-log2(Ylim(1)));
   else
       NormY = (Y-Ylim(1)) / (Ylim(2)-Ylim(1));
   end
   if isLogZ,
       NormZ = (log2(Z)-log2(Zlim(1))) / (log2(Zlim(2))-log2(Zlim(1)));
   else
       NormZ = (Z-Zlim(1)) / (Zlim(2)-Zlim(1));
   end
%% Here is the conversion
   dum = view(Axes) * [NormX NormY NormZ 1]';
   NormX = dum(1,:);
   NormY = dum(2,:);
...

did not work again. Any thoughts?

#20 Comment By Johannes Korsawe On November 26, 2013 @ 5:37 am

Hello Yair,

inside some GUI, i want to turn the pointer into watch until some calculations have been done. Unfortunately, this only works until my first fprintf-statement (with output to commandline-window) is executed. After that, the pointer resembles ‘pointer’ again, although the calculations are not over yet (i.e. the statement setptr(mainfigurehandle,’pointer’) has NOT been executed).

What is the reason / is there a workaround for this?

Best,
Johannes

#21 Comment By Yair Altman On November 28, 2013 @ 3:06 am

@Johannes – strange, this does not happen to me. Perhaps you have something special in your code, or maybe a specific configuration of Matlab release/platform which is buggy. I suggest that you contact MathWorks and file a bug report. While setptr is undocumented/unsupported, the corresponding set(gcf,...) is entirely documented/supported and should exhibit the same behavior on your system.

#22 Comment By Charlie On January 17, 2014 @ 4:43 pm

Excellent post Yair, but… How would you get the handle of an axes control that is within the GUI?

#23 Comment By Yair Altman On January 18, 2014 @ 9:11 am

hAxes = findall(hFigOrPanel, 'type','axes');

#24 Comment By Chad On September 30, 2014 @ 5:09 pm

Great Post! How would I change the cursor if I don’t have a figure open, e.g. I want to show an hourglass during a slow function called from the command line.

#25 Comment By Yair Altman On September 30, 2014 @ 10:18 pm

@Chad – you would need to modify the Cursor property (or using the setCursor accessor method) of the various Java components that comprise the Matlab Desktop, as explained in other articles on this website (e.g. [16] and [17]).

#26 Comment By David M On December 3, 2014 @ 9:10 pm

Hi Yair,

In the following example, my cursor pointer will not seem to change from the ‘default cursor’ shape to the ‘text cursor’ shape whenever I hover my cursor over the Password field edit box (that is, inside the bounds of the Password field box). How can I get my cursor to change to a ‘text cursor’ shape inside the bounds of the password field box?

figure1 = figure
jPasswordField = javax.swing.JPasswordField;
[jhPasswordField, hContainer] = javacomponent(jPasswordField, [20 20 100 40], figure1);

#27 Comment By Yair Altman On December 3, 2014 @ 11:41 pm

@David –

jPasswordField.setCursor(java.awt.Cursor.getPredefinedCursor(java.awt.Cursor.TEXT_CURSOR));

#28 Comment By David M On December 4, 2014 @ 6:50 am

Yair,

Thank you for the timely reply. However, after adding your line of code, the cursor still will not change to a ‘text cursor’ shape. Might there be another solution? I am using R2014a.

#29 Comment By Yair Altman On December 4, 2014 @ 2:27 pm

@David – changing the component cursor works well for me. In fact, the default JPasswordField cursor is the text cursor, so in theory you don’t need to set the cursor at all. So I suspect that there is something very specific on your system that causes this component to misbehave for some reason.

#30 Comment By Tal Kenig On May 5, 2015 @ 7:55 am

Hi Yair.
Just two comments:
1. With HG2 (R2014b), your overobj2() does not work:

fig = get(0,'PointerWindow');

should be replaced with:

fig = matlab.ui.internal.getPointerWindow();

2. It fails when the desired object is a uitab child – the position is referred to relative to the figure object and not the actual parent. It would be nice if the function would convert the object position to figure units.

Best regards,
Tal.

#31 Comment By Yair Altman On May 5, 2015 @ 9:09 am

@Tal – the article is 6 years old, and overobj2 itself is several years older than that, way before HG2 was even contemplated. If anything, I’m surprised that it worked well all the way till now. Anyway, I’ve updated the code for HG2, although (alas) not for the uitab issue that you mentioned. I’ll leave that as an exercise to the reader… :-)

#32 Comment By Michel Bertrand On June 14, 2015 @ 12:46 pm

I just saw on Matlab FEX,an overob2 wich is 90%+ a copy of overobj2 found on undocumentedMatlab (posted in 2009?), without any acknowledgments!!.

#33 Comment By Armindo On July 30, 2015 @ 7:27 am

Hi,

I try to use the:
function moveptr(hAx, x, y)

However I get the following error

Undefined function ‘getpos’ for input arguments of type
‘matlab.graphics.axis.Axes’.

How Can I solve this issue?


Article printed from Undocumented Matlab: https://undocumentedmatlab.com

URL to article: https://undocumentedmatlab.com/blog/undocumented-mouse-pointer-functions

URLs in this post:

[1] Image: http://undocumentedmatlab.com/feed/

[2] email feed: http://undocumentedmatlab.com/subscribe_email.html

[3] quite a few bugs: https://www.mathworks.com/matlabcentral/newsreader/view_thread/246598

[4] usage samples in CSSM: https://www.mathworks.com/matlabcentral/newsreader/search_results?search_string=overobj&page=1&dur=all

[5] A CSSM reader has noted: https://www.mathworks.com/matlabcentral/newsreader/view_thread/27539#68650

[6] undocumented hittest built-in function: https://www.mathworks.com/matlabcentral/newsreader/view_thread/239883#613421

[7] Context-Sensitive Help : https://undocumentedmatlab.com/blog/context-sensitive-help

[8] Tab panels – uitab and relatives : https://undocumentedmatlab.com/blog/tab-panels-uitab-and-relatives

[9] uitree : https://undocumentedmatlab.com/blog/uitree

[10] Customizing menu items part 1 : https://undocumentedmatlab.com/blog/customizing-menu-items-part-1

[11] uiundo – Matlab’s undocumented undo/redo manager : https://undocumentedmatlab.com/blog/uiundo-matlab-undocumented-undo-redo-manager

[12] An interesting uitree utility : https://undocumentedmatlab.com/blog/interesting-uitree-utility

[13] : #moveptr-args

[14] : http://www.mathworks.com/access/helpdesk/help/techdoc/ref/rootobject_props.html#zmw57dd0e284019

[15] : https://www.mathworks.com/matlabcentral/newsreader/

[16] : http://undocumentedmatlab.com/blog/findjobj-find-underlying-java-object

[17] : http://undocumentedmatlab.com/blog/changing-matlab-command-window-colors

Copyright © Yair Altman - Undocumented Matlab. All rights reserved.