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

Undocumented cursorbar object

Posted By Yair Altman On September 29, 2010 | 40 Comments

Every now and then, I stumble on a Matlab feature that looks interesting and potentially useful and has existed for many previous Matlab releases, yet remains undocumented and unsupported. Today I present one such object, Matlab’s graphics.cursorbar.
The graphics.cursorbar object answers a very basic need that is often encountered in graph exploration: displaying data values together with horizontal/vertical cross-hairs, similarly to ginput.
While Matlab has provided the data-cursor mode for a long time, the cross-hair feature is still missing as of R2010b. Many CSSM newsgroup readers have asked about this missing feature. Some recent examples: here [1], here [2], and here [3].

DataMatrix

To answer this need I have created the DataMatrix utility [4], which is available on the Matlab File Exchange:

DataMatrix: customizable data tooltip & cross-hairs
DataMatrix: customizable data tooltip & cross-hairs

DataMatrix displays matlab’s standard data-cursor tooltip together with dotted cross-hairs, both of which move with the mouse pointer. DataMatrix is actually based mostly on fully-documented stuff: the undocumented aspects are secondary to the main program flow and mostly just ensure old releases compatibility and correct behavior in the presence of some figure modes.

graphics.cursorbar

When I created DataMatrix in 2007, I had no idea that graphics.cursorbar already existed. graphics.cursorbar is an internal Matlab object, that is undocumented and unsupported. It has several advantages over DataMatrix, being more customizable in the cross-hairs and data marker, although not enabling to customize the tooltip text nor to present both cross-hairs (only horizontal/vertical, not both). It is one of the earliest examples of Matlab’s old class system (schema-based).
We initialize a graphics.cursorbar object by supplying an axes (not very useful) or plot-line handle (more useful). The cursorbar handle can be customized using properties such as BottomMarker, TopMarker, CursorLineColor, CursorLineStyle, CursorLineWidth, TargetMarkerSize, TargetMarkerStyle, ShowText, Orientation, Position (Position is a hidden property) etc., as well as the regular HG properties (UserData, Visibility, Parent etc.).
Once the cursor-bar is created, it can be dragged and moved via the mouse cursor, as the following code snippet and animated gif show:

t=0:.01:7; hp=plot(t,sin(t));
hCursorbar = graphics.cursorbar(hp); drawnow
hCursorbar.CursorLineColor = [.9,.3,.6]; % default=[0,0,0]='k'
hCursorbar.CursorLineStyle = '-.';       % default='-'
hCursorbar.CursorLineWidth = 2.5;        % default=1
hCursorbar.Orientation = 'vertical';     % =default
hCursorbar.TargetMarkerSize = 12;        % default=8
hCursorbar.TargetMarkerStyle = 'o';      % default='s' (square)

Matlab's internal cursorbar object
Matlab's internal cursorbar object

Comments within the internal code (%matlabroot%\toolbox\matlab\graphics\@graphics\@cursorbar\*.m) suggest that graphics.cursorbar has been around since 2003 at least, although I have not checked such old releases. The presented tooltip resembles one of the old data tips, not one of the modern ones. In addition, as far as I can tell, graphics.cursorbar is not used within the Matlab code corpus. For these reasons it would not surprise me at all to find that MathWorks will remove this feature in some near future release. Until then – have fun using it!
Can you find a good use for graphics.cursorbar? if so, please let us know by posting a comment below [5].
Note: graphics.cursorbar was removed in Matlab release R2014b (8.4), as part of the transition to the new graphics system (HG2). Perhaps one day a replacement functionality will be added. Until then, we can use Michelle Hirsch’s dualcursor [6] utility, or Yaroslav Don’s direct replacement cursorbar [7] (see comment below [8]), which apparently has the official approval of MathWorks and was selected as File Exchange Pick of the Week [9].

Categories: Handle graphics, High risk of breaking in future versions, Stock Matlab function, Undocumented function


40 Comments (Open | Close)

40 Comments To "Undocumented cursorbar object"

