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 (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. 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 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 – 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.
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
@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.
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?
@Joel – moveptr usage is explained here and the root’s PointerLocation property is explained here.
[…] we could use the semi-documented moveptr function, which was described here last […]
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
@Rahul – this blog is dedicated to undocumented Matlab features and functionality. If you need general Matlab help, please use the CSSM newsgroup, or ask MathWorks technical support, or email me directly for consulting.
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
Joel Lim @ Here is the matlab code to move cursor by detecting specific color……
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:
best regards
@farfyy – thanks. Users should note that this requires the Image Processing Toolbox.
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.
@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.
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.
@Matt – Thanks for the tip
Hi,
Is there anyway to do the thing moveptr does but on a 3d axis. moveptr does not accept 3 inputs as coordinates.
Thanks
@Oytun, I fear that you will need to do the 3D-2D transformation yourself.
Thank you Yair.
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:
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:
did not work again. Any thoughts?
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
@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.Excellent post Yair, but… How would you get the handle of an axes control that is within the GUI?
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.
@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. here and here).
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?
@David –
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.
@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.
Hi Yair.
Just two comments:
1. With HG2 (R2014b), your overobj2() does not work:
should be replaced with:
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.
@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… 🙂
I just saw on Matlab FEX,an overob2 wich is 90%+ a copy of overobj2 found on undocumentedMatlab (posted in 2009?), without any acknowledgments!!.
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?