1keypad(3XCURSES) X/Open Curses Library Functions keypad(3XCURSES)
2
3
4
6 keypad - enable/disable keypad handling
7
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
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
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
221 Upon successful completion, the keypad() function returns OK. Other‐
222 wise, it returns ERR.
223
225 No errors are defined.
226
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
242 addch(3XCURSES), endwin(3XCURSES), getch(3XCURSES), initscr(3XCURSES),
243 libcurses(3XCURSES), newterm(3XCURSES), nocbreak(3XCURSES),
244 noraw(3XCURSES), attributes(5), standards(5)
245
246
247
248SunOS 5.11 5 Jun 2002 keypad(3XCURSES)