Name:         GRCURS

Purpose:      read cursor position

Category:     GRAPHICS

File:         pgplot.src

Author:       T.J. Pearson

Use:          see description below.

Description:

            INTEGER FUNCTION GRCURS (IDENT,IX,IY,IXREF,IYREF,MODE,POSN,CH)
            INTEGER IDENT, IX, IY, IXREF, IYREF, MODE, POSN
            CHARACTER*(*) CH
      
       GRPCKG: Read the cursor position and a character typed by the user.
       The position is returned in absolute device coordinates (pixels).
       GRCURS positions the cursor at the position specified, and
       allows the user to move the cursor using the joystick or
       arrow keys or whatever is available on the device. When he has
       positioned the cursor, the user types a single character on his
       keyboard; GRCURS then returns this character and the new cursor
       position.
      
       "Rubber band" feedback of cursor movement can be requested (although
       it may not be supported on some devices). If MODE=1, a line from
       the anchor point to the current cursor position is displayed as
       the cursor is moved. If MODE=2, a rectangle with vertical and
       horizontal sides and one vertex at the anchor point and the opposite
       vertex at the current cursor position is displayed as the cursor is
       moved.
      
       Returns:
      
       GRCURS (integer): 1 if the call was successful; 0 if the device
            has no cursor or some other error occurs. 
      
       Arguments:
      
       IDENT (integer, input):  GRPCKG plot identifier (from GROPEN).
       IX    (integer, in/out): the device x-coordinate of the cursor.
       IY    (integer, in/out): the device y-coordinate of the cursor.
       IXREF (integer, input):  x-coordinate of anchor point.
       IYREF (integer, input):  y-coordinate of anchor point.
       MODE  (integer, input):  type of rubber-band feedback.
       CH    (char,    output): the character typed by the user; if the device
            has no cursor or if some other error occurs, the value CHAR(0)
            [ASCII NUL character] is returned.

Updates:      Oct 16, 1998: JPT automatically extracted from source.