Name:         PGBAND

Purpose:      read cursor position, with anchor

Category:     GRAPHICS

File:         pgplot.src

Author:       T.J. Pearson

Use:          see description below.

Description:

            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.

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