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