- 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.
Mac users may need to set their X windows preferences to (1) Emulate 3
button mouse and (2) Click through inactive windows, to make cursor
work properly.
- 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=, CURSOR_STANDARD=]
- 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.
CURSOR_STANDARD = this keyword can be used to select the cursor
appearance if /CROSS is set and will set the cursor to this value
when the full-screen cursor is turned off if /FULLCURSOR has been
set. See IDL help for the DEVICE keyword CURSOR_STANDARD to see
possible cursors for X Windows and MS Windows. The default
behavior, if this keyword is not set, is to set the cursor to the
window system's default cursor, which might not be the user's
preferred cursor.
- 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.
Note: this might have been the case back in the day, but Robishaw
hasn't experienced any problems with CURSOR, /UP in the last 10
years. Even so, it would be somewhat tricky to implement the /UP
behavior in this routine, which explains why it's still missing.
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.
- 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
Fixed misbehavior when /FULLCURSOR not set; was checking for
non-existent variable VisualName. T. Robishaw 2007 Jul 01
Added the CURSOR_STANDARD keyword because I hate how this routine
changes my default cursor. Also, it was crashing when /FULL not set:
small fix, now works. T. Robishaw 2007 Jul 03
Fixed bug where moving mouse with button pressed or releasing button
would return values even if DOWN was set. The checks for this were
only being done if PRINT was set also. T.V. Wenger 2013 May 14
Fix problem exiting when X,Y not supplied W. Landsman June 2013