Cursor commands

The 'Xstring' and 'Ystring' plt arguments allow you to add text strings just to the right of the cursor X or Y readout values. Since these strings occupy the same screen area as the delta cursor readouts, they get covered up when you are in delta cursor mode (or a if a zoom window is visible). However those are usually temporary modes, so as you will see, these strings still prove useful. The main feature which makes them so useful is the string replacement feature. Strings on the left column in the table below are replaced with the value shown in the right column. (It is important to note that Xstring and Ystring are both updated every time the cursor is moved.)

String	Replacement value
@CID	cursor ID
@XVAL	active cursor X position
@YVAL	active cursor Y position
@XY	same as complex(@XVAL,@YVAL)
@IDX	active cursor index
@HAND	handle of active trace
@LNUM	line number of active trace
@XU	Xstring user value
@YU	Ystring user value

Examples:

Suppose it was important to see the cursor index as well as the usual cursor x and y values (i.e. you want to know that your are looking at the sixty fifth data element for instance). You could do this as follows:

plt(x,y,'xstring','sprintf("index = %d",@IDX)');

A string within a string (such as the 'index = %d' above) is normally written in Matlab using two consecutive single quote characters on both sides of the string. Since this can get verbose and confusing at times, callbacks defined within plt may use a double quote character instead of two successive single quotes. That's why the double quotes appear in the line above.

Although the mean of the active trace y values can be shown using on of the usual cursor features, suppose you wanted to display the mean of the entire data set (independent of the viewing window). Suppose also that you want to continuously display the y/x ratio. (This ratio is also a standard cursor feature, but its not continuously visible.) You could accomplish both of those feats as follows:

plt(x,y,'xstring','sprintf("mean: %f",mean(get(@HAND,"y")))',...

        'ystring','sprintf("Y/X: %5.3f",@YVAL/@XVAL)');

Suppose your x axis is measured in seconds with a zero reference of 5pm, 21-Jan-2007 UTC. The cursor x-axis readout will be in seconds past the reference, but you may want an additional cursor readout that shows the actual time of day. This can be accomplished as follows:

plt(t,y,'xstring',...

  'sprintf("utc: %s",datestr(datenum("21-Jan-07 17:00")+@XVAL/86400,13))');

Note the 86400 (the number of seconds in a day) is needed because date numbers are measured in days. If your x axis unit was "weeks", you would replace /86400 with *7.  If you removed the ,13 near the end of the line (date string format), then the readout would show the complete date and time instead of just the time. Another way to code the statement above is:

plt(t,y,'xstring','sprintf("utc: %s",datestr(@XU+@XVAL/86400,13))');

set(findobj(gcf,'tag','xstr'),'User',datenum(2007,1,21,17,0,0));

The second statement puts the reference time in the Xstring user value which is used by plt when updating the Xstring. This method is much more convenient when the reference time can change. Note that the reference time is identical to that used above, although it's written in the vector format instead of the character format.

Sometimes the 1 second resolution provided by datestr is not sufficient. You can increase this resolution to 1 millisecond by using the date string function provided by plt as follows:

plt(t,y,'xstring','sprintf("utc: %s",plt("datestr",@XU+@XVAL/86400,13))');

Occasionally its useful to use an edit box instead of a string for one or both of these customized cursor controls. (The pltn.m example does this for the Xstring, although the Ystring is still rendered as a text string.) To do that, simply insert a question mark before the string. The first example above is rewritten below to use an edit box. .

plt(x,y,'xstring','?sprintf("index = %d",@IDX)');

[xy k] = plt('cursor',cid,'get','position',n);

Get x and y coordinates of the cursor location the last time it was on trace #n. The trace number is optional - if it is not specified then the position of the active trace is returned. xy is a complex value. Its real part is the cursor x-coordinate and its imaginary part is the y coordinate. The second return value (if requested) is the index into the x data vector of the cursor position.

[n h] = plt('cursor',cid,'get','activeLine');

Returns the line number of the active cursor. The second return value (if requested) is the handle of the active trace.

h = plt('cursor',cid,'get','obj');

Returns an 11 element vector of handles to the following cursor objects:

1:  x label	5:  y cursor readout	09:  delta button
2:  y label	6:  y cursor expansion	10:  expansion box
3:  x cursor readout	7:  peak button	11:  delta cursor
4:  x cursor expansion	8:  valley button

u = plt('cursor',cid,'get','expHis');

Returns an array containing the display expansion history.
Each row contains one display expansion as [xmin, xmax, ymin, ymax, code] where:

• code = -1  indicates the row was not used
• code = 0   indicates a valid display expansion
• code = 1   indicates the current display limits

plt('cursor',cid,'set','visON');

plt('cursor',cid,'set','visOFF');

Shows or hides the following objects:

• peak/valley/delta cursor buttons
• active trace cursor
• auxiliary trace cursor (if right hand axis is active)
• x and y axis edit boxes and respective labels
• xstring and ystring objects
• x-cursor slider

• cursor id string

Note that this function is invoked alternately (visOFF/visON) when you right click on the plot y-axis label (which also hides/shows the menu box).

plt('cursor',cid,'set','aux','on');

plt('cursor',cid,'set','aux','off');

Shows or hides the auxiliary (right hand axis) cursor and its edit box

plt('cursor',cid,'set','position',p);

p is a 9 by 4 element array. Each row contains (x,y,width,height) which represents the position and size of the following objects:

1. x-axis edit box label
2. y-axis edit box label
3. x-axis edit box (cursor readout)
4. x-axis cursor expansion edit box
5. y-axis edit box (cursor readout)
6. y-axis cursor expansion edit box
7. peak button
8. valley button
9. delta cursor button