#1 Comment By Yunde Shi On September 16, 2011 @ 13:03

Thanks a lot for the helpful tutorial on the cursorbar. I’m wondering how I could set the displayed text such as the “y: -0.7568” in this example. Can I also display the x-coordinate?

#2 Comment By Yair Altman On November 10, 2011 @ 10:31

@Yunde – you can change the graphics.cursorbar object’s UpdateFcn property to a custom text-update function handle, as described [16].

Also see this related article: [17]

#3 Comment By Fatnassi On November 8, 2011 @ 17:43

Really more useful. But for the spectral analysis, it will be fantastic to have two horizontal (dual) graphics.cursorbar at the same time in the same plot with displaying (x,y) values for each one

#4 Comment By Yair Altman On November 10, 2011 @ 10:22

@Fantassi – you can easily create multiple graphics.cursorbar objects by simply repeating the creation command and assigning two separate handles:

t=0:.01:7; hp=plot(t,sin(t));
hCursorbar1 = graphics.cursorbar(hp);
hCursorbar2 = graphics.cursorbar(hp);
% now customize the appearance of hCursorbar1 and hCursorbar2

#5 Comment By Fatnassi On November 12, 2011 @ 17:00

Hello Mr Altmann.
Thank you very much for your reply.
In the spite of the fact that I’m just a very slowly starter with matlab, I know that. That I’m looking for, is to obtain 2 vertical cursorbars that displays x-values or (x,y)-values not only y-values, and additionnaly 2 horizontal cursorbars that displays y-values or (x,y)-values not only x-values.
Thank you again

#6 Comment By Yair Altman On November 14, 2011 @ 00:33

@Fatnassi – see my answer above to @Yunde. For horizontal cursorbars use the Orientation property. If you still need my help in customizing your application, please contact me via email (see the link at the top-right of this webpage) – I would be happy to help you for a compensation of my time and expertise.

#7 Comment By JP On January 29, 2012 @ 09:08

Yair,
Thanks, this is incredibly helpful. Is there a way to link multiple cursorbars, on the same axes object or a different axes object, so that when you move one cursor bar, the linked ones follow the same movement?

If not, is there a way to programmatically move the position of the cursorbar so after one moves, you would be able to move others to the same x axis location (for a vertical orientation)?

Thanks!

#8 Comment By Yair Altman On January 29, 2012 @ 14:09

@JP – use the linkprop function

#9 Comment By reivajtux On January 7, 2013 @ 02:40

Thank you! extremely useful information. I’ve been using this script but I’m having some troubles customizing the marker color. For some reason, the edit plot feature shows that the cursorbar has a TargetMarkerFaceColor and a TargetMarkerEdgeColor option, but it seems they are not working for me and I can’t change the marker color… any suggestion?

#10 Comment By Yair Altman On January 7, 2013 @ 03:22

@reivajtux – You are correct, it is due to an internal Matlab bug. Here is the workaround, based on the cursorbar’s hidden property TargetMarkerHandle:

hCursorbar.TargetMarkerHandle.MarkerEdgeColor = 'r';
hCursorbar.TargetMarkerHandle.MarkerFaceColor = 'g';

You can also use TargetMarkerHandle to update other aspects of the target marker, such as LineStyle, LineWidth, [18], or Visible.

#11 Comment By J On April 1, 2013 @ 11:17

I’ve been playing around with the cursorbar today and it is surprisingly functional. I have spectra plots with multiple axis and plots on each axis. This does work very well for multiple line series on a given axis, you just have to use an array of line series handles to create the cursorbar. It will then show the y-values for each plot, pretty neat.

It doesn’t really seem to work across multiple axes, it does show all the values, but the y-value lables are postioned to the primary y-axis only. But there may be some way to cheat with the input data so it does work.

#12 Comment By Malcolm Lidierth On April 3, 2013 @ 06:01

@J
[19]might be of some help across multiple axes.

#13 Comment By jinu On May 6, 2013 @ 17:58

