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, here, and here.
To answer this need I have created the DataMatrix utility, which is available on the Matlab File Exchange:
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.
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)
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.
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 utility, or Yaroslav Don’s direct replacement cursorbar (see comment below), which apparently has the official approval of MathWorks and was selected as File Exchange Pick of the Week.