KEYPAD(3XCURSES) X/Open Curses Library Functions KEYPAD(3XCURSES)


NAME


keypad - enable/disable keypad handling

SYNOPSIS


cc [ flag... ] file... -I /usr/xpg4/include -L /usr/xpg4/lib \
-R /usr/xpg4/lib -lcurses [ library... ]

c89 [ flag... ] file... -lcurses [ library... ]

#include <curses.h>

int keypad(WINDOW *win, bool bf);


PARAMETERS


win
Is a pointer to the window in which to enable/disable keypad
handling.


bf
Is a Boolean expression.


DESCRIPTION


The keypad() function controls keypad translation. If bf is TRUE, keypad
translation is enabled. If bf is FALSE, keypad translation is disabled.
The initial state is FALSE.


This function affects the behavior of any function that provides keyboard
input.


If the terminal in use requires a command to enable it to transmit
distinctive codes when a function key is pressed, then after keypad
translation is first enabled, the implementation transmits this command
to the terminal before an affected input function tries to read any
characters from that terminal.


The Curses input model provides the following ways to obtain input from
the keyboard:

Keypad processing


The application can enable or disable keypad translation by calling
keypad(). When translation is enabled, Curses attempts to translate a
sequence of terminal input that represents the pressing of a function
into a single key code. When translation is disabled, Curses passes
terminal input to the application without such translation, and any
interpretation of the input as representing the pressing of a keypad key
must be done by the application.


The complete set of key codes for keypad keys that Curses can process is
specified by the constants defined in <curses.h> whose names begin with
"KEY_". Each terminal type described in the terminfo database may support
some or all of these key codes. The terminfo database specifies the
sequence of input characters from the terminal type that correspond to
each key code.


The Curses inplementation cannot translate keypad keys on terminals where
pressing the keys does not transmit a unique sequence.


When translation is enabled and a character that could be the beginning
of a function key (such as escape) is received, Curses notes the time and
begins accumulating characters. If Curses receives additional characters
that represent the processing of a keypad key within an unspecified
interval from the time the character was received, then Curses converts
this input to a key code for presentation to the application. If such
characters are not received during this interval, translation of this
input does not occur and the individual characters are presented to the
application separately. (Because Curses waits for this interval to
accumulate a key code, many terminals experience a delay between the time
a user presses the escape key and the time the escape key is returned to
the application.)


In addition, No Timeout Mode provides that in any case where Curses has
received part of a function key sequence, it waits indefinitely for the
complete key sequence. The "unspecified interval" in the previous
paragraph becomes infinite in No Timeout Mode. No Timeout Mode allows the
use of function keys over slow communication lines. No Timeout Mode lets
the user type the individual characters of a function key sequence, but
also delays application response when the user types a character (not a
function key) that begins a function key sequence. For this reason, in No
Timeout Mode many terminals will appear to hang between the time a user
presses the escape key and the time another key is pressed. No Timeout
Mode is switchable by calling notimeout(3XCURSES).


If any special characters (<backspace>, <carriage return>, <newline>,
<tab>) are defined or redefined to be characters that are members of a
function key sequence, then Curses will be unable to recognize and
translate those function keys.


Several of the modes discussed below are described in terms of
availability of input. If keypad translation is enabled, then input is
not available once Curses has begun receiving a keypad sequence until the
sequence is completely received or the interval has elapsed.

Input Mode


The following four mutually-specific Curses modes let the application
control the effect of flow-control characters, the interrupt character,
the erase character, and the kill character:


+----------------------------------------------+
| Input Mode Effect |
|Cooked Mode This achieves normal |
| line-at-a-time processing |
| with all special characters |
| handled outside the |
| application. This achieves |
| the same effect as |
| canonical-mode input |
| processing. The state of |
| the ISIG and IXON flags are |
| not changed upon entering |
| this mode by calling |
| nocbreak(3XCURSES), and are |
| set upon entering this mode |
| by calling |
| noraw(3XCURSES).Erase and |
| kill characters are |
| supported from any |
| supported locale, no matter |
| the width of the character. |
|cbreak Mode Characters typed by the |
| user are immediately |
| available to the |
| application and Curses does |
| not perform special |
| processing on either the |
| erase character or the kill |
| character. An application |
| can set cbreak mode to do |
| its own line editing but to |
| let the abort character be |
| used to abort the task. |
| This mode achieves the same |
| effect as |
| non-canonical-mode, Case B |
| input processing (with MIN |
| set to 1 and ICRNL |
| cleared.) The state of the |
| ISIG and IXON flags are not |
| changed upon entering this |
| mode. |
|Half-Delay Mode The effect is the same as |
| cbreak, except that input |
| functions wait until a |
| character is available or |
| an interval defined by the |
| application elapses, |
| whichever comes first. This |
| mode achieves the same |
| effect as |
| non-canonical-mode, Case C |
| input processing (with TIME |
| set to the value specified |
| by the application.) The |
| state of the ISIG and IXON |
| flags are not changed upon |
| entering this mode. |
|Raw Mode Raw mode gives the |
| application maximum control |
| over terminal input. The |
| application sees each |
| character as it is typed. |
| This achieves the same |
| effect as non-canonical |
| mode, Case D input |
| processing. The ISIG and |
| IXON flags are cleared upon |
| entering this mode. |
+----------------------------------------------+


The terminal interface settings are reported when the process calls
initscr(3XCURSES) or newterm(3XCURSES) to initialize Curses and restores
these settings when endwin(3XCURSES) is called. The initial input mode
for Curses operations is especially unless Enhanced Curses compliance, in
which the initial mode is cbreak mode, is supported.


The behavior of the BREAK key depends on other bits in the display driver
that are not set by Curses.

Delay Mode


Two mutually-exclusive delay modes specify how quickly certain Curses
functions return to the application when there is no terminal input
waiting when the function is called:

No Delay
The function fails.


Delay
The application waits until text is passed through to the
application. If cbreak or Raw Mode is set, this is after one
character. Otherwise, this is after the first <newline>
character, end-of-line character, or end-of-file character.


The effect of No Delay Mode on function key processing is unspecified.

Echo processing


Echo mode determines whether Curses echoes typed characters to the
screen. The effect of Echo mode is analogous to the effect of the ECHO
flag in the local mode field of the termios structure associated with the
terminal device connected to the window. However, Curses always clears
the ECHO flag when invoked, to inhibit the operating system from
performing echoing. The method of echoing characters is not identical to
the operating system's method of echoing characters, because Curses
performs additional processing of terminal input.


If in Echo mode, Curses performs 's's own echoing. Any visible input
character is stored in the current or specified window by the input
function that the application called, at that window's cursor position,
as though addch(3XCURSES) were called, with all consequent effects such
as cursor movement and wrapping.


If not in Echo mode, any echoing of input must be performed by the
application. Applications often perform their own echoing in a
controlled area of the screen, or do not echo at all, so they disable
Echo mode.


It may not be possible to turn off echo processing for synchronous and
networked asynchronous terminals because echo processing is done directly
by the terminals. Applications running on such terminals should be aware
that any characters typed will appear on the screen at wherever the
cursor is positioned.

RETURN VALUES


Upon successful completion, the keypad() function returns OK. Otherwise,
it returns ERR.

ERRORS


No errors are defined.

ATTRIBUTES


See attributes(7) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Standard |
+--------------------+-----------------+
|MT-Level | Unsafe |
+--------------------+-----------------+

SEE ALSO


addch(3XCURSES), endwin(3XCURSES), getch(3XCURSES), initscr(3XCURSES),
libcurses(3XCURSES), newterm(3XCURSES), nocbreak(3XCURSES),
noraw(3XCURSES), attributes(7), standards(7)


illumos June 5, 2002 KEYPAD(3XCURSES)