Very cool…is there any way to link this to multiple figures? i.e. if I move the cursorbar in one figure..it will update it in another. Also kind seperate…is there a way to tile figures using a script. I can do it manually by using the “Tile” button in the upper right hand corner of the figure window. Was hoping to do this with a script. Very cool site…looking forward to reading the book

#14 Comment By Yair Altman On May 28, 2013 @ 17:07

@Jinu – you could probably use [20] to link the cursor-bar to another figure.

#15 Comment By dan On September 22, 2013 @ 15:16

Thanks for sharing Yair, this seems to be quite useful.
I am implementing this in a GUI to allow the user to graphically select a value on the y-axis of a data plot. I basically invoke the cursorbar in a callback of a pushbutton and several cursorbars can be added to the plot. I am using it instead of ginput, because the plot is located in an axes environment (where i can’t change the pointer property), and it is very neat that you can use purely horizontal or vertical bars which have the exact extension of the axes.

I just have a small problem, maybe somebody can help me out. When adding a second, third.. cursorbar: The cursorbar is always drawn at the location of the CurrentPoint value of the axes, which is usually the exact place where already the previous cursorbar is parked. I prefer to have them occur at a different position, but if i give a position as input argument it will be overwritten by the CurrentPoint value. Does somebody have an idea how to handle this?

#16 Comment By dan On September 25, 2013 @ 06:39

found a rather simple solution to my problem… i can just reset the ‘CurrentPoint’ of the parent figure each time before adding a cursorbar.

Anyways, now it works quite nicely.. so once again: Great tool, thanks!

#17 Comment By nikhil On December 15, 2013 @ 13:13

Hello Yair Altman,

Thank you for the great solution (I have been looking for this from the past few weeks. Finally…)

I have a couple of questions:
1. I did update (as you explained in one of your comments) the position of the cursorbar using the update function and display in the text box (as in the animated gif) is not changing the position when i move the cursorbar as expected.
2. Is there a possibility even to show the position of ‘X’ data in the small text

By the way an excellent website 🙂

#18 Comment By Yair Altman On December 15, 2013 @ 15:16

@Nikhil – I don’t have an immediate answer but I’m pretty sure that it can be done by either modifying the Matlab code or using some hooks from the graphics.cursorbar object (hCursorbar). Don’t be lazy, dig in to discover it yourself – this makes it much more fun. Then come back here and report what you found.

#19 Comment By nikhil On December 24, 2013 @ 13:05

Hello Yair Altman,

Thank you for the support & suggestion. It’s really fun searching for the solutions from the hooks you suggested. I found the solution by including the code:

set(hCursorbar1.DisplayHandle,'Position',pos,'string',StringText)

in the UpdateFcn property callback.
pos is the current position of the cursorbar
StringText: pos(1:2)

#20 Comment By nikhil On December 24, 2013 @ 13:40

It’s described in defaultUpdateFcn.

#21 Comment By nicolas On April 25, 2014 @ 02:26

Hello Yair Altman,
Thanks for sharing.
I am currently trying to use the cursorbar on a spectrogram figure (with the spectrogram function) but I keep getting the following error : “Target must be a single axes handle, or an array of line handles”.
I guess it is because the spectrogram plot is in 3D, but I cannot find any solution (I’m a beginner in matlab).
If you have any idea, I would be very grateful.
Thanks in advance.
Best
-Nicolas-

#22 Comment By Yair Altman On April 25, 2014 @ 03:44

@Nicolas – I don’t currently have the Signal Processing Toolbox, so I’m afraid I can’t help you with this, you’ll need to debug it by yourself…

#23 Comment By nicolas On April 25, 2014 @ 05:28

Ok, I’ll try to find a solution.
Just for you to know, I also tried to display the cursorbar on a spectrogram drawn with the [21], and I get exactly the same error.

#24 Comment By nicolas On May 2, 2014 @ 07:23

Dear Yair,
Is there a way to also get the Y value when using the horizontal mode?
Thanks
-nicolas-

