GSEVWT(3g,L) AIX Technical Reference GSEVWT(3g,L)
-------------------------------------------------------------------------------
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
application.
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.
Processed November 7, 1990 GSEVWT(3g,L) 1
GSEVWT(3g,L) AIX Technical Reference GSEVWT(3g,L)
Warning: gsevwt uses the application buffer passed to it for temporary
storage. If the user has explicitly 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 application 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 character 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:
+-----------------------------------------------------------------------------+
| This figure cannot be displayed properly on the screen. |
| Please refer to the printed book. |
+-----------------------------------------------------------------------------+
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 terminates the sequence (ASCII a-z or A-Z).
Processed November 7, 1990 GSEVWT(3g,L) 2
GSEVWT(3g,L) AIX Technical Reference GSEVWT(3g,L)
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:
+-----------------------------------------------------------------------------+
| This figure cannot be displayed properly on the screen. |
| Please refer to the printed book. |
+-----------------------------------------------------------------------------+
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 absolute 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 corresponds to a button, the most significant bit
representing Button 1. A bit set to 1 indicates 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:
+-----------------------------------------------------------------------------+
| This figure cannot be displayed properly on the screen. |
| Please refer to the printed book. |
+-----------------------------------------------------------------------------+
Processed November 7, 1990 GSEVWT(3g,L) 3
GSEVWT(3g,L) AIX Technical Reference GSEVWT(3g,L)
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 0 through 31 of the LPFK pressed by the user.
The Timestamp (time since system startup) is in sixtieths of a
second. The data is structured as follows:
+-----------------------------------------------------------------------------+
| This figure cannot be displayed properly on the screen. |
| Please refer to the printed book. |
+-----------------------------------------------------------------------------+
5 Valuator
This event type occurs when the user turns a valuator dial.
The data consists of the valuator information. 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 counterclockwise rotation.
The Timestamp (time since system startup) is in sixtieths of a
second. The data is structured as follows:
+-----------------------------------------------------------------------------+
| This figure cannot be displayed properly on the screen. |
| Please refer to the printed book. |
+-----------------------------------------------------------------------------+
6 Key Code
This event type occurs when the virtual terminal is in
non-translated mode and a keyboard key is pressed, held down, or
released. The data is structured as follows:
+-----------------------------------------------------------------------------+
| This figure cannot be displayed properly on the screen. |
| Please refer to the printed book. |
+-----------------------------------------------------------------------------+
Key position codes are found under "keyboard."
7 Pick Event
This event type occurs while the pick operation is enabled and
graphics primitives are being sent to the adapter. The data is
structured as follows:
+-----------------------------------------------------------------------------+
Processed November 7, 1990 GSEVWT(3g,L) 4
GSEVWT(3g,L) AIX Technical Reference GSEVWT(3g,L)
| This figure cannot be displayed properly on the screen. |
| Please refer to the printed book. |
+-----------------------------------------------------------------------------+
A pick event code is generated when a structure traversal occurs.
The pick occurs when pixels intersect the pick window (defined by
the pick enable window size). The detection mode is always
immediate, 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 terminal 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 Invalid number of escape parameters.
GS_ICTL Invalid final character.
RELATED INFORMATION
In this book: "keyboard."
Processed November 7, 1990 GSEVWT(3g,L) 5