KbdStringIn: Difference between revisions
m Ak120 moved page OS2 API:CPI:KbdStringIn to KbdStringIn |
m fix |
||
(2 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
Gets a string of keyboard input. | Gets a string of keyboard input. | ||
==Syntax== | ==Syntax== | ||
KbdStringIn(pch, pchin, Flag, hkbd) | |||
==Parameters== | ==Parameters== | ||
; pch (PCH) - output : | ;pch (PCH) - output: Pointer to the character string buffer. | ||
; pchin (PSTRINGINBUF) - in/out : Pointer to buffer-length data. | ;pchin (PSTRINGINBUF) - in/out : Pointer to buffer-length data. | ||
A pointer to the STRINGINBUF structure containing buffer-length data. | A pointer to the STRINGINBUF structure containing buffer-length data. | ||
; Flag (ULONG) - input : Wait flag. | ;Flag (ULONG) - input : Wait flag. | ||
* 0 IO_WAIT Wait for a keystroke if one is not available. The keystroke returned is removed from the queue. | *0 IO_WAIT Wait for a keystroke if one is not available. The keystroke returned is removed from the queue. | ||
* 1 IO_NOWAIT Return immediately, with or without a keystroke. If a keystroke is returned, remove it from the queue. | *1 IO_NOWAIT Return immediately, with or without a keystroke. If a keystroke is returned, remove it from the queue. | ||
* 2 IO_PEEK Return immediately, with or without a keystroke. Do not remove the keystroke from the queue. | *2 IO_PEEK Return immediately, with or without a keystroke. Do not remove the keystroke from the queue. | ||
* 3 IO_PEEKWAIT Wait for a keystroke if one is not available. Return the keystroke but do not remove it from the queue. | *3 IO_PEEKWAIT Wait for a keystroke if one is not available. Return the keystroke but do not remove it from the queue. | ||
; hkbd (HKBD) - input : Reserved. Must be 0. | ;hkbd ([[HKBD]]) - input : Reserved. Must be 0. | ||
==Return Code== | ==Return Code== | ||
;rc ([[APIRET]]) - returns:KbdStringIn returns one of the following values: | |||
KbdStringIn returns one of the following values: | |||
* 0 NO_ERROR | * 0 NO_ERROR | ||
* 373 ERROR_KBD_PARAMETER | * 373 ERROR_KBD_PARAMETER | ||
Line 39: | Line 26: | ||
==Remarks== | ==Remarks== | ||
This function is retained only for compatibility. New code should not use it. KbdGetConsole is the preferred function for new code. | This function is retained only for compatibility. New code should not use it. [[KbdGetConsole]] is the preferred function for new code. | ||
The contents and ending condition depend on the keyboard state: | The contents and ending condition depend on the keyboard state: | ||
;ASCII: Only valid characters are placed in the input buffer. The function ends when a turnaround character is found or when the buffer is full. The turnaround character is not placed in the buffer. | |||
;ASCII : Only valid characters are placed in the input buffer. The function ends when a turnaround character is found or when the buffer is full. The turnaround character is not placed in the buffer. | ;BINARY: Both valid characters and extended keys are returned. The extended keys are returned as two-byte strings with a leading 0x00 or 0xe0 character. The function ends when the buffer is full. | ||
;BINARY : Both valid characters and extended keys are returned. The extended keys are returned as two-byte strings with a leading 0x00 or 0xe0 character. The function ends when the buffer is full. | ;TERM: Valid characters and escape sequences are placed in the input buffer. The function ends when the turnaround character is found, when an escape sequence is complete, or when the buffer is full. The turnaround character is placed in the buffer. | ||
;TERM : Valid characters and escape sequences are placed in the input buffer. The function ends when the turnaround character is found, when an escape sequence is complete, or when the buffer is full. The turnaround character is placed in the buffer. | |||
The maximum buffer length is 255 bytes. | The maximum buffer length is 255 bytes. | ||
The character strings can be optionally echoed on the display if echo mode is set. When echo is on, each character is echoed as it is read from the keyboard. Echo mode and binary mode are mutually exclusive. See KbdGetStatus and KbdSetStatus for more information. | The character strings can be optionally echoed on the display if echo mode is set. When echo is on, each character is echoed as it is read from the keyboard. Echo mode and binary mode are mutually exclusive. See [[KbdGetStatus]] and [[KbdSetStatus]] for more information. | ||
The default input mode is ASCII. In ASCII mode, 2-byte character codes only return in complete form. An extended ASCII code is returned in a 2-byte string. The first byte is 0DH or E0H and the next byte is an extended code. | The default input mode is ASCII. In ASCII mode, 2-byte character codes only return in complete form. An extended ASCII code is returned in a 2-byte string. The first byte is 0DH or E0H and the next byte is an extended code. | ||
In input mode (binary or ASCII), the following returns can be set and retrieved with KbdGetStatus and KbdSetStatus: | In input mode (binary or ASCII), the following returns can be set and retrieved with KbdGetStatus and KbdSetStatus: | ||
* Turnaround Character | * Turnaround Character | ||
* Echo Mode | * Echo Mode | ||
* Interim Character Flag | * Interim Character Flag | ||
* Shift State | * Shift State | ||
The received input length is also used by the KbdStringIn line edit functions for re-displaying and entering a caller-specified string. On the next KbdStringIn call the received input length indicates the length of the input buffer that can be recalled by the user using the line-editing keys. A value of 0 inhibits the line-editing function for the current KbdStringIn request. | The received input length is also used by the KbdStringIn line edit functions for re-displaying and entering a caller-specified string. On the next KbdStringIn call the received input length indicates the length of the input buffer that can be recalled by the user using the line-editing keys. A value of 0 inhibits the line-editing function for the current KbdStringIn request. | ||
[[Category:Kbd]] | [[Category:Kbd]] |
Latest revision as of 16:23, 3 January 2019
Gets a string of keyboard input.
Syntax
KbdStringIn(pch, pchin, Flag, hkbd)
Parameters
- pch (PCH) - output
- Pointer to the character string buffer.
- pchin (PSTRINGINBUF) - in/out
- Pointer to buffer-length data.
A pointer to the STRINGINBUF structure containing buffer-length data.
- Flag (ULONG) - input
- Wait flag.
- 0 IO_WAIT Wait for a keystroke if one is not available. The keystroke returned is removed from the queue.
- 1 IO_NOWAIT Return immediately, with or without a keystroke. If a keystroke is returned, remove it from the queue.
- 2 IO_PEEK Return immediately, with or without a keystroke. Do not remove the keystroke from the queue.
- 3 IO_PEEKWAIT Wait for a keystroke if one is not available. Return the keystroke but do not remove it from the queue.
- hkbd (HKBD) - input
- Reserved. Must be 0.
Return Code
- rc (APIRET) - returns
- KbdStringIn returns one of the following values:
- 0 NO_ERROR
- 373 ERROR_KBD_PARAMETER
- 375 ERROR_KBD_INVALID_IOWAIT
- 376 ERROR_KBD_INVALID_LENGTH
- 439 ERROR_KBD_INVALID_HANDLE
- 445 ERROR_KBD_FOCUS_REQUIRED
- 504 ERROR_KBD_EXTENDED_SG
Remarks
This function is retained only for compatibility. New code should not use it. KbdGetConsole is the preferred function for new code.
The contents and ending condition depend on the keyboard state:
- ASCII
- Only valid characters are placed in the input buffer. The function ends when a turnaround character is found or when the buffer is full. The turnaround character is not placed in the buffer.
- BINARY
- Both valid characters and extended keys are returned. The extended keys are returned as two-byte strings with a leading 0x00 or 0xe0 character. The function ends when the buffer is full.
- TERM
- Valid characters and escape sequences are placed in the input buffer. The function ends when the turnaround character is found, when an escape sequence is complete, or when the buffer is full. The turnaround character is placed in the buffer.
The maximum buffer length is 255 bytes.
The character strings can be optionally echoed on the display if echo mode is set. When echo is on, each character is echoed as it is read from the keyboard. Echo mode and binary mode are mutually exclusive. See KbdGetStatus and KbdSetStatus for more information.
The default input mode is ASCII. In ASCII mode, 2-byte character codes only return in complete form. An extended ASCII code is returned in a 2-byte string. The first byte is 0DH or E0H and the next byte is an extended code.
In input mode (binary or ASCII), the following returns can be set and retrieved with KbdGetStatus and KbdSetStatus:
- Turnaround Character
- Echo Mode
- Interim Character Flag
- Shift State
The received input length is also used by the KbdStringIn line edit functions for re-displaying and entering a caller-specified string. On the next KbdStringIn call the received input length indicates the length of the input buffer that can be recalled by the user using the line-editing keys. A value of 0 inhibits the line-editing function for the current KbdStringIn request.