#25 Comment By Yair Altman On May 4, 2014 @ 14:40

See [22]

#26 Comment By Christoph On September 9, 2014 @ 01:05

Dear Yair,

I tried to link two cursorbars with the linkprop-function (as you suggested before) via the (hidden) ‘Position’-Property. As the ‘Position’ contains the x- as well as the y-Position some malfunctions occur (both cursorbars have the same x AND y-Positions) and the textbox of one of the bars doesn’t update anymore. I guess just the x-Positions should be linked. Is there a way to do so / what am I doing wrong?

Thanks in advance
Christoph

#27 Comment By Yair Altman On September 9, 2014 @ 02:47

You cannot link only part of a property value. Instead, try using a property listener to set a custom callback function, that will update only the relevant part.

#28 Comment By Christoph On September 11, 2014 @ 11:18

I failed to follow your advice – I really tried. Let’s say we have this:

t=0:0.01:(2*pi);
ax = plotyy(t,sin(t),t,2*cos(t));

How could I get one (or two superposed) cursorbar(s) into this figure showing the datapoints of both lines. Your help would be great here. Thank You 🙂

#29 Comment By Yair Altman On September 11, 2014 @ 14:34

@Christoph – you can modify the code of graphics.cursorbar (%matlabroot%/toolbox/matlab/graphics/@graphics/@cursorbar/cursorbar.m) to add support for plotyy. It shouldn’t be too difficult – the source code only has ~430 lines of code and plenty of comments.

#30 Comment By Christoph On September 30, 2014 @ 06:00

Hi Yair,

thank you for your suggestions. I do not have write permissions for these files and cannot edit them. Do you have any other idea, how to solve my problem?
Furthermore is it possible to synchronize two cursorbars within different subplots?

Christoph

#31 Comment By Yair Altman On September 30, 2014 @ 06:05

You can place a modified copy of the file(s) in your own user path, where it takes precedence over the built-in path. To synchronize different cursorbars, you can use the linkprop function.

#32 Comment By Christoph On October 1, 2014 @ 02:04

Hi Yair,

nevermind – I finally did it.
As I mentioned before, linkprop does not show the desired behaviour.
I added a listener via “handle.listener” function on the position property to call the update-function for all involved cursorbar handles and it works fine. A bit slow in case of many cursorbars but it is OK.

So there was no need to copy or edit any matlab-files.

Thank you
Christoph

#33 Comment By Dan On October 21, 2014 @ 04:33

Hello Yair, i’ve been using this feature for a while now, thanks again for pointing it out.
I think this feature has eventually been removed with the 2014b release (At least i can not find it anymore). Do you know anything that is on par, as a replacement?

#34 Comment By Yair Altman On October 21, 2014 @ 08:27

@Dan – try Michelle Hirsch’s [6] utility. She’s the Matlab product manager at MathWorks, by the way.

#35 Comment By Dan On October 21, 2014 @ 09:15

Thanks, I will check it out!

#36 Comment By Yaroslav On January 22, 2015 @ 13:52

@Yair,

I have also encountered the same issue as @Dan — Being a very useful feature, some of my files rely heavily on graphics.cursorbar. Unfortunately, after TMW had decided to remove it, my programs ceased to work at all. Therefore, I needed a fast, reliable and indistinguishable solution (the last requirement is important: I didn’t want to modify large chunks of code).

Simiarly to @Dan, I also couldn’t find an adequate solution; thus, I decided to take the mission on myself. Taking all the old files in +graphics/@cursorbar, I modified them so that they work with HG2. Mainly, I merged schema and cursorbar to a single file built in Matlab’s new class system, and made a few minor changes to all other files. Since it is basically the same ol’ code, it works like a charm; almost no changes were required to my programs, and I feel it is even faster than the old cursorbar.

Now I have a dilemma: I want to publish my solution on the File Exchange, but most of the code and the entire logical structure is still TMW’s. Since I wish to avoid plagiarism and copyright issues, it creates quite a nuisance. How do you suggest to proceed?

