Cursor commands
The cursor pseudo object, the most complex pseudo object supported by plt,
consists of one or more markers and several uicontrols with complex
interactions. Because of this you normally will not create cursor objects on
your own, but will rely on plt to create them automatically when you specify the
data to be plotted. However it is possible to create a cursor object manually
with the cursor init command described at the end of this section. For many
casual plotting applications, the plt cursors will behave as desired out of the
box. For more sophisticated applications you may want to modify the cursoring
behavior using the plt parameters (DualCur, Xstring, Ystring, Options) or the independent
cursor commands shown below.
DualCur parameter:
Normally the cursor value for only a single trace (referred to as the active trace) is
shown in an edit box below the plot. However sometimes it is convenient to show the
y-value for two traces simultaneously. This is done by using the 'DualCur'
parameter which specifies a trace which will always have a display of its y-value on the screen
in addition to the display of the active trace. Try out the
editz.m demo program which uses Dual Cursors to simultaneously
display the magnitude and phase of a transfer function. (In fact, transfer
function displays were the problem that inspired the Dual Cursor feature.)
The alternate method of specifying the dual cursor trace (as an offset from the active trace)
is indicated by using a negative number for the DualCur parameter. The demo program
afilt.m demonstrates the use of that mode.
The use of the DualCur mode is covered in more detail near the end of the cursoring guide
found here: Cursoring.
Xstring and Ystring parameters:
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.
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 |
Most of the power of the Xstring and Ystring parameters stem from
their string replacement feature described in this table.
Strings in the first column of the table
are replaced with the value shown in the second column.
(The Xstring and Ystring are both updated every time the cursor is moved.)
Xstring/Ystring 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 one 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','prin("Y/X: %5w",@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)');
See the following demo programs, for more examples of the use of the Xstring or Ystring:
afiltALT,
editz,
gpsLog,
movbar,
pltn,
pub2, and
tasplt.
Cursor commands
Notes:
|
The cid (cursor ID) that appears in all the commands
shown below is an integer that identifies the cursor the command is to act on.
This integer is returned from the cursor initialization command used to create
the cursor. If an axis contains a cursor, its cid is saved in the axis user data.
(The cid stored in the axis user data is always a scalar since an axis may only
contain a single cursor object.) You can specify that the cid should be retrieved
from the axis user data by specifying a zero for the cid.
So for example the following two commands have the same effect:
plt('cursor',0,'visON')
plt('cursor',get(gca,'user'),'visON')
|
|
The figure 'cid' application data variable contains a
vector with the cursor IDs for all the cursor objects in the figure. You can
specify that the cid should be retrieved from this vector by supplying a negative
number as the cid (for example -2 specifies the 2nd element of this vector). This means
that the following two lines have the same effect:
xy=plt('cursor',-2,'get');
c=getappdata(gcf,'cid'); xy=plt('cursor',c(2),'get');
|
|
All the following commands are case sensitive (unlike all the other plt parameters
previously described) and must use the exact case shown below. |
|
All the cursor commands below may return up to two arguments. If the return
arguments are listed for a cursor command, the return values will be as specified.
However if the return arguments are not listed for a particular command, the
first return value (if requested) will be the active cursor handle and the second
return value (if requested) will be the active line handle. |
|
See the following demo programs for examples of the use of the cursor commands described below:
afilt,
afiltALT,
editz,
gauss,
gpsLog,
julia,
movbar,
pltmap,
pltn,
pltsq,
tasplt,
trigplt,
weight, and
winplt.
|
[xy k] = plt('cursor',cid,'get',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,'getActive');
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,'obj');
Returns an 13 element vector of handles to the following cursor objects:
1: x label |
5: y cursor readout |
09: marker line-style button |
13: cursor marker |
2: y label |
6: y cursor expansion |
10: delta button |
3: x cursor readout |
7: peak button |
11: expansion box |
4: x cursor expansion |
8: valley button |
12: delta cursor |
|
u = plt('cursor',cid,'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,'visON');
plt('cursor',cid,'visOFF');
Shows or hides the following objects:
- peak/valley/delta cursor buttons
- active trace cursor
- auxiliary trace cursor (dual cursor)
- 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,'aux','on');
plt('cursor',cid,'aux','off');
Shows or hides the auxiliary (dual) cursor and its edit box
plt('cursor',cid,'setObjPos',p);
Sets the cursor object positions to p, where 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:
- x-axis edit box label
- y-axis edit box label
- x-axis edit box (cursor readout)
- x-axis cursor expansion edit box
- y-axis edit box (cursor readout)
- y-axis cursor expansion edit box
- peak button
- valley button
- 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 using the plt 'xy'
parameter, or with a command such as:
set(findobj(gcf,'tag','xslider'),'position',p);
plt('cursor',cid,'xlim',p);
Set new x axis limits and update expansion history, where p=[xmin,xmax]
Normally the action string ('xlim' in this case) is case insensitive, but for this command
the case of the 'L' character is significant. If the L is lower case then the
axis callback function is executed after the axis limits have been updated and if the L is upper case then
the axis callback function is not executed. The case of the other characters in the action string are ignored
(so 'xLim' and 'XLIM' are equivalent). This sensitivity to the case of the L character applies to the next two
cursor commands described below as well ('yLim' and 'xyLim')
plt('cursor',cid,'ylim',p,pAux);
Set new y axis limits and update expansion history, where p=[ymin,ymax].
and optionally pAux=[ymin,ymax] (for the right hand axis).
plt('cursor',cid,'xylim',p,pAux);
Set new x and y axis limits and update expansion history, where p=[xmin,xmax,ymin,ymax].
and optionally pAux=[ymin,ymax] (for the right hand axis).
plt('cursor',cid,'exRestore',u);
Restores an expansion history previously saved in u.
plt('cursor',cid,'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' parameter 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,'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,'moveCB2',fcn);
This call operates similarly to the set moveCB command
shown above and the functions specified in both these calls are executed whenever
the cursor is moved. However normally you will not want to use this call because
the moveCB2 function is used internally by plt to
keep the CursorID tag (just to the left of the y-axis cursor readout) so that it
always identifies the cursored trace name. It's also used by plt in the linked
subplot mode to keep the plots in a column synchronized. In rare situations you may
wish to modify those behaviors, which you can do with the moveCB2
function.
plt('cursor',cid,'setActive',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. If k (optional) is out of bounds or not supplied,
then the cursor will be placed in the center of the array.
When a is zero (a special case), the active line
remains the same and only the cursor index is changed - which would have the the
same as calling the update command (below).
plt('cursor',cid,'update',k);
plt('cursor',cid,'updateH',k);
plt('cursor',cid,'updateN',k);
Moves the active cursor to index k in the data set and calls any user
defined cursor callbacks (moveCB, xstring, ystring). If k is out of bounds, the
cursor is set to the middle of the array associated with the active trace.
If you do not supply the argument k, then the command does not move the cursor,
however it does execute the cursor callbacks. If
update moves the cursor to an area that is not inside
the current axis limits, it will shift the axis limits to make the cursored data
element visible. However when the cursor is moved by updateH
the axis limits will never be adjusted. (Think of this as "Update, Hold".)
Also updating the cursor with the updateN command has the
same effect as using the updateH command except that the
cursor callback function (defined by 'MoveCB') is not
called like it is with the update and
updateH commands.
When the index is not needed we can abbreviate the update command by omitting
the 'update' string. This means that the following two lines are equivalent:
plt('cursor',cid);
plt('cursor',cid,'update');
We can abbreviate the update command even more by omitting the cursor ID
which defaults to -1. This means that the following two lines are equivalent:
plt('cursor');
plt('cursor',-1);
And finally there is one more variant of the update and updateH commands:
plt('cursor',cid,'update',k,x,y);
plt('cursor',cid,'updateH',k,x,y);
The moves the active cursor to the index k as above. Normally x and y would be
the position of the kth element of the array associated with the active trace,
in which case this command behaves the same as if you didn't include the
last two parameters. However x and y can be any position on the axis, and
the visible cursor marker will be moved to those coordinates. (It's rare
to want to move the cursor off the line, but it may sometimes be useful.)
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('cursor',cid,'TraceIDs');
Returns a cell array containing the TraceIDs associated with cursor cid.
For example, when running the demo program afilt.m, if you click on the left hand
plot and then type plt('cursor',0,'TraceIDs')
you will see:
ans = 5×1 cell array
{'Butter'}
{'Bessel'}
{'Cheby1'}
{'Cheby2'}
{'Elliptic'}
plt hideCur;
Hides the cursor objects. (This has the same effect as right-clicking on the y-axis label).
See cursoring.
plt hideTID;
Hides all the TraceID boxes in the current figure
Note: The following cursor commands were designed primarily for plt internal use,
although sometimes they may also be useful in your programs. (These commands are case sensitive.)
The "0" in the first seven commands below refers to the current cursor. You may replace the "0"
with the actual cursor ID number, or "-n" to refer to the nth cursor.
plt cleft 0 ZoomOut; |
Zoom out both x & y axis by 40%. |
plt cright 0 ZoomOut; |
Zoom in both x & y axis by 40%. With the functional form (which applies to the command above
as well), you may also include an additional argument which specifies the zoom ratio.
For example, this command specifies a 20% ratio (half of the default amount):
plt('cright',0,'ZoomOut',.2);
|
plt cleft 0 peakval 0; |
Move the cursor to the next peak. (The last argument may be omitted in this case.) |
plt cleft 0 peakval 1; |
Move the cursor to the next valley |
plt cleft 0 peakval 2; |
Reset the peak finder (i.e. move the cursor to the highest peak) |
plt cleft 0 peakval 3; |
Reset the valley finder (i.e. move the cursor to the lowest valley) |
plt cleft 0 TGLlogy; |
Toggle the y-axis between linear/log |
plt cleft 0 TGLlogx; |
Toggle the x-axis between linear/log |
plt cright 0 TGLlogy; |
Open Hardcopy menu |
plt cright 0 TGLlogx; |
Swap x & y axes |
plt cleft 0 markCB; |
Toggle the delta cursor mode on or off |
plt cleft 0 mlsCB; |
3 way toggle of all traces between markers only, lines only, and both lines & markers |
plt cleft 0 mark; |
Adds a text label identifying the current cursor location |
plt xleft TGLgrid; |
Toggle between grid lines and ticks |
plt xright TGLgrid; |
Toggle between default and alternate grid style |
plt xleft TGLmenu; |
Toggle the menu bar on/off |
plt xright TGLmenu; |
Open a cursor data window |
plt xleft mark 2; |
Open a window allowing editing plt figure colors |
plt xleft mark 3; |
Write a file saving the current plt figure colors |
plt xleft link; |
Toggle right hand axis link status |
plt xleft RMS; |
Equivalent to clicking on the cursorID tag which rotates between the five cursor modes
[normal, Avg, RMS, y/x, sqrt(x^2+y^2)]. After five of these commands the cursor mode
will be the same as it was before the first of those commands (having rotated thru
all the modes).
|
plt xleft EDIT 1; |
Enter data editing (using last used editing mode) |
plt xleft EDIT 2; |
Open up Yedit popup menu |
plt xleft EDIT 5; |
Exit data editing mode |
plt xleft Yedit 1; |
Open a window allowing editing the line properties of cursored trace.
(The command plt xright mark;) also does the same thing. |
plt xright Yedit 1; |
Open a window allowing editing the plt figure properties |
plt xleft Yedit 2; |
Toggle multiCursor mode |
plt xleft Yedit 3; |
Toggle xView slider |
plt xleft Yedit 4; |
Cancel data editing mode |
plt xleft Yedit 5; |
Enter data edit mode (Range) |
plt xleft Yedit 6; |
Enter data edit mode (Range left/right) |
plt xleft Yedit 7; |
Enter data edit mode (Range up/down) |
plt xleft Yedit 8; |
Enter data edit mode (Modify) |
plt xleft Yedit 9; |
Enter data edit mode (Modify left/right) |
plt xleft Yedit 10; |
Enter data edit mode (Modify up/down) |
plt xright Yedit 8; |
Enter persistent data edit mode (Modify) |
plt xright Yedit 9; |
Enter persistent data edit mode (Modify left/right) |
plt xright Yedit 10; |
Enter persistent data edit mode (Modify up/down) |
Mouse motion functions:
If you create a figure with a plt command that includes the parameter
'MotionZoom','funcname', then if you create a zoom box (see
The expansion box)
while you are adjusting the size of the zoom box the function
funcname([x1 x2 y1 y2]) will be continually called as the mouse is
moved (i.e. for as long as the mouse button is held down). The coordinate
[x1 y1] is the position of the lower left corner of the zoom box and [x2 y2]
is the coordinate of the upper right corner. It may require some imagination to
see how using such a parameter would enhance your user interface. The example
demo\gauss.m shows how to use the 'MotionZoom'
function. Although the use of the MotionZoom feature in this program is not
inspirational, at least when you create a zoom box inside the gauss figure you
will see the effect that the MotionZoom parameter creates. A more practical demonstration
of the use of this parameter can be seen in the pltmap.m example.
In place of the character string 'funcname' you may also use
@funcname or to insert extra parameters to the function, use
{@funcname param1 param2}. (The 4 element vector specifying
the zoombox corners will be the 3rd parameter of the function in this example.) These
alternate forms also apply to the other mouse motion functions
Including the parameter 'MotionZup','funcname' has a similar effect
except that the function 'funcname' only is called when the mouse button is released. The
MotionZoom and MotionZup functions are called when the zoom box moved or resized as well as when
it is first created.
You may also create, modify, or remove these mouse motion functions after the call to plt by
modifying the corresponding application data variable associated an axis.
For example these commands will set the mouse motion functions as expected:
setappdata(gca,'MotionZoom','funcA');
setappdata(gca,'MotionZup',@funcB);
Three additional mouse motion functions (MotionEdit, EditStart, EditStop) may also be defined
and are described in the
Data Editing section.
Creating a cursor pseudo object:
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 the plt pseudo object).
Ret1 = plt('cursor',axis,'init',In1,In2,In3,In4,In5,In6,In7,In8,In9);
where:
- Ret1: the cursor ID (cid) used to control the cursor with additional calls to plt.
- axis: 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 (right hand axis) is normally overlaid 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:
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 | line markers button |
10 | delta cursor button |
11 | x-axis cursor slider (optional) |
a 11 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 (no mixing units).
The last row specifies the position of the slider and is the only optional row.
If In1 contains only ten rows then the x-axis cursor slider will not be created.
The rows of In1 are assigned as described in this table.
- In2:
Row
| [r g b]
|
1 | x/y cursor label color
|
2 | cursor readout color [*1]
|
3 | expansion box color
|
4 | delta cursor color
|
5 | line #1 cursor color [*1]
|
6 | line #2 cursor color [*1]
|
... | ............................... [*1]
|
4+n (Must have a row for each line object that has a cursor)
| line #n cursor color [*1]
|
a 3 column array [red green blue] specifying the
colors for the cursors and cursor readout text.
The rows of In2 are defined as shown in this table.
[*1] Set to [0 0 0] to make the color of this element track its associated line color.
- 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 3 lines one could
use '+ox'
or to use the same symbol for all 3
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'}.
(Type "help prin" for a description of these format strings.)
- In7: Visible flag (first optional
argument). 'on' or
'off'.
- In8: (optional) Monotonic flag.
Set to 1 if the x data is monotonically
increasing, and 0 otherwise (such as with Nyquist plots).
- In9: (optional) Axis limit change callback function.
Executed when the axis limits are changed.
Notes: |
When the plt('cursor','init'
function is called, plt will attempt to add cursors to all lines of
the axis created by plt. If you want plt to skip adding cursors to some of
the lines, you should tag the line with the string
'SkipCur'. For example, a cursor would not be
created for a line created with the following command:
line(x,y,'tag','SkipCur'); |
|
Another way to restrict which lines are to be cursored is to add the application data key
'Lhandles' to the axis. (For example:
setappdata(ax,'Lhandles',[h1 h3]); would tell the
cursor initialization routine to add cursors only to those two handles.) |