Note that this command does not set the position of the optional x-axis control slider. However you can set this position with a command such as:
set(findobj(gcf,'tag','xslider'),'position',p);

plt('cursor',cid,'set','xlim',p);

Set new x axis limits and update expansion history, p=[xmin,xmax]

plt('cursor',cid,'set','ylim',p,pAux);

Set new y axis limits and update expansion history, p=[ymin,ymax].
pAux (for the right hand axis) is optional

plt('cursor',cid,'set','xylim',p,pAux);

Set new x and y axis limits and update expansion history,
p=[xmin,xmax,ymin,ymax], pAux=[ymin,ymax] (pAux is optional)

plt('cursor',cid,'set','expHis',u);

Restores an expansion history previously saved in u.

plt('cursor',cid,'set','axisCB',fcn);

String fcn will be evaluated whenever an axis limit is changed. This cursor command overwrites any axis callback function entered using the 'axisCB' or 'NewLimit' parameters on the plt command line. The rules for string substitutions and function handles are the same as mentioned below in the moveCB command.

plt('cursor',cid,'set','moveCB',fcn);

String fcn will be evaluated whenever the cursor is moved. Before the fcn string is evaluated all occurrences of  the strings in the 1st column of the table above ( @CID, @XVAL, @YVAL, @XY, @IDX, @HAND, @LNUM, @XU, @YU) are replaced with the values in the 2nd column of that table. fcn is not called by events initiated from outside the figure window containing the cursor. (For example a button push that moves the cursor in another figure window would not activate the callback. This prevents infinite loops when figure A modifies figure B's cursor and visa versa.) If you do want to enable the callback for external events, insert an extra semicolon as the first character of the moveCB callback string. This cursor command overwrites any axis callback function entered using the 'moveCB' parameters on the plt command line. In addition to a string, fcn may also be a function handle of the form @func or {@func,arg1,arg2,...,argn}. Note that the string substitutions can't be used with the function handle form of this parameter.

Also note that a similar callback is provided for the TraceId fields, although the string substitutions allowed are different than the ones mentioned above. See the 'TIDcback' parameter under Trace properties.

plt('cursor',cid,'set','activeLine',a,k);

Switches the active cursor to the line specified by  a (a must be an integer between 1 and the number of lines in the plot). The cursor will be placed at index k which must not exceed the length of the line's x and y data. k is optional (default=1). When a is zero (a special case), the active line remains the same and only the cursor index is changed. That is similar to the mainCur command (below) except that mainCur also executes the cursor callback.

plt('cursor',cid,'mainCur',k);

Moves the active cursor to the index k in the data set and calls any user defined cursor callbacks (moveCB, xstring, ystring). To run the cursor callbacks without moving the cursor, set k to zero.

plt('cursor',cid,'peakval',0);
plt('cursor',cid,'peakval',1);

Moves the active cursor to the next peak (0) or to the next valley (1)

plt('cursor',cid,'clear');

All the cursor objects are deleted.

plt hideCur;

Has the same effect as right clicking on the y-axis label. See cursoring. If you also want to hide the TraceID box, use the commands tbox=findobj('user','TraceID'); set([tbox; get(tbox,'child')],'vis','off').

Ret1 = plt('cursor',[axis auxAxis],'init',In1,In2,In3,In4,In5,In6,In7,In8,In9);

Usually the cursor objects are initialized from the main plt() call that specifies the data arrays to be plotted. However you may also create the cursor objects using this cursor 'init' call after creating a figure on your own (i.e. without using plt).

Ret1:    The cursor ID (cid) used to control the cursor with additional calls to plt.

axis:    This is a scalar if the cursor is assigned to a single axis. A two element row vector is used to assign the cursor to a pair of axes. The second axis (auxAxis) is normally overlayed on top of the primary axis and is used to provide a separate y-coordinate axis on the right and side of the graph.

In1:    A 10 by 4 array containing the positions of the cursor controls. Each row contains [x y w h] where x,y is the position of the control and w,h is its size. The units for all the values in the In1 array must be either pixels or normalized (i.e no mixing units). The last row specifies the position of the slider and is the only optional row. If In1 contains only nine rows then the x-axis cursor slider will not be created. The rows of In1 are assigned as follows:

Row	[x y w h]
1	label for x cursor readout
2	label for y cursor readout
3	x cursor readout
4	x cursor expansion
5	y cursor readout
6	y cursor expansion
7	peak find button
8	valley find button
9	delta cursor button
10	x-axis cursor slider (OPTIONAL)

In2:    A  three column array [red green blue] specifying the colors for the cursors and cursor readout text. The rows of In2 are defined as follows:

Row	[r g b]	notes
1	x/y cursor label color
2	cursor readout color	Set to [0 0 0] to track the cursor readout to the associated line color.
3	expansion box color
4	delta cursor color
5	line #1 cursor color	Set to [0 0 0] to track the cursor color to the associated line color.
6	line #2 cursor color	"
...	...	"
4+n	line #n cursor color	" (Must have a row for each line object that has a cursor.)

In3:   Text for the x/y cursor labels. ['xlabel';'ylabel'] or {'xlabel', 'ylabel'}

In4:   Cursor markers. Must have one marker for each line that has a cursor. For example for three lines one could use '+ox' or to use the same symbol for all three cursors use '+++'.

In5:   Cursor size (in points)

In6:   Format strings for x and y cursor readouts. e.g. ['%2.1f'; '%5w  '] or  {'%2.1f','%5w'}. See ftoa for a description of the format strings.

In7:   Visible flag (first optional argument).   'on' or 'off'.

In8:    Monotonic flag (optional). Set to 1 if the x data is monotonically increasing,  and 0 otherwise (such as with Nyquist plots).

In9:   Axis limit change callback function (optional). Executed when the axis limits are changed.