SGS provides two ways in which a program can interact with the person running it:
The most familiar form of interaction is where the cursor is displayed and the program waits for the user to move it to the desired position and press one of the choice keys. The cursor position (a position in world coordinates) and the choice selected (a positive integer) are then returned to the program.
This type of interaction is achieved by:
If this routine is called repeatedly the cursor will reappear at the position that it was left at by the previous call. The cursor’s position can be explicitly set by:
provided that the hardware allows the position of the cursor to be controlled by the computer. Not all devices have cursors, e.g. pen plotters, and so a program can find out if the workstation of the current SGS zone has a cursor (all SGS input routines operate on the currently selected SGS zone) with:
where AVAIL is set to the logical value .TRUE. or .FALSE.. The cursor can also be used in a mode (sample mode) in which the cursor can be moved around by the user but the position is read by the program without waiting for the use to press a choice key. This mode of operation has to be explicitly enabled with:
but may not be available on all devices or at all in some GKS implementations (at present this includes the RAL implementation used by Starlink) and if it is not an error message will be generated; the cursor position can then be sampled with:
typically in a loop. Sample mode is disabled with:
It is sometimes desirable to use this mode without the cursor being visible, its position being indicated in some other way, such as continuously drawing a line to the cursor position from its position when last sampled. In order to allow this, the cursor can be made invisible by:
and made visible again with:
The cursor will, of course, only actually appear if sample mode is enabled or when SGS_REQCU is called.
The choice device, which can be invoked either in conjunction with the cursor or on its own, can be one of two devices. By default it is a choice device associated with the graphics workstation such as the buttons on a mouse or the numeric keys on a graphics terminal and is characterised by having a small number of choices. SGS provides an alternative device which is the keyboard of the terminal from which the program is being run. This has the advantage of being always available and of having a much larger number of choices. However, since it is potentially a different device from the graphics device, two separate read operations are required to get the choice and the cursor information, and on a very busy system or over a network these operations may be separated by an appreciable length of time.
The choice device you wish to use is selected by:
where NCHDEV is 1 or greater for the normal GKS choice devices and 0 for the command terminal keyboard. The number of choices on a choice device can be inquired with:
If the choice device does not exist, N will be returned as zero.
For the terminal keyboard (choice device 0) only, the mapping of the keyboard keys onto the integers returned by SGS_REQCH is controlled by:
where CHOSTR is a character string specifying which keys are to be considered to be valid choices. If the key specified by the first character in the string is pressed an integer 1 will be returned, if the second a 2 will be returned, and so on. If the key is not included in the string a zero will be returned. There is no restriction on which characters can be specified but upper and lower case characters are not distinguished and you are advised only to use the FORTRAN character set (A-Z 0-9 =+-*’/(),.:$ and blank) as other characters cannot be guaranteed to be present on a terminal. For this reason, if the number of choices on device 0 is inquired 49 is returned.
A typical use of this facility might be a program which plots a star field and then asks the user to identify each object on the plot as either a star a galaxy or a plate defect by positioning the cursor on each object in turn and pressing the S G or D keys to indicate the nature of the object or the ‘.’ key to terminate the sequence. The interactive part of this program might be:
It is a Starlink recommendation that you use the “.” character to terminate a sequence of operations such as this.