#37 Comment By Michelle Hirsch On February 13, 2015 @ 11:38

With a gigantic thanks to Yaroslav, we now have an updated for R2014b version of cursorbar posted on the File Exchange: [7]. I believe it’s a straight drop-in replacement that should support code written against the undocumented cursorbar from previous releases.

#38 Comment By micpro On September 19, 2016 @ 15:20

Hi,
Thanks for sharing,
How can I change default position of cursuor? I need to 2 cursor bars and I want to see them seperately,
thanks

#39 Comment By Yaroslav On November 2, 2016 @ 22:38

Use the Location or the Position properties. For example,

% set the plot
t     = 0:.01:7; 
hPlot = plot(t,sin(t));
% draw the cursorbars
if verLessThan('matlab','8.4.0') % HG1 version
    hCursorbar1 = graphics.cursorbar(hPlot);
    hCursorbar2 = graphics.cursorbar(hPlot);
else % HG2 version, latest version on FEX
    hCursorbar1 = cursorbar(hPlot);
    hCursorbar2 = cursorbar(hPlot);
end
% now, set the locations
hCursorbar1.Location = 2; 
hCursorbar2.Location = 4; 

#40 Comment By MacDonald Smith On November 2, 2016 @ 18:40

Yair,

I was trolling around on this section a few weeks ago and I thought I saw a link to the File Exchange for a function that plotted multiple cursor bars on a Magnitude/Power Spectrum that indicated a fundamental plus several harmonics. I cannot find this link anymore. Do you recall where this link might be or what the name of the function might be?


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

URL to article: http://undocumentedmatlab.com/articles/undocumented-cursorbar-object

URLs in this post:

[1] here: https://www.mathworks.com/matlabcentral/newsreader/view_thread/278992

[2] here: http://www.mathworks.cn/matlabcentral/newsreader/view_thread/289787

[3] here: http://www.mathworks.cn/matlabcentral/newsreader/view_thread/288484

[4] DataMatrix utility: http://www.mathworks.com/matlabcentral/fileexchange/16181-datamatrix

[5] below: http://undocumentedmatlab.com/blog/undocumented-cursorbar-object/#respond

[6] dualcursor: http://www.mathworks.com/matlabcentral/fileexchange/2875-dualcursor

[7] cursorbar: http://www.mathworks.com/matlabcentral/fileexchange/49612-cursorbar

[8] comment below: http://undocumentedmatlab.com/blog/undocumented-cursorbar-object#comment-345555

[9] File Exchange Pick of the Week: https://blogs.mathworks.com/pick/2017/09/08/cursorbar

[10] getundoc – get undocumented object properties : http://undocumentedmatlab.com/articles/getundoc-get-undocumented-object-properties

[11] Handle object as default class property value : http://undocumentedmatlab.com/articles/handle-object-as-default-class-property-value

[12] Accessing private object properties : http://undocumentedmatlab.com/articles/accessing-private-object-properties

[13] General-use object copy : http://undocumentedmatlab.com/articles/general-use-object-copy

[14] Types of undocumented Matlab aspects : http://undocumentedmatlab.com/articles/types-of-undocumented-matlab-aspects

[15] FindJObj – find a Matlab component's underlying Java object : http://undocumentedmatlab.com/articles/findjobj-find-underlying-java-object

[16] : http://www.mathworks.com/help/techdoc/ref/datacursormode.html#zmw57dd0e87879

[17] : http://UndocumentedMatlab.com/blog/controlling-plot-data-tips/

[18] : http://undocumentedmatlab.com/blog/plot-linesmoothing-property/

[19] : http://www.mathworks.co.uk/matlabcentral/fileexchange/14093-data-cursors-for-figure-window

[20] : http://undocumentedmatlab.com/blog/continuous-slider-callback/

[21] : http://www.mathworks.com/matlabcentral/fileexchange/24321-plotspectrogram

[22] : http://undocumentedmatlab.com/blog/undocumented-cursorbar-object#comment-304381

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