keypad(3xcurses)

1keypad(3XCURSES)        X/Open Curses Library Functions       keypad(3XCURSES)
2
3
4

NAME

6       keypad - enable/disable keypad handling
7

SYNOPSIS

9       cc [ flag... ] file... -I /usr/xpg4/include  -L  /usr/xpg4/lib \
10        -R  /usr/xpg4/lib  -lcurses  [ library... ]
11
12       c89 [ flag... ] file... -lcurses [ library... ]
13
14       #include <curses.h>
15
16       int keypad(WINDOW *win, bool bf);
17
18

PARAMETERS

20       win    Is  a  pointer  to  the window in which to enable/disable keypad
21              handling.
22
23
24       bf     Is a Boolean expression.
25
26

DESCRIPTION

28       The keypad() function controls keypad translation. If bf is TRUE,  key‐
29       pad  translation is enabled. If bf is FALSE, keypad translation is dis‐
30       abled. The initial state is FALSE.
31
32
33       This function affects the behavior of any function that  provides  key‐
34       board input.
35
36
37       If the terminal in use requires a command to enable it to transmit dis‐
38       tinctive codes when a function key is pressed, then after keypad trans‐
39       lation  is  first enabled, the implementation transmits this command to
40       the terminal before an affected input function tries to read any  char‐
41       acters from that terminal.
42
43
44       The Curses input model provides the following ways to obtain input from
45       the keyboard:
46
47   Keypad processing
48       The application can enable or disable  keypad  translation  by  calling
49       keypad().  When  translation is enabled, Curses attempts to translate a
50       sequence of terminal input that represents the pressing of  a  function
51       into  a  single  key  code. When translation is disabled, Curses passes
52       terminal input to the application without  such  translation,  and  any
53       interpretation  of  the  input as representing the pressing of a keypad
54       key must be done by the application.
55
56
57       The complete set of key codes for keypad keys that Curses  can  process
58       is  specified  by the constants defined in <curses.h> whose names begin
59       with "KEY_". Each terminal type described in the terminfo database  may
60       support some or all of these key codes. The terminfo database specifies
61       the sequence of input characters from the terminal type that correspond
62       to each key code.
63
64
65       The  Curses  inplementation  cannot  translate keypad keys on terminals
66       where pressing the keys does not transmit a unique sequence.
67
68
69       When translation is enabled and a character that could be the beginning
70       of  a  function key (such as escape) is received, Curses notes the time
71       and begins accumulating  characters.  If  Curses   receives  additional
72       characters  that  represent  the  processing  of a keypad key within an
73       unspecified interval from the time the  character  was  received,  then
74       Curses converts this input to a key code for presentation to the appli‐
75       cation. If such characters  are  not  received  during  this  interval,
76       translation  of this input does not occur and the individual characters
77       are presented to the application separately. (Because Curses waits  for
78       this  interval  to  accumulate  a key code, many terminals experience a
79       delay between the time a user presses the escape key and the  time  the
80       escape key is returned to the application.)
81
82
83       In addition, No Timeout Mode provides that in any case where Curses has
84       received part of a function key sequence, it waits indefinitely for the
85       complete key sequence. The "unspecified interval" in the previous para‐
86       graph becomes infinite in No Timeout Mode. No Timeout Mode  allows  the
87       use  of  function  keys  over slow communication lines. No Timeout Mode
88       lets the  user  type  the  individual  characters  of  a  function  key
89       sequence,  but  also  delays application response when the user types a
90       character (not a function key) that begins a function key sequence. For
91       this  reason,  in  No  Timeout  Mode many terminals will appear to hang
92       between the time a user presses the escape key and the time another key
93       is   pressed.   No  Timeout  Mode  is  switchable  by  calling  notime‐
94       out(3XCURSES).
95
96
97       If any special characters (<backspace>, <carriage  return>,  <newline>,
98       <tab>)  are defined or redefined to be characters that are members of a
99       function key sequence, then Curses will  be  unable  to  recognize  and
100       translate those function keys.
101
102
103       Several  of  the modes discussed below are described in terms of avail‐
104       ability of input. If keypad translation is enabled, then input  is  not
105       available  once  Curses has begun receiving a keypad sequence until the
106       sequence is completely received or the interval has elapsed.
107
108   Input Mode
109       The following four mutually-specific Curses modes let  the  application
110       control the effect of flow-control characters, the interrupt character,
111       the erase character, and the kill character:
112
113
114
115
116       ┌────────────────────────────────────────────────────────────┐
117       │   Input Mode                       Effect                  │
118       │Cooked Mode        This achieves normal line-at-a-time pro‐ │
119       │                  cessing  with all special characters han‐ │
120       │                  dled  outside   the   application.   This │
121       │                  achieves  the  same  effect as canonical- │
122       │                  mode input processing. The state  of  the │
123       │                  ISIG  and IXON flags are not changed upon │
124       │                  entering    this    mode    by    calling │
125       │                  nocbreak(3XCURSES),   and  are  set  upon │
126       │                  entering    this    mode    by    calling │
127       │                  noraw(3XCURSES).Erase and kill characters │
128       │                  are supported from any supported  locale, │
129       │                  no matter the width of the character.     │
130       │cbreak Mode       Characters  typed by the user are immedi‐ │
131       │                  ately available to  the  application  and │
132       │                  Curses  does not perform special process‐ │
133       │                  ing on either the erase character or  the │
134       │                  kill  character.  An  application can set │
135       │                  cbreak mode to do its  own  line  editing │
136       │                  but to let the abort character be used to │
137       │                  abort the task. This  mode  achieves  the │
138       │                  same effect as non-canonical-mode, Case B │
139       │                  input processing (with MIN set to  1  and │
140       │                  ICRNL cleared.) The state of the ISIG and │
141       │                  IXON flags are not changed upon  entering │
142       │                  this mode.                                │
143       │Half-Delay Mode    The effect is the same as cbreak, except │
144       │                  that input functions wait until a charac‐ │
145       │                  ter  is  available or an interval defined │
146       │                  by  the  application  elapses,  whichever │
147       │                  comes  first. This mode achieves the same │
148       │                  effect  as  non-canonical-mode,  Case   C │
149       │                  input  processing  (with  TIME set to the │
150       │                  value specified by the application.)  The │
151       │                  state  of the ISIG and IXON flags are not │
152       │                  changed upon entering this mode.          │
153       │Raw Mode          Raw mode gives  the  application  maximum │
154       │                  control over terminal input. The applica‐ │
155       │                  tion sees each character as it is  typed. │
156       │                  This  achieves  the  same  effect as non- │
157       │                  canonical mode, Case D input  processing. │
158       │                  The  ISIG and IXON flags are cleared upon │
159       │                  entering this mode.                       │
160       └────────────────────────────────────────────────────────────┘
161
162
163       The terminal interface settings are reported  when  the  process  calls
164       initscr(3XCURSES)   or   newterm(3XCURSES)  to  initialize  Curses  and
165       restores these settings when endwin(3XCURSES) is  called.  The  initial
166       input  mode  for Curses operations is especially unless Enhanced Curses
167       compliance, in which the initial mode is cbreak mode, is supported.
168
169
170       The behavior of the BREAK key depends on  other  bits  in  the  display
171       driver that are not set by Curses.
172
173   Delay Mode
174       Two  mutually-exclusive  delay modes specify how quickly certain Curses
175       functions return to the application when there  is  no  terminal  input
176       waiting when the function is called:
177
178       No Delay    The function fails.
179
180
181       Delay        The  application waits until text is passed through to the
182                   application. If cbreak or Raw Mode is set,  this  is  after
183                   one character. Otherwise, this is after the first <newline>
184                   character, end-of-line character, or end-of-file character.
185
186
187
188       The effect of No Delay Mode on function key processing is unspecified.
189
190   Echo processing
191       Echo mode determines whether Curses  echoes  typed  characters  to  the
192       screen.  The effect of Echo mode is analogous to the effect of the ECHO
193       flag in the local mode field of the termios structure  associated  with
194       the  terminal  device  connected  to the window. However, Curses always
195       clears the ECHO flag when invoked, to inhibit the operating system from
196       performing  echoing.  The method of echoing characters is not identical
197       to the operating system's method of echoing characters, because  Curses
198       performs additional processing of terminal input.
199
200
201       If  in  Echo  mode, Curses performs 's's own echoing. Any visible input
202       character is stored in the current or specified  window  by  the  input
203       function that the application called, at that window's cursor position,
204       as though addch(3XCURSES) were called, with all consequent effects such
205       as cursor movement and wrapping.
206
207
208       If  not  in  Echo  mode,  any echoing of input must be performed by the
209       application. Applications often perform their own  echoing  in  a  con‐
210       trolled area of the screen, or do not echo at all, so they disable Echo
211       mode.
212
213
214       It may not be possible to turn off echo processing for synchronous  and
215       networked  asynchronous  terminals  because  echo  processing  is  done
216       directly by the  terminals.  Applications  running  on  such  terminals
217       should  be aware that any characters typed will appear on the screen at
218       wherever the cursor is positioned.
219

RETURN VALUES

221       Upon successful completion, the keypad() function  returns  OK.  Other‐
222       wise, it returns ERR.
223

ERRORS

225       No errors are defined.
226

ATTRIBUTES

228       See attributes(5) for descriptions of the following attributes:
229
230
231
232
233       ┌─────────────────────────────┬─────────────────────────────┐
234       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
235       ├─────────────────────────────┼─────────────────────────────┤
236       │Interface Stability          │Standard                     │
237       ├─────────────────────────────┼─────────────────────────────┤
238       │MT-Level                     │Unsafe                       │
239       └─────────────────────────────┴─────────────────────────────┘
240