illumos: 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