% @(#)get_gcur.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:43:38 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      get_gcur.hlq
%.AUTHOR     RHW, IPG/ESO
%.KEYWORDS   MIDAS, help files, GET/GCURSOR
%.PURPOSE    On-line help file for the command: GET/GCURSOR
%.VERSION    1.0  13-JAN-1990 : Creation, RHW
%----------------------------------------------------------------
\se
SECTION./GCUR
\es\co
GET/GCURSOR					                 13-JAN-1990 RHW
\oc\su
GET/GCURSOR [output_spec] [app_flag] [max]
	read and store cursor coordinates from the graphics display
\us\pu
Purpose:      
              Read and store cursor coordinates from the graphics display.
\up\sub
Subject:      
              Position, graphics.
\bus\sy
Syntax:       
              GET/GCURSOR [output_spec] [app_flag] [max]
\ys\pa
              output_spec	 = output specification to receive coordinates and/or 
                           data values. The output can be stored in a table or 
                           a descriptor. To store the output in a table the 
                           specification should be `table_name,TABLE'; if the 
                           output is to be stored in a descriptor the 
                           specification should be `descr_name,DESCR'. The 
                           latter is only possible if the data plotted 
                           originate from a frame or a table.
\ap\pa
              app_flag =   'A' indicates that data values will be appended
                           to the table or descriptor used as output; default
                           the descriptor or table is created or overwritten.
\ap\pa
              max =        optional limit to the number of coordinate pairs
                           read; default = 99999
\ap\out
Output:       Table or descriptor containing positional information.
\tuo\no
Note:        
              The command can be used after each main plot and overplot command
              (to display descriptor, keyword, table or image data, or to plot 
              a set of axes). By default, cursor values are only displayed on 
              the terminal.
\\
              IMPORTANT: The position(s) retrieved by the cursor refer to the
              last plotted data. Hence, after a plot and subsequent overplot
              command(s) the coordinates refer to the data plotted with the 
              last overplot command.
\\
              The command enables the graphic cursor and reads the screen
              coordinates. If the graphics cursor is used on table, keyword, 
              or descriptor data, the screen (world) coordinates are read and 
              stored in the output table in the columns X_AXIS and Y_AXIS.
              In case of image data the command converts the screen coordinates
              to pixel and world coordinates of the nearest image pixel.
              These numbers are stored in the columns labelled X_AXIS, Y_AXIS, 
              LINE_NO, PIXEL_NO, X_COORD, Y_COORD. The pixel intensity is 
              stored in the column VALUE.
\\
              For XWindows use the mouse to move the cursor, the leftmost
              mouse button or the RETURN key is the ENTER button, the
              second left mouse button serves as EXIT button.  The cursor cross
              may not be visible at first. Move the mouse to the lower left 
              corner of the graphics window to grab the cursor.
\\
              For graphic terminals pressing any key of the graphics keyboard
              will give the coordinates of the cursor(s) position; the space
              bar is used to exit from the cursor mode.
\on\see
See also:     
              SET/GRAPHICS, SHOW/GRAPHICS, SET/GCURSOR
\ees\exs
Examples:
\ex
              GET/GCURS
              display cursor data on terminal only
\xe\ex
              GET/GCURS COORDS,DES
              as before but store world coords. and intensity into real 
              descriptor `COORDS' of the frame or table for which the data
              was plotted
\xe\ex
              GET/GCURS coords A
              as above but append the table `coords' with these data
\xe \sxe