%N pgband %F $MIR/src/pgband.f
%D Read cursor position, with anchor
%B
      INTEGER FUNCTION PGBAND (MODE, POSN, XREF, YREF, X, Y, CH)
      INTEGER MODE, POSN
      REAL XREF, YREF, X, Y
      CHARACTER*(*) CH

 Read the cursor position and a character typed by the user.
 The position is returned in world coordinates.  PGBAND positions
 the cursor at the position specified (if POSN=1), allows the user to
 move the cursor using the mouse or arrow keys or whatever is available
 on the device. When he has positioned the cursor, the user types a
 single character on the keyboard; PGBAND then returns this
 character and the new cursor position (in world coordinates).

 Some interactive devices offer a selection of cursor types,
 implemented as thin lines that move with the cursor, but without
 erasing underlying graphics. Of these types, some extend between
 a stationary anchor-point at XREF,YREF, and the position of the
 cursor, while others simply follow the cursor without changing shape
 or size. The cursor type is specified with one of the following MODE
 values. Cursor types that are not supported by a given device, are
 treated as MODE=0.

 -- If MODE=0, the anchor point is ignored and the routine behaves
 like PGCURS.
 -- If MODE=1, a straight line is drawn joining the anchor point 
 and the cursor position.
 -- If MODE=2, a hollow rectangle is extended as the cursor is moved,
 with one vertex at the anchor point and the opposite vertex at the
 current cursor position; the edges of the rectangle are horizontal
 and vertical.
 -- If MODE=3, two horizontal lines are extended across the width of
 the display, one drawn through the anchor point and the other
 through the moving cursor position. This could be used to select
 a Y-axis range when one end of the range is known.
 -- If MODE=4, two vertical lines are extended over the height of
 the display, one drawn through the anchor point and the other
 through the moving cursor position. This could be used to select an
 X-axis range when one end of the range is known.
 -- If MODE=5, a horizontal line is extended through the cursor
 position over the width of the display. This could be used to select
 an X-axis value such as the start of an X-axis range. The anchor point
 is ignored.
 -- If MODE=6, a vertical line is extended through the cursor
 position over the height of the display. This could be used to select
 a Y-axis value such as the start of a Y-axis range. The anchor point
 is ignored.
 -- If MODE=7, a cross-hair, centered on the cursor, is extended over
 the width and height of the display. The anchor point is ignored.

 Returns:
  PGBAND          : 1 if the call was successful; 0 if the device
                    has no cursor or some other error occurs.
 Arguments:
  MODE   (input)  : display mode (0, 1, ..7: see above).
  POSN   (input)  : if POSN=1, PGBAND attempts to place the cursor
                    at point (X,Y); if POSN=0, it leaves the cursor
                    at its current position. (On some devices this
                    request may be ignored.)
  XREF   (input)  : the world x-coordinate of the anchor point.
  YREF   (input)  : the world y-coordinate of the anchor point.
  X      (in/out) : the world x-coordinate of the cursor.
  Y      (in/out) : the world y-coordinate of the cursor.
  CH     (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.

 Note: The cursor coordinates (X,Y) may be changed by PGBAND even if
 the device has no cursor or if the user does not move the cursor.
 Under these circumstances, the position returned in (X,Y) is that of
 the pixel nearest to the requested position.
