Tribblix: manual page: keypad.3xcurses

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

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