KPG1_PGCUR

Uses the cursor to get a set of points

Description:

This routine uses the PGPLOT cursor to get a set of positions in the world co-ordinate system of the current PGPLOT window. If a position is given outside the box specified by X1, X2, Y1, Y2, then a warning is issued and the position is ignored. The allowable box can extend outside the PGPLOT viewport (extrapolated world co-ordinates are returned for positions outside the viewport).

The routine returns when any one of the following occurs:

1) The maximum number of positions have been given (see MAXPNT). 2) The right mouse button, " X" or " ." is pressed (but only if KEYS contains " X" or " ." ). The cursor position is not returned. 3) The key/button specified by EXACT is pressed. The cursor position IS returned.

Invocation

CALL KPG1_PGCUR( INFO, MESS, NACT, ACTDES, KEYS, X1, X2, Y1, Y2, EXACT, X0, Y0, MAXPNT, RBMODE, LINE, BOX, MARK, IPLOT, X, Y, ACT, NPNT, STATUS )

Arguments

INFO = LOGICAL (Given)
Display information describing the available actions before getting the first position?
MESS = CHARACTER ∗ ( ∗ ) (Given)
The purpose for using the cursor. Eg " select 2 points" . May be blank.
NACT = INTEGER (Given)
The number of available actions. Ignored if INFO is .FALSE.
ACTDES( NACT ) = CHARACTER ∗ ( ∗ ) (Given)
Short descriptions of each action. Ignored if INFO is .FALSE. Examples: " select a point" , " exit" , " mark a star" . etc.
KEYS = CHARACTER ∗ ( ∗ ) (Given)
A string of NACT unique characters. These are the keyboard keys which must be pressed to select the corresponding action. Note, case is insignificant, but trailing spaces are significant. The left, middle and right mouse buttons are represented by the upper case characters A, D and X respectively (this is imposed by PGPLOT). A dot (" ." ) is considered equivalent to an X (i.e. the right mouse button). In addition, due to problems in the GKS version of PGPLOT, a space ("" ) is considered equivalent to an A (i.e. left mouse button).

The " X" and " ." keys (or equivalently the right mouse button) are special in that (if they are included in KEYS) they cause the routine to exit without adding the cursor position to the list of returned positions. If KEYS includes neither " X" nor " ." , then presses of " X" , " ." or the right mouse button are ignored.

X1 = REAL (Given)
World co-ord X at lower-left corner of region in which positons may be entered.
X2 = REAL (Given)
World co-ord X at upper-right corner of region in which positons may be entered. If X1 and X2 are equal then no restrictions are placed on the region in which positions may be given.
Y1 = REAL (Given)
World co-ord Y at lower-left corner of region in which positons may be entered.
Y2 = REAL (Given)
World co-ord Y at upper-right corner of region in which positons may be entered. If Y1 and Y2 are equal then no restrictions are placed on the region in which positions may be given.
EXACT = REAL (Given)
The index of an exit action. If the corresponding key/button press is made, then the cursor position is added to the list of returned positions and the routine then exits. Zero can be supplied if this facility is not required. Note, if KEYS contains " X" or " ." then the routine also exits (WITHOUT adding the cursor position to the returned list) if " X" , " ." or the right mouse button is pressed.
X0 = REAL (Given )
The X world co-ordinate of the initial cursor position. Ignored if VAL__BADR.
Y0 = REAL (Given )
The Y world co-ordinate of the initial cursor position. Ignored if VAL__BADR.
MAXPNT = INTEGER (Given)
The maximum number of positions which can be given by the user before exiting.
RBMODE = INTEGER (Given)
The form of the rubber band which connects the cursor to the previous position. Rubber bands are not available when using the GKS version of PGPLOT: 0 - do not use a rubber band. 1 - use a straight-line rubber band. 2 - use a horizontal box rubber band.
LINE = INTEGER (Given)
Specifies lines to be drawn as follows:

  • 1: Join adjacent points and do not close the polygon. 0: Do not draw any lines. 1: Join adjacent points and close the polygon. 2: Draw a vertical line between y1 and y2 (or the height of the window if y1=y2). 3: Draw a horizontal line between x1 and x2 (or the width of the window if x1=x2). The plotting attributes are specified by the CURVES(...) attributes of the supplied Plot (see IPLOT).

BOX = INTEGER (Given)
If non-zero then a horizontal box is drawn between each position. The plotting attributes are specified by the BORDER(...) attributes of the supplied Plot (see IPLOT).
MARK = INTEGER (Given)
If -31 or larger, then a marker is drawn at each position. The type of marker is given by the specific value (see PGPLOT routine PGPT). The plotting attributes are specified by the MARKERS(...) attributes of the supplied Plot (see IPLOT).
IPLOT = INTEGER (Given)
Defines the plotting styles for any graphics (see LINE, BOX and MARK). If AST__NULL is supplied, ther current PGPLOT attributes are used for all graphics.
X( MAXPNT ) = REAL (Returned)
Elements 1 to NPNT hold the selected X positions.
Y( MAXPNT ) = REAL (Returned)
Elements 1 to NPNT hold the selected X positions.
ACT( MAXPNT ) = INTEGER (Returned)
Elements 1 to NPNT hold the indices of the actions for each selected point. In range 1 to NACT.
NPNT = INTEGER (Returned)
The number of positions given by the user (this includes the position at which the action specified by EXACT was pressed - if it was. It does not include the position at which " X" , " ." or the right mouse button was pressed).
STATUS = INTEGER (Given and Returned)
The global status.