usr/src/man/man3xcurses/keypad.3xcurses

   1 '\" te
   2 .\"  Copyright (c) 1990, 1995 by Mortice Kern Systems Inc.  All Rights Reserved  Portions Copyright (c) 1996, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH KEYPAD 3XCURSES "Jun 5, 2002"
   7 .SH NAME
   8 keypad \- enable/disable keypad handling
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-I\fR /usr/xpg4/include \fB -L \fR /usr/xpg4/lib \e
  13 \fB -R \fR /usr/xpg4/lib \fB -lcurses \fR [ \fIlibrary\fR... ]
  14
  15 \fBc89\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lcurses\fR [ \fIlibrary\fR... ]
  16
  17 #include <curses.h>
  18
  19 \fBint\fR \fBkeypad\fR(\fBWINDOW *\fR\fIwin\fR, \fBbool\fR \fIbf\fR);
  20 .fi
  21
  22 .SH PARAMETERS
  23 .sp
  24 .ne 2
  25 .na
  26 \fB\fIwin\fR\fR
  27 .ad
  28 .RS 7n
  29 Is a pointer to the window in which to enable/disable keypad handling.
  30 .RE
  31
  32 .sp
  33 .ne 2
  34 .na
  35 \fB\fIbf\fR\fR
  36 .ad
  37 .RS 7n
  38 Is a Boolean expression.
  39 .RE
  40
  41 .SH DESCRIPTION
  42 .sp
  43 .LP
  44 The \fBkeypad()\fR function controls keypad translation. If \fIbf\fR is
  45 \fBTRUE\fR, keypad translation is enabled. If \fIbf\fR is \fBFALSE\fR, keypad
  46 translation is disabled. The initial state is \fBFALSE\fR.
  47 .sp
  48 .LP
  49 This function affects the behavior of any function that provides keyboard
  50 input.
  51 .sp
  52 .LP
  53 If the terminal in use requires a command to enable it to transmit distinctive
  54 codes when a function key is pressed, then after keypad translation is first
  55 enabled, the implementation transmits this command to the terminal before an
  56 affected input function tries to read any characters from that terminal.
  57 .sp
  58 .LP
  59 The Curses input model provides the following ways to obtain input from the
  60 keyboard:
  61 .SS "Keypad processing"
  62 .sp
  63 .LP
  64 The application can enable or disable keypad translation by calling
  65 \fBkeypad()\fR. When translation is enabled, Curses attempts to translate a
  66 sequence of terminal input that represents the pressing of a function into a
  67 single key code. When translation is disabled, Curses passes terminal input to
  68 the application without such translation, and any interpretation of the input
  69 as representing the pressing of a keypad key must be done by the application.
  70 .sp
  71 .LP
  72 The complete set of key codes for keypad keys that Curses can process is
  73 specified by the constants defined in <\fBcurses.h\fR> whose names begin with
  74 "\fBKEY_\fR". Each terminal type described in the \fBterminfo\fR database may
  75 support some or all of these key codes. The \fBterminfo\fR database specifies
  76 the sequence of input characters from the terminal type that correspond to each
  77 key code.
  78 .sp
  79 .LP
  80 The Curses inplementation cannot translate keypad keys on terminals where
  81 pressing the keys does not transmit a unique sequence.
  82 .sp
  83 .LP
  84 When translation is enabled and a character that could be the beginning of a
  85 function key (such as escape) is received, Curses notes the time and begins
  86 accumulating characters. If Curses  receives additional characters that
  87 represent the processing of a keypad key within an unspecified interval from
  88 the time the character was received, then Curses converts this input to a key
  89 code for presentation to the application. If such characters are not received
  90 during this interval, translation of this input does not occur and the
  91 individual characters are presented to the application separately. (Because
  92 Curses waits for this interval to accumulate a key code, many terminals
  93 experience a delay between the time a user presses the escape key and the time
  94 the escape key is returned to the application.)
  95 .sp
  96 .LP
  97 In addition, No Timeout Mode provides that in any case where Curses has
  98 received part of a function key sequence, it waits indefinitely for the
  99 complete key sequence. The "unspecified interval" in the previous paragraph
 100 becomes infinite in No Timeout Mode. No Timeout Mode allows the use of function
 101 keys over slow communication lines. No Timeout Mode lets the user type the
 102 individual characters of a function key sequence, but also delays application
 103 response when the user types a character (not a function key) that begins a
 104 function key sequence. For this reason, in No Timeout Mode many terminals will
 105 appear to hang between the time a user presses the escape key and the time
 106 another key is pressed. No Timeout Mode is switchable by calling
 107 \fBnotimeout\fR(3XCURSES).
 108 .sp
 109 .LP
 110 If any special characters (<backspace>, <carriage return>, <newline>, <tab>)
 111 are defined or redefined to be characters that are members of a function key
 112 sequence, then Curses will be unable to recognize and translate those function
 113 keys.
 114 .sp
 115 .LP
 116 Several of the modes discussed below are described in terms of availability of
 117 input. If keypad translation is enabled, then input is not available once
 118 Curses has begun receiving a keypad sequence until the sequence is completely
 119 received or the interval has elapsed.
 120 .SS "Input Mode"
 121 .sp
 122 .LP
 123 The following four mutually-specific Curses modes let the application control
 124 the effect of flow-control characters, the interrupt character, the erase
 125 character, and the kill character:
 126 .sp
 127
 128 .sp
 129 .TS
 130 box;
 131 c c
 132 l l .
 133  Input Mode      Effect
 134 Cooked Mode     T{
 135  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 \fBISIG\fR and \fBIXON\fR flags are not changed upon entering this mode by calling \fBnocbreak\fR(3XCURSES), and are set upon entering this mode by calling \fBnoraw\fR(3XCURSES).Erase and kill characters are supported from any supported locale, no matter the width of the character.
 136 T}
 137 \fBcbreak\fR Mode       T{
 138 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 \fBcbreak\fR 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 \fBISIG\fR and \fBIXON\fR flags are not changed upon entering this mode.
 139 T}
 140 Half-Delay Mode T{
 141  The effect is the same as \fBcbreak\fR, 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 \fBISIG\fR and \fBIXON\fR flags are not changed upon entering this mode.
 142 T}
 143 Raw Mode        T{
 144 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 \fBISIG\fR and \fBIXON\fR flags are cleared upon entering this mode.
 145 T}
 146 .TE
 147
 148 .sp
 149 .LP
 150 The terminal interface settings are reported when the process calls
 151 \fBinitscr\fR(3XCURSES) or \fBnewterm\fR(3XCURSES) to initialize Curses and
 152 restores these settings when \fBendwin\fR(3XCURSES) is called. The initial
 153 input mode for Curses operations is especially unless Enhanced Curses
 154 compliance, in which the initial mode is \fBcbreak\fR mode, is supported.
 155 .sp
 156 .LP
 157 The behavior of the \fBBREAK\fR key depends on other bits in the display driver
 158 that are not set by Curses.
 159 .SS "Delay Mode"
 160 .sp
 161 .LP
 162 Two mutually-exclusive delay modes specify how quickly certain Curses functions
 163 return to the application when there is no terminal input waiting when the
 164 function is called:
 165 .sp
 166 .ne 2
 167 .na
 168 \fBNo Delay\fR
 169 .ad
 170 .RS 12n
 171 The function fails.
 172 .RE
 173
 174 .sp
 175 .ne 2
 176 .na
 177 \fBDelay\fR
 178 .ad
 179 .RS 12n
 180  The application waits until text is passed through to the application. If
 181 \fBcbreak\fR or Raw Mode is set, this is after one character. Otherwise, this
 182 is after the first <newline> character, end-of-line character, or end-of-file
 183 character.
 184 .RE
 185
 186 .sp
 187 .LP
 188 The effect of No Delay Mode on function key processing is unspecified.
 189 .SS "Echo processing"
 190 .sp
 191 .LP
 192 Echo mode determines whether Curses echoes typed characters to the screen. The
 193 effect of Echo mode is analogous to the effect of the \fBECHO\fR flag in the
 194 local mode field of the \fBtermios\fR structure associated with the terminal
 195 device connected to the window. However, Curses always clears the \fBECHO\fR
 196 flag when invoked, to inhibit the operating system from performing echoing. The
 197 method of echoing characters is not identical to the operating system's method
 198 of echoing characters, because Curses performs additional processing of
 199 terminal input.
 200 .sp
 201 .LP
 202 If in Echo mode, Curses performs 's's own echoing. Any visible input character
 203 is stored in the current or specified window by the input function that the
 204 application called, at that window's cursor position, as though
 205 \fBaddch\fR(3XCURSES) were called, with all consequent effects such as cursor
 206 movement and wrapping.
 207 .sp
 208 .LP
 209 If not in Echo mode, any echoing of input must be performed by the application.
 210 Applications often perform their own echoing in a controlled area of the
 211 screen, or do not echo at all, so they disable Echo mode.
 212 .sp
 213 .LP
 214 It may not be possible to turn off echo processing for synchronous and
 215 networked asynchronous terminals because echo processing is done directly by
 216 the terminals. Applications running on such terminals should be aware that any
 217 characters typed will appear on the screen at wherever the cursor is
 218 positioned.
 219 .SH RETURN VALUES
 220 .sp
 221 .LP
 222 Upon successful completion, the \fBkeypad()\fR function returns \fBOK\fR.
 223 Otherwise, it returns \fBERR\fR.
 224 .SH ERRORS
 225 .sp
 226 .LP
 227 No errors are defined.
 228 .SH ATTRIBUTES
 229 .sp
 230 .LP
 231 See \fBattributes\fR(5) for descriptions of the following attributes:
 232 .sp
 233
 234 .sp
 235 .TS
 236 box;
 237 c | c
 238 l | l .
 239 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 240 _
 241 Interface Stability     Standard
 242 _
 243 MT-Level        Unsafe
 244 .TE
 245
 246 .SH SEE ALSO
 247 .sp
 248 .LP
 249 \fBaddch\fR(3XCURSES), \fBendwin\fR(3XCURSES), \fBgetch\fR(3XCURSES),
 250 \fBinitscr\fR(3XCURSES), \fBlibcurses\fR(3XCURSES), \fBnewterm\fR(3XCURSES),
 251 \fBnocbreak\fR(3XCURSES), \fBnoraw\fR(3XCURSES), \fBattributes\fR(5),
 252 \fBstandards\fR(5)