gsevwt
Purpose
Waits for an input event.
C Syntax
int gsevwt_ (wait, data)
int *wait, data[13|;
FORTRAN Syntax
INTEGER function gsevwt (wait, data)
INTEGER wait, data (13)
Pascal Syntax
FUNCTION gsevwt_ (
VAR wait: INTEGER;
VAR data: ARRAY [0..12| of INTEGER
): INTEGER [PUBLIC|;
Description
The gsevwt subroutine returns the relevant information
for the oldest input event in the ring buffer.
The function works as follows:
o If an event is in the ring, then gsevwt parses the
oldest event in the ring. It returns the event type
and its data in the buffer provided by the applica-
tion.
o If no event is in the ring and the application
requested no wait, gsevwt returns immediately. If the
application requested a wait, the process execution
is suspended until an enabled input event occurs;
then gsevwt returns the event type and its data in
the buffer provided.
Warning: gsevwt uses the application buffer passed
to it for temporary storage. If the user has explic-
itly keyed part of an ANSI control sequence when the
application calls gsevwt with no wait request, then
gsevwt finds a partial event in the ring and leaves
part of the parsed data for the event in the applica-
tion buffer; however, gsevwt returns a timeout event
class. Unless the application returns the same
unmodified buffer, or a different buffer containing
identical information, the results of the next call
to gsevwt will be incorrect.
A valid input ring must be defined during the GSL
initialization.
Parameters
wait Determines whether or not to wait for an event.
If wait is 0, then gsevwt does not wait for an
event if no event is available.
data Specifies the location where GSL is to store
the input data (up to 13 words). The data must
be word aligned:
The possible events are:
1 Keystroke(s)
This event type occurs when the user types a
single graphic character or a single-byte
control character. For these two events,
gsevwt returns a null-terminated byte string
representing the graphic or control char-
acter that was typed. This event may also
occur if the user has explicitly keyed an
ANSI escape sequence; gsevwt returns two
bytes, the ESC and the next character in the
sequence.
The data consists of a null-terminated ASCII
string and is structured as follows:
ol807212
2 Control sequence
This event type indicates an ANSI control
sequence, which is of the form:
ESC [ p ; p ; . . . p f
where ESC is the ASCII escape character, p
represents a parameter (one or more ASCII
digits), the ellipsis represents additional
parameters separated by semicolons, and f
represents the final character that termi-
nates the sequence (ASCII a-z or A-Z).
The ANSI control sequence occurs when the
user presses a program function key on the
keyboard or if the user enters an explicit
control sequence.
The data consists of the parsed control
sequence information. The Final Character is
the valid or invalid final character. The
Count indicates the number of parameters in
the control sequence, with a maximum count
of 10. These fields are followed by the
Parameters. The data is structured as
follows:
ol807213
3 Locator
This event indicates the user has moved the
locator or pressed a button on the locator.
The data consists of locator position and
status information. The X value and the Y
value field contain a relative movement
(delta x, delta y) for a mouse and an abso-
lute position (x, y) for a tablet. The
Timestamp, which is elapsed time since
system startup (IPL), is in sixtieths of a
second.
The Buttons field contains the locator
button status. For a mouse, each bit corre-
sponds to a button, the most significant bit
representing Button 1. A bit set to 1 indi-
cates that the corresponding button is
pressed. For a tablet, the most significant
five bits represent the button pressed,
according to the following scheme:
Status Button
0 None pressed
1 Cursor upper left, stylus tip
2 Cursor upper right
3 Cursor lower left
4 Cursor lower right
For a tablet, the sixth most significant bit
of the Buttons field indicates that the
sensor is on (bit set) or off (bit not set).
The Type field contains a 0 if the locator
is a mouse and a 1 if the locator is a
tablet. The data is structured as follows:
ol807214
4 LPFK
This event type occurs when the user presses
a key on the LPFK.
The data consists of the LPFK information.
The LPFK field contains the decimal number
of the LPFK pressed by the user, that is, 0
through 31. The Timestamp (time since
system startup) is in sixtieths of a second.
The data is structured as follows:
ol807215
5 valuator
This event type occurs when the user turns a
valuator dial.
The data consists of the valuator informa-
tion. The Valuator field contains the
decimal number, 0 through 7, of the valuator
turned by the user. The Valuator Delta
field contains the difference between the
current valuator value and the last valuator
value. The delta for a full turn is 256 for
the IBM Valuator. The delta is positive for
clockwise rotation and negative for counter-
clockwise rotation. The Timestamp (time
since system startup) is in sixtieths of a
second. The data is structured as follows:
ol807216
6 key code
This event type occurs when the virtual ter-
minal is in non-translated mode and a key-
board key is pressed, held down, or
released. The data is structured as
follows:
ol807223
Key position codes are found under "key-
board." Status bits are found under
"Input."
7 pick event
This event type occurs while the pick opera-
tion is enabled and graphics primitives are
being sent to the adapter. The data is
structured as follows:
ol807224
A pick event code is generated when a struc-
ture traversal occurs. The pick occurs when
pixels are determined to intersect the pick
window (defined by the pick enable window
size). The detection mode is always imme-
diate, so that an event is generated as soon
as an event occurs.
The pick event type is provided only for use
with the IBM 5081 Display Adapter, and not
for use with other displays.
10 Timeout
No data is returned.
It is important to note that gsevwt does not detect ANSI
escape sequences. However, with the default virtual ter-
minal keyboard mapping, it is not possible to generate an
escape sequence by pressing a single key. Because gsevwt
does parse ANSI control sequences, the routine cannot
consider the press of the escape key an event, so the
routine waits for the next character to decide if the
escape implies the start of a control sequence. Only if
the next character is not the left bracket does gsevwt
return the escape and the next character.
If the return code indicates overflow, the most recent
input events from enabled devices are lost.
Return Value
GS_SUCC Successful.
GS_ROVR Ring buffer overflow.
GS_UDRG Ring undefined.
GS_PARM Too many control sequence parameters.
GS_ICTL Invalid final character.
Related Information
In this book: "keyboard" and "Input."