RDPLOT

   Like CURSOR but with a full-screen cursor and continuous readout option

   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,
   or CHANGE keywords are not set, then the leftmost mouse button will
   print a "newline" line-feed, but not exit.

   RDPLOT, [X, Y, WaitFlag], [/DATA, /DEVICE, /NORMAL,
      /NOWAIT, /WAIT, /DOWN, /CHANGE, ERR=,
      PRINT=, XTITLE=, YTITLE=, XVALUES=, YVALUES=,
      /FULLCURSOR, /NOCLIP, LINESTYLE=, THICK=, COLOR=, /CROSS]

   None.

   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

    X - a named variable to receive the final cursor X position, scalar
    Y - a named variable to receive the final cursor Y position, scalar

   /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, mouse
      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 = analagous 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.
   CROSS = if non-zero will show the regular cross AND full screen cursors.

   ERR = returns the most recent value of the !mouse.button value.

   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

   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.
   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.

   Basically is a bells-n-whistles version of the CURSOR procedure.  All
   the details are covered in the above discussion of the keywords.
 EXAMPLE (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

   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

[Home Page] [Software, Documentation] [IDL Documentation] [Quick Reference] [Feedback]