Chapter 5 and Chapter 6 have introduced graphical input in GKS. When an application program requires input data from an operator, it asks a logical input device to obtain it and, using the operating mode, controls the style by which the operator interacts with that logical input device. A particular logical input device can supply to the program values corresponding to one of the six types of input data available in GKS.
This chapter defines an interaction in GKS more precisely and shows how a logical input device can be controlled by sending it an initial value and control parameters which are used when an interaction starts. The other main topic is further control of the input queue.
Implicit in Chapters 5 and 6 has been the interaction. An interaction involves an operator and a logical input device. While the interaction is underway, the operator controls the current value (or measure) held by the logical input device. It is this measure that is returned to the application program by GKS. While no interaction with a logical input device is underway, the operator has no control over the measure and the program has no way of finding out its value. In effect it does not exist. For example, an operator can move the pen of a tablet across the tablet surface at any time. But if no interaction is underway, the movements of the pen have no effect on the measure and, hence, also have no effect on the application program. If the application program has specified that echoing is to occur, the echo only appears when an interaction starts and disappears when it stops.
In REQUEST mode, a single call to a GKS REQUEST function contains an entire interaction. Otherwise no interaction with that device is underway. In SAMPLE and EVENT modes, an interaction is underway the whole time. It starts when either mode is selected by a GKS function of the form SET XXX MODE and finishes when the same GKS function is next called with the same device specified by its parameters (note that another interaction may start with the next call).
The following (slightly artificial) example demonstrates which GKS functions start and stop an interaction:
SET VALUATOR MODE(WS, DV, SAMPLE, EC) Interaction starts
SAMPLE VALUATOR(WS, DV, VALUE)
SET VALUATOR MODE(WS, DV, REQUEST, EC) Interaction stops
REQUEST VALUATOR(WS, DV, STAT, VALUE) Entire interaction
SET VALUATOR MODE(WS, DV, EVENT, EC) Interaction starts
AWAIT EVENT(T, W, C, D)
GET VALUATOR(VALUE)
SET VALUATOR MODE(WS, DV, EVENT, EC) Interaction stops and
new one starts
SET VALUATOR MODE(WS, DV, REQUEST, EC) Interaction stops
A logical input device may be initialised by calling the appropriate INITIALISE XXX function, where XXX is the class of the device, which is of the form:
INITIALISE XXX(WS, DV, initial value, PE,
XMN, XMX, YMN, YMX, ..., LDR, DR)
The first two parameters give the workstation identifier and device number. Next follows one or more parameters defining the initial value for that type of device. PE defines the prompt and echo types which will be described in Section 9.3.2. The four parameters XMN, XMX, YMN, YMX define the echo area described in Section 9.3.3. Finally, DR(1) to DR(LDR) is an input data record described in Section 9.3.4.
During an interaction, the measure of a logical input device is controlled by the operator. However, we have not described how the measure is initialised.
In GKS, an initial value associated with the device, initialises the measure when the interaction starts. Therefore, unless the initial value is altered by the application program, the measure is the same at the start of each interaction. For example, if REQUEST LOCATOR is being used and echoing is selected, the echo appears initially in the same place on each call to REQUEST LOCATOR.
For the operator, this method gives the advantage of predictability. However, the initial value may be so unsuitable that the interaction becomes stilted and inefficient. The initial value can be altered by the appropriate GKS function INITIALISE XXX given above. XXX denotes one of the six classes of input data. WS and DV are the workstation identifier and the device number, which together with the data type XXX identify the logical input device whose initial value is to be set. The format of the new initial value depends on the data type XXX and in each case corresponds to the format which would be delivered by the GKS input functions. The remaining parameters have nothing to do with the initial value itself and will be described later.
Two of the GKS INITIALISE functions are:
INITIALISE VALUATOR(WS, DV, VALUE, PE, XMN, XMX, YMN, YMX,
LOVAL, HIVAL, LDR, DR)
INITIALISE LOCATOR(WS, DV, N, X, Y, PE, XMN, XMX, YMN, YMX,
LDR, DR)
A good use of INITIALISE is to ensure that the input resulting from one interaction is used as the initial value for the next. For example:
100 CONTINUE
REQUEST LOCATOR(WS, DV, ST, N, X, Y)
DRAW DUCK AT(X, Y)
INITIALISE LOCATOR(WS, DV, N, X, Y, PE, XMN, XMX, YMN, YMX, LDR, DR)
GOTO 100
Supposing that echoing has been selected, the operator sees an echo appear in a particular position, manipulates a physical device to control the measure and, hence, the echo, terminates the interaction, and then the duck moves to the chosen position. On the next call to REQUEST LOCATOR, the echo appears in the position last input by the operator, who can now engage in another interaction. If the chosen positions are likely to be close together, this extra call by the program can considerably assist the operator.
In general it is a good idea to use an INITIALISE function if the program can make a reasonable prediction of the next input value. For example, an operator's response to a REQUEST CHOICE may cause a particular initial value to be suitable for the next interaction. In the following example, suitable initial locator values are stored in the arrays NT, XP and YP:
REQUEST CHOICE(WS, DV1, STAT, N)
IF(STAT .NE. OK) STOP
INITIALISE LOCATOR(WS, DV2, NT(N), XP(N), YP(N), PE,
XMN, XMX, YMN, YMX, LDR, DR)
Note that the initial value used by the program must be legal at the time that the INITIALISE function is called. It must be a value that the operator is able to input. In particular, when setting the initial value of a locator device, the specified point must lie within the window of the specified transformation and for a pick device the specified segment name must exist and be detectable and visible. For example, the following sequence of GKS calls is illegal even though clipping is disabled:
SET WINDOW(1, 0, 60, 0, 60)
SET CLIPPING INDICATOR(NOCLIP)
INITIALISE LOCATOR(WS, DV, 1, 70, 70, PE, XMN, XMX, YMN, YMX,
LDR, DR) ILLEGAL!!
It is possible for an initial value to be valid when set up by an INITIALISE function, but to become invalid later when, for example, a normalization transformation changes. In this situation, an interaction starts with a fall-back initial value determined by the implementation of the logical input device. For example:
SET WINDOW(1, 0, 60, 0, 60)
INITIALISE LOCATOR(WS, DV, 1, 50, 50, PE, XMN, XMX, YMN, YMX,
LDR, DR)
SET WINDOW(I1, 0, 40, 0, 40)
REQUEST LOCATOR(WS, DV, ST, NT, X, Y)
The call to REQUEST LOCATOR causes the fall-back initial value to be used since the specified initial point is now outside the window of the specified normalization transformation, It is also important to note that some devices may be unable to use the initial value properly. For example, on some input hardware, the crosshairs cannot be initialised at all. GKS accepts input from such a device, but the operator sees the initial echo of a value determined by the hardware and not by the application program.
So far echoing has been mentioned as desirable because from it the operator can deduce the current measure: the value that would pass to the program if it were to be delivered now. However, the form of the echo has only been hinted at.
A simple logical input device might only have one method of echoing. Another might have several and each of these may have advantages in different situations. For example, a crosshair cursor usually extends to the edges of a display surface and allows horizontal and vertical alignments to be perceived by the operator. A locator echoed by one corner of a rectangle allows an operator to perceive what lies inside and what lies outside. It seems sensible to permit the application program to select the most appropriate method. In GKS, this selection can be made using the prompt and echo type in the INITIALISE function. This is the PE parameter which appeared in all the references to INITIALISE in the last section.
On any logical input device, the PE parameter can take the value 1. For example:
INITIALISE VALUATOR(WS, DV, VL, 1, XMN, XMX, YMN, YMX,
LOVAL, HIVAL, LOR, DR)
The form of the echo corresponding to the value 1 is device dependent and is the usual echo for the device. Values of PE other than 1 might be available on some devices but not on others. Some values of PE are defined in GKS and have a particular meaning. The meanings of these are described later. The ISO Registration Authority will assign standard meanings to positive values beyond the range defined by GKS. There will be a different set of registered prompt and echoes for each input class. Negative values are device dependent.
The use of prompt and echo types that are not in the standard set makes a program less portable than if a program confines itself to prompt and echo type 1, but does take advantage of special echoes available on some devices. The program tuned for a particular special echo can be made more adaptable if it inquires what prompt and echo types are available on a logical input device. The GKS function for this purpose is the appropriate INQUIRE DEFAULT XXX DEVICE DATA where XXX is one of the six input classes.
The prompt and echo types that are standardized in GKS are grouped by input class.
On a particular installation, one locator device might only be able to display a tracking cross. Since prompt and echo type 1 must be available and is the usual type, it would be implemented as a tracking cross on this device and so would prompt and echo type 3. A locator device with a variety of echoes including crosshair and adjustable rectangle might make available prompt and echo types 1, 2 and 4. Initialising these devices might look like:
INITIALISE LOCATOR(WS1, DV1, NT, X, Y, 1, XMN, XMX, YMN, YMX, LOR, OR)
INITIALISE LOCATOR(WS2, DV2, NT, X, Y, 4, XMN, XMX, YMN, YMX, LOR, OR)
For some prompt and echo types, both the prompt and the echo can be anywhere on that part of the display surface currently in use (for example, most of the locator prompt and echo types) or is not displayed at all (for example, choice prompt and echo type 2 which puts the lights on). For many prompt and echo types however, the prompt and echo is displayed in a particular place and does not move from there, even though it may change shape. The program can control where such a display goes, by altering the echo area, which is a rectangle with sides parallel to the X and Y axes. In each INITIALISE function:
INITIALISE XXX(WS, DV, initial value, PE, XMN, XMX, YMN, YMX, ..., LDR, DR)
XMN and XMX are the left and right bounds of the echo area and YMN and YMX are the bottom and top bounds. The coordinates are in device coordinates.
For example, a locator value may be echoed by using digits in the top right corner of a 500×500 display surface or a valuator may be echoed using a dial in the top left:
INITIALISE LOCATOR(WS, DV1, N, X, Y, 6, 450, 500, 450, 500, LOR, DR)
INITIALISE VALUATOR(WS, DV2, VAL, 2, 0, 40, 450, 500, L, H, LOR, DR)
Since the coordinates are in device coordinates, the echo area can be separate from the area used by GKS output if this is wanted. In the following example, a choice device has an echo area containing a menu. The echo area is distinct from the workstation viewport:
SET WORKSTATION VIEWPORT(WS, 100, 500, 0, 500)
INITIALISE CHOICE(WS, DV, OK, 1, 3, 0, 99, 0, 500, LDR, DR)
Some logical input devices allow further control over the way they interact with the operator. For example, several sizes of tracking cross might be allowed. Other devices may vary the method by which the value delivered to the program is calculated. For example, if a pick device is emulated by a physical device which only returns an (X,Y) coordinate (a tablet perhaps), the closeness with which the point has to approach a segment before a hit is registered might be a settable parameter.
These quantities are not defined in GKS. However the input data record provides a method by which quantities like these and also some compulsory quantities are sent to the logical input device. This is the final pair of parameters of the INITIALISE function. In FORTRAN, it is a CHARACTER*80 array (DR), preceded by the size of the array (LOR). For example:
INITIALISE VALUATOR(WS, DV, VAL, 1, XMN, XMX, YMN, YMX, LOVAL, HIVAL, LDR, DR)
The format and contents of the input data record are allowed by the standard to vary from one device to another. In FORTRAN, the array may include integers, reals and characters. Somehow this information has to be passed via the single array DR and to do this a special FORTRAN routine is available. It is not a GKS function, but is available with any FORTRAN implementation of GKS in order to construct data records. It is:
PACK DATA RECORD(NIA, IA, NRA, RA, NS, LSA, SA, MDR, ERRIND, NOR, DR)
In this routine, DR is the CHARACTER*80 array into which the data record is put by PACK DATA RECORD. MDR is the size of DR and NOR is the number of entries in DR actually occupied by the data record after being packed. ERRIND indicates whether an error has occurred in the packing. IA, RA and SA contain data (integers, reals, and character strings) to be packed in the data record and, for integers and reals, the preceding parameter is the number of entries to be packed. For character strings, there is a parameter containing the number of them (NS), the number of significant characters in each one (array LSA) and the array of strings themselves (SA). Other uses exist for data records and these will be described in Chapter 12. A routine performing the opposite task, UNPACK DATA RECORD, is also available.
For example, LOCATOR might require 10 integers and 2 real numbers to define its action. This would be achieved as follows:
PACK DATA RECORD(10, IA, 2, RA, 0, LSA, SA, 100, ERRIND, NOR, DR)
For some input classes, certain entries in the data record have specific meanings. These cases are noted in the following list:
In a FORTRAN implementation, the quantities which are always present, are separate parameters which precede the CHARACTER *80 array and its size. Thus INITIALISE VALUATOR contains parameters to set the lowest and highest values. For example, the program may require valuator input to be in the range 4.2 to 8.7:
PACK DATA RECORD(0, IAR, 0, RA, 0, LS, S, I, ERRIND, NOR, DR)
INITIALISE VALUATOR(WS, DV, VAL, 1, XMN, XMX, YMN, YMX, 4.2, 8.7, NOR, DR)
If a prompt and echo type is set for choice input, the input device requires a menu of character strings. Suppose that the menu is to appear on the left side of the screen. Then we might use:
DATA LS/4, 3, 4, 5, 4/
DATA S/'MOVE', 'NEW', 'FILL', 'SCALE', 'QUIT'/
PACK DATA RECORD(0, IA, 0, RA, 5, LS, S, 10, ERRIND, LOR, DR)
INITIALISE CHOICE(WS, DV, OK, CH, 3, 0, 50, 0, 400, LOR, DR)
This would make a menu on the left consisting of the five words MOVE, NEW, FILL, SCALE, QUIT.
Other entries in the input data records may vary from one device to another even within the same input class. A variety of quantities is possible. For example, for locator input there might be an entry in the data record controlling the size of the tracking cross or an entry which sends pixels defining the shape of a tracking cross. For valuator, an entry might control the valuator resolution or a linear/logarithmic switch. Increasing the former gives the effect of a valuator which has distinct steps. For stroke, an entry might control the time interval, between separate successive points of the stroke input.
Some of the parameters of the INITIALISE function are device dependent; prompt and echo type is chosen from a device dependent list of possibilities, echo area is in device coordinates and the input data record is in a non-standard form. By contrast the meaning of initial value is workstation independent.
A program, which is to be transported easily, might only use the initial value and ensure that the others are unchanged. It is necessary to use an inquiry function to find the values which are to be unchanged, for example:
INQUIRE VALUATOR DEVICE STATE(WS, DV, MXDR, ERRIND, OPMODE,
EC, INITV AL, PE, EA, LOVAL, HIVAL, LDR, DR)
INITIALISE VALUATOR(WS, DV, NEWINITVALUE, PE,
EA(1), EA(2), EA(3), EA(4), LOVAL, HIVAL, LDR, DR)
Event reports are added to the input queue by logical input devices operating in EVENT mode and removed independently by the application program. This section deals with the possibility of more than one event entering the queue as a result of a single operator action and also the detection and handling of input queue overflow.
When an operator presses a button to trigger an event for a locator input device, it is possible that any of several buttons could have been chosen. In some situations, it is desirable that the program should find out which button was pressed, so extracting the maximum information about the operator's action. Whether this is possible in a particular implementation of GKS depends on how the logical input devices are associated with the physical devices.
Suppose that on a workstation, there is a tablet T capable of generating (X,Y) coordinates and that with it there is a group of buttons B1, B2, B3 and B4 possibly on a puck associated with the tablet. It is possible in GKS for more than one logical input device to be associated with the buttons B1 to B4. In fact the less sophisticated the input hardware, the more likely this is to happen, in order to provide the full six logical input devices.
The following example shows two logical input devices sharing the same group of buttons:
If any of the four buttons are pressed in EVENT mode, two event reports enter the input queue: one from each logical input device. In GKS, these are referred to as simultaneous events. The two events enter the input queue consecutively, but in no particular order.
The application program reads the events one at a time using the GET XXX and AWAIT EVENT functions described in Section 6.6. If it is necessary to discover which events originated from the same operator action, the function:
INQUIRE MORE SIMULTANEOUS EVENTS(ERRIND, ANYMORE)
would be used. The parameter ANYMORE contains the required information. If the input queue still contains any events simultaneous with an event already removed, ANYMORE contains the value MORE, otherwise it contains NOMORE.
The following example illustrates how this inquiry function might be used. The program requires locator input values NT, X, Y and a choice value NCH, which are passed to the application subroutine USE INPUT DATA. Part of the example consists of a loop which collects the input data and ensures that input values are obtained from both logical input devices. It also ensures that simultaneous events are not separated.
SET LOCATOR MODE(WS, DVL, EVENT, ECHO)
SET CHOICE MODE (WS, DVC, EVENT, ECHO)
100 LOC=.FALSE.
CHO=.FALSE.
200 CONTINUE
AWAIT EVENT(600, QWS, CLASS, QDV)
IF(CLASS .EQ. NONE) GOTO 300
IF(CLASS .EQ. LOCATOR) GET LOCATOR(NT, X, Y)
IF(CLASS .EQ. LOCATOR) LOC=.TRUE.
IF(CLASS .EQ. CHOICE) GET CHOICE(ST, NCH)
IF(CLASS .EQ. CHOICE) CHO= .TRUE.
IF(.NOT. (CHO .AND. LOC)) GOTO 200
INQUIRE MORE SIMULTANEOUS EVENTS(ERRIND, ANYMORE)
IF(ANYMORE .EQ. MORE) GOTO 200
USE INPUT DATA(NT, X, Y, ST, NCH)
GOTO 100
300 CONTINUE
Note that, if in an implementation the two logical input devices are not associated in this way, the program still works. The operator would have to trigger two events: one for each device, but in either order. The program would ensure that an event from each logical input device arrived before using the input data. If any repeat occurred, any old value would be thrown away.
With a logical input device in EVENT mode, it may happen that the operator adds events to the queue faster than the application program removes them. Since the input queue is likely to be of limited size, it can easily overflow in this situation. A consequence of the queue overflowing is that some input data is lost. This section shows how it is possible to find out that loss of input data has occurred.
When the input queue overflows, no more event reports are added until the application program empties the queue in a particular way. The operator would normally perceive that the input actions were no longer being acknowledged.
A GKS error (number 147) is reported, when the program next attempts to remove an event from the queue. The program can trap the error by replacing the ERROR HANDLING procedure as described in Section 8.5.
Alternatively the program can use an inquiry function:
INQUIRE INPUT QUEUE OVERFLOW(ERRIND, EWS, ECLASS, EDV)
to detect input queue overflow. If the error indicator ERRIND is returned as 0, the queue has overflowed. If ERRIND is 148, the queue has not overflowed. The inquiry would normally be called immediately after a call to AWAIT EVENT. If overflow has occurred, the other parameters indicate which logical input device was attempting to add the event report that caused the overflow.
Event reports remaining on the queue are valid and repeated calls to AWAIT EVENT remove them and allow them to be examined by the appropriate GET XXX function. However, only when the application program calls AWAIT EVENT with the queue empty (i.e. when the device class parameter is returned with the value NONE), can further event reports be added by the operator. It is at this stage that the application program can assume that the loss of input data occurred.
In the following example, events are taken off the queue and dealt with. This is the loop that starts at statement 100. In the loop, the condition of input queue overflow is tested and, if it has occurred, control passes to statement 200. There the device that caused the overflow is put into REQUEST mode which stops further events being generated.
Remaining events in the queue are passed to the application subroutine USE INPUT DATA as if the overflow had not occurred. However when the queue has been emptied, the program jumps to statement 400 to deal with the situation of lost data.
SET LOCATOR MODE(WS, DVL, EVENT, ECHO)
SET CHOICE MODE(WS, DVC, EVENT, ECHO)
100 AWAIT EVENT(600, WST, CLASS, DEV)
IF (CLASS .EQ. NONE) GOTO 500
INQUIRE INPUT QUEUE OVERFLOW(ERRIND, EWS, ECLASS, EDV)
IF(ERRIND .EQ. 0) GOTO 200
USE INPUT DATA(WST, CLASS, DEV)
GOTO 100
200 CONTINUE
IF(ECLASS .EQ. CHOICE) SET CHOICE MODE(EWS, EDV, REQUEST, ECHO)
IF(ECLASS .EQ. LOCATOR) SET LOCATOR MODE(EWS, EDV, REQUEST, ECHO)
300 AWAIT EVENT(0, WST, CLASS, DEV)
IF(CLASS .EQ. NONE) GOTO 400
USE INPUT DATA(WST, CLASS, DEV)
GOTO 300
400 CONTINUE
500 CONTINUE
At the statement 400, the queue has been emptied and the program has reached the point where data has been lost.