%N grcurs %F $MIR/src/grcurs.f
%D Read cursor position
%B
      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.
