idlastro / Math and Statistics: RDPLOT

[Source code]

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