RDPLOT
Name
RDPLOT
Purpose
Like CURSOR but with a full-screen cursor and continuous readout option
Explanation
This program is designed to essentially mimic the IDL CURSOR command,
but with the additional options of continuously printing out the data
values of the cursor's position, and using a full-screen cursor rather
than a small cross cursor. The full screen cursor uses OPLOT and
X-windows graphics masking to emulate the cursor.
One difference is that IF the PRINT keyword is set but the DOWN,
WAIT, CHANGE, or NOWAIT keywords are not set, then the leftmost mouse
button will print a "newline" line-feed, but not exit.
Calling Sequence
RDPLOT [, X, Y] [, WaitFlag] [, /DATA | /DEVICE | /NORMAL]
[, /NOWAIT | /WAIT | /DOWN | /CHANGE]
[, /FULLCURSOR] [, /NOCLIP] [, /CROSS] [, /ACCUMULATE]
[, ERR=, PRINT=, XTITLE=, YTITLE=, XVALUES=, YVALUES=
, LINESTYLE=, THICK=, COLOR=, BACKGROUND=]
Required Inputs
None.
Optional Inputs
WAITFLAG = Uses the same table as the intrinsic CURSOR command, But note
that unlike the CURSOR command, there is no UP keyword.
WaitFlag=0 sets the NOWAIT keyword
WaitFlag=1 sets the WAIT keyword {default}
WaitFlag=2 sets the CHANGE keyword
WaitFlag=3 sets the DOWN keyword
Optional Outputs
X - a named variable to receive the final cursor X position, scalar
or vector (if /ACCUMULATE is set)
Y - a named variable to receive the final cursor Y position, scalar
or vector (if /ACCUMULATE is set)
Optional Keyword Input Parameters
/DATA - data coordinates are displayed and returned.
/DEVICE - device coordinates are displayed and returned.
/NORMAL - normal coordinates are displayed and returned.
Default is to use DATA coordinates if available (see notes).
/NOWAIT = if non-zero the routine will immediately return the cursor's
present position.
/WAIT - if non-zero will wait for a mouse key click before returning. If
cursor key is already down, then procedure immediately exits.
/DOWN - equivalent to WAIT *except* that if the mouse key is already down
when the procedure is called, the procedure will wait until the mouse
key is clicked down again.
/CHANGE - returns when the mouse is moved OR a key is clicked up or down.
PRINT = if non-zero will continuously print out (at the terminal) the data
values of the cursor's position. If PRINT>1, program will printout a
brief header describing the mouse button functions. However, note that
the button functions are overridden if any of the DOWN, WAIT, or
CHANGE values are non-zero.
XTITLE = label used to describe the values of the abscissa if PRINT>0.
YTITLE = label used to describe the values of the ordinate if PRINT>0.
XVALUES = a vector corresponding to the values to be printed when the
PRINT keyword is set. This allows the user the option of printing
out other values rather than the default X coordinate position of
the cursor. E.g., if XVALUES is a string vector of dates such as
['May 1', 'May 2', ...], then those dates will be printed rather than
the X value of the cursor's position: if X=1 then 'May 2' would be
printed, etc. This requires that the values of the X coordinate read
by the cursor must be positive (can't access negative elements).
If XVALUES=-1, then NO values for X will be printed.
YVALUES = analogous to the XVALUES keyword.
/FULLCURSOR - if non-zero default cursor is blanked out and full-screen
(or full plot window, depending on the value of NOCLIP) lines are
drawn; their intersecton is centered on the cursor position.
/NOCLIP - if non-zero will make a full-screen cursor, otherwise it will
default to the value in !P.NOCLIP.
LINESTYLE = style of line that makes the full-screen cursor.
THICK = thickness of the line that makes the full-screen cursor.
COLOR = color of the full-screen cursor.
BACKGROUND = color of the background of the plot device. If this has
been set to !P.BackGround, then this keyword is unnecessary.
CROSS = if non-zero will show the regular cross AND full screen cursors.
/ACCUMULATE - all of the positions for which the left button was
clicked are stored in the X and Y variables. Has no effect if X and Y
are not present.
OPTIONAL KEYWORD OUTPUT PARAMETER:
ERR = returns the most recent value of the !mouse.button value.
Notes
Note that this procedure does not allow the "UP" keyword/flag...which
doesn't seem to work too well in the origianl CURSOR version anyway.
If a data coordinate system has not been established, then RDPLOT will
create one identical to the device coordinate system. Note that this
kluge is required even if the user specified /NORMAL coordinates, since
RDPLOT makes use of the OPLOT procedure. This new data coordinate system
is effectively "erased" (!X.CRange and !Y.CRange are both set to zero)
upon exit of the routine so as to not change the plot status from the
user's point of view.
Only tested on X-windows systems. If this program is interrupted, the
graphics function might be left in a non-standard state; in that case,
run the program RESET_RDPLOT to return the standard graphics functions,
or type the command: DEVICE, /CURSOR_CROSS, SET_GRAPHICS=3, BYPASS=0
Robishaw added /ACCUMULATE keyword to pass back all the positions at
which the mouse was left-clicked. In addition, the value of the exit
click is returned unless the cursor did not change position between the
last left-click and the exit click.
Bugs
NOTE: (1/27/05) The bugs below have been fixed by Robishaw and tested
on Solaris, Linux and OS-X.
It is assumed that the current background of the plot is correctly
defined by the value in !P.Background. Otherwise, the color of the
long cursor probably will not be correct. Sometimes the color doesn't
work anyway, and I'm not sure why.
NOTE: Robishaw fixed this 1/27/05.
There may be some cases (e.g., when THICK>1 and NOCLIP=0) when the
full-screen cursor is not correctly erased, leaving "ghost images" on the
plot. It just seems that the screen updates get slow or the positions
ambiguous with a thick line and the cursor off the plot.
NOTE: Robishaw fixed this 1/27/05.
Procedure
Basically is a bells-n-whistles version of the CURSOR procedure. All
the details are covered in the above discussion of the keywords.
Examples
A silly, but informative one:
Months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', $
'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
plot, indgen(12), xrange=[-5, 15]
rdplot, /FULL, /PRINT, XTITLE='Month: ', YTITLE='Y-value per month = ', $
xvalues=Months
If your plot has a non-black background color, be sure to set either
!p.background or the BACKGROUND keyword. Here are examples of how to
use a blue full-screen cursor on a plot with a red background and
yellow axes and data. First, deal with color decomposition off:
device, decomposed=0
tvlct, [255,255,0], [0,255,0], [0,0,255], 1
plot, randomn(seed,1024), XSTYLE=19, PSYM=3, COLOR=2, BACK=1
rdplot, /PRINT, /FULL, THICK=5, /NOCLIP, BACK=1, COLOR=3
For decomposition on (TrueColor or DirectColor only):
device, decomposed=1
plot, randomn(seed,1024), XSTYLE=19, PSYM=3, COLOR=65535l, BACK=255l
rdplot, /PRINT, /FULL, THICK=5, /NOCLIP, BACK=255l, COLOR=16711680l
Modification History
Written (originally named CURFULL) by J.Wm.Parker 1993 Nov 22
Created data coordinates if not already present, W. Landsman Nov. 93
Added continuous printout of data values, COLOR and FULLCURSOR keywords
(so that default is that it acts just like the cursor command).
Changed name from CURFULL to RDPLOT. J.Wm.Parker 1994 Apr 20
Modified (with some translation table assistance from the IDL support
group) to correctly plot the crosshair with the desired IDL
color using the device's translation table to determine the XOR
function and using the BYPASS function. Added the RESET_RDPLOT
procedure to cleanup crashes that might occur while running
RDPLOT. Other minor changes/bug fixes. J.Wm.Parker 1994 May 21
Modified DOWN, WAIT, CHANGE functions to behave more similar to the
generic CURSOR procedure. J.Wm.Parker 1995 April 24
Added XVALUES, YVALUES keywords and cleanup. J.Wm.Parker 1995 April 24
Convert to IDL V5.0, W. Landsman July 1998
Change !D.NCOLORS to !D.TABLE_SIZE for 24 bit displays W. Landsman May 2000
Skip translation table for TrueColor visuals W. Landsman March 2001
Fixed /FULLCURSOR ghosts. Fixed to properly deal with background colors
in 24-bit visual classes (TrueColor and DirectColor). Added
BACKGROUND keyword. Tim Robishaw 2005 Jan 27
Added /ACCUMULATE keyword. T. Robishaw 2006 Nov 8
Corrected following problems. When /CHANGE and /PRINT were set,
returned X & Y were different than those printed. When /PRINT and
/NOWAIT were set, or /PRINT and /WAIT were set and the routine was
entered with a mouse button clicked, nothing was printed. When
/PRINT and /DOWN were set, if routine was started with button down,
advertised behavior was that routine would exit on next down click;
in practice if cursor was not moved, successive down clicks had no
effect. Now, if X is passed as an output variable, requires that Y
is also passed, like CURSOR. Bottom line is that RDPLOT now really
does behave like CURSOR and when /PRINT is set, the values printed
correspond to those returned in X & Y. T. Robishaw 2006 Nov 12
Fixed misbehavior when color decomposition was set to off for
TrueColor and DirectColor. Now thoroughly tested on PseudoColor
displays as well as both decomposition states for TrueColor and
DirectColor. Also made the default cursor color white when
decomposition is on (this has been its default value for
decomposition off). T. Robishaw 2006 Nov 16