man/XChangeKeyboardMapping.man

   1 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
   2 .\"
   3 .\" Permission is hereby granted, free of charge, to any person obtaining
   4 .\" a copy of this software and associated documentation files (the
   5 .\" "Software"), to deal in the Software without restriction, including
   6 .\" without limitation the rights to use, copy, modify, merge, publish,
   7 .\" distribute, sublicense, and/or sell copies of the Software, and to
   8 .\" permit persons to whom the Software is furnished to do so, subject to
   9 .\" the following conditions:
  10 .\"
  11 .\" The above copyright notice and this permission notice shall be included
  12 .\" in all copies or substantial portions of the Software.
  13 .\"
  14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  15 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  16 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  17 .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
  18 .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  19 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  20 .\" OTHER DEALINGS IN THE SOFTWARE.
  21 .\"
  22 .\" Except as contained in this notice, the name of the X Consortium shall
  23 .\" not be used in advertising or otherwise to promote the sale, use or
  24 .\" other dealings in this Software without prior written authorization
  25 .\" from the X Consortium.
  26 .\"
  27 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
  28 .\" Digital Equipment Corporation
  29 .\"
  30 .\" Portions Copyright \(co 1990, 1991 by
  31 .\" Tektronix, Inc.
  32 .\"
  33 .\" Permission to use, copy, modify and distribute this documentation for
  34 .\" any purpose and without fee is hereby granted, provided that the above
  35 .\" copyright notice appears in all copies and that both that copyright notice
  36 .\" and this permission notice appear in all copies, and that the names of
  37 .\" Digital and Tektronix not be used in in advertising or publicity pertaining
  38 .\" to this documentation without specific, written prior permission.
  39 .\" Digital and Tektronix makes no representations about the suitability
  40 .\" of this documentation for any purpose.
  41 .\" It is provided ``as is'' without express or implied warranty.
  42 .\"
  43 .\"
  44 .ds xT X Toolkit Intrinsics \- C Language Interface
  45 .ds xW Athena X Widgets \- C Language X Toolkit Interface
  46 .ds xL Xlib \- C Language X Interface
  47 .ds xC Inter-Client Communication Conventions Manual
  48 .na
  49 .de Ds
  50 .nf
  51 .\\$1D \\$2 \\$1
  52 .ft 1
  53 .\".ps \\n(PS
  54 .\".if \\n(VS>=40 .vs \\n(VSu
  55 .\".if \\n(VS<=39 .vs \\n(VSp
  56 ..
  57 .de De
  58 .ce 0
  59 .if \\n(BD .DF
  60 .nr BD 0
  61 .in \\n(OIu
  62 .if \\n(TM .ls 2
  63 .sp \\n(DDu
  64 .fi
  65 ..
  66 .de FD
  67 .LP
  68 .KS
  69 .TA .5i 3i
  70 .ta .5i 3i
  71 .nf
  72 ..
  73 .de FN
  74 .fi
  75 .KE
  76 .LP
  77 ..
  78 .de IN          \" send an index entry to the stderr
  79 ..
  80 .de C{
  81 .KS
  82 .nf
  83 .D
  84 .\"
  85 .\"     choose appropriate monospace font
  86 .\"     the imagen conditional, 480,
  87 .\"     may be changed to L if LB is too
  88 .\"     heavy for your eyes...
  89 .\"
  90 .ie "\\*(.T"480" .ft L
  91 .el .ie "\\*(.T"300" .ft L
  92 .el .ie "\\*(.T"202" .ft PO
  93 .el .ie "\\*(.T"aps" .ft CW
  94 .el .ft R
  95 .ps \\n(PS
  96 .ie \\n(VS>40 .vs \\n(VSu
  97 .el .vs \\n(VSp
  98 ..
  99 .de C}
 100 .DE
 101 .R
 102 ..
 103 .de Pn
 104 .ie t \\$1\fB\^\\$2\^\fR\\$3
 105 .el \\$1\fI\^\\$2\^\fP\\$3
 106 ..
 107 .de ZN
 108 .ie t \fB\^\\$1\^\fR\\$2
 109 .el \fI\^\\$1\^\fP\\$2
 110 ..
 111 .de hN
 112 .ie t <\fB\\$1\fR>\\$2
 113 .el <\fI\\$1\fP>\\$2
 114 ..
 115 .de NT
 116 .ne 7
 117 .ds NO Note
 118 .if \\n(.$>$1 .if !'\\$2'C' .ds NO \\$2
 119 .if \\n(.$ .if !'\\$1'C' .ds NO \\$1
 120 .ie n .sp
 121 .el .sp 10p
 122 .TB
 123 .ce
 124 \\*(NO
 125 .ie n .sp
 126 .el .sp 5p
 127 .if '\\$1'C' .ce 99
 128 .if '\\$2'C' .ce 99
 129 .in +5n
 130 .ll -5n
 131 .R
 132 ..
 133 .               \" Note End -- doug kraft 3/85
 134 .de NE
 135 .ce 0
 136 .in -5n
 137 .ll +5n
 138 .ie n .sp
 139 .el .sp 10p
 140 ..
 141 .ny0
 142 .TH XChangeKeyboardMapping __libmansuffix__ __xorgversion__ "XLIB FUNCTIONS"
 143 .SH NAME
 144 XChangeKeyboardMapping, XGetKeyboardMapping, XDisplayKeycodes, XSetModifierMapping, XGetModifierMapping, XNewModifiermap, XInsertModifiermapEntry, XDeleteModifiermapEntry, XFreeModifiermap, XModifierKeymap \- manipulate keyboard encoding and keyboard encoding structure
 145 .SH SYNTAX
 146 .HP
 147 int XChangeKeyboardMapping(\^Display *\fIdisplay\fP, int \fIfirst_keycode\fP,
 148 int \fIkeysyms_per_keycode\fP, KeySym *\fIkeysyms\fP, int \fInum_codes\fP\^);
 149 .HP
 150 KeySym *XGetKeyboardMapping(\^Display *\fIdisplay\fP, KeyCode
 151 \fIfirst_keycode\fP, int \fIkeycode_count\fP, int
 152 *\fIkeysyms_per_keycode_return\fP\^);
 153 .HP
 154 int XDisplayKeycodes\^(\^Display *\fIdisplay\fP\^, int
 155 *\fImin_keycodes_return\fP\^, int *\fImax_keycodes_return\fP\^);
 156 .HP
 157 int XSetModifierMapping(\^Display *\fIdisplay\fP, XModifierKeymap
 158 *\fImodmap\fP\^);
 159 .HP
 160 XModifierKeymap *XGetModifierMapping(\^Display *\fIdisplay\fP\^);
 161 .HP
 162 XModifierKeymap *XNewModifiermap(\^int \fImax_keys_per_mod\fP\^);
 163 .HP
 164 XModifierKeymap *XInsertModifiermapEntry\^(\^XModifierKeymap *\fImodmap\fP,
 165 KeyCode \fIkeycode_entry\fP, int \fImodifier\fP\^);
 166 .HP
 167 XModifierKeymap *XDeleteModifiermapEntry\^(\^XModifierKeymap *\fImodmap\fP,
 168 KeyCode \fIkeycode_entry\fP, int \fImodifier\fP\^);
 169 .HP
 170 int XFreeModifiermap(\^XModifierKeymap *\fImodmap\fP\^);
 171 .SH ARGUMENTS
 172 .IP \fIdisplay\fP 1i
 173 Specifies the connection to the X server.
 174 .ds Kc changed or returned
 175 .IP \fIfirst_keycode\fP 1i
 176 Specifies the first KeyCode that is to be \*(Kc.
 177 .IP \fIkeycode_count\fP 1i
 178 Specifies the number of KeyCodes that are to be returned.
 179 .IP \fIkeycode_entry\fP 1i
 180 Specifies the KeyCode.
 181 .IP \fIkeysyms\fP 1i
 182 Specifies an array of KeySyms.
 183 .IP \fIkeysyms_per_keycode\fP 1i
 184 Specifies the number of KeySyms per KeyCode.
 185 .IP \fIkeysyms_per_keycode_return\fP 1i
 186 Returns the number of KeySyms per KeyCode.
 187 .IP \fImax_keys_per_mod\fP 1i
 188 Specifies the number of KeyCode entries preallocated to the modifiers
 189 in the map.
 190 .IP \fImax_keycodes_return\fP 1i
 191 Returns the maximum number of KeyCodes.
 192 .IP \fImin_keycodes_return\fP 1i
 193 Returns the minimum number of KeyCodes.
 194 .IP \fImodifier\fP 1i
 195 Specifies the modifier.
 196 .IP \fImodmap\fP 1i
 197 Specifies the
 198 .ZN XModifierKeymap
 199 structure.
 200 .IP \fInum_codes\fP 1i
 201 Specifies the number of KeyCodes that are to be changed.
 202 .SH DESCRIPTION
 203 The
 204 .ZN XChangeKeyboardMapping
 205 function defines the symbols for the specified number of KeyCodes
 206 starting with first_keycode.
 207 The symbols for KeyCodes outside this range remain unchanged.
 208 The number of elements in keysyms must be:
 209 .LP
 210 .Ds
 211 num_codes * keysyms_per_keycode
 212 .De
 213 .LP
 214 The specified first_keycode must be greater than or equal to min_keycode
 215 returned by
 216 .ZN XDisplayKeycodes ,
 217 or a
 218 .ZN BadValue
 219 error results.
 220 In addition, the following expression must be less than or equal to
 221 max_keycode as returned by
 222 .ZN XDisplayKeycodes ,
 223 or a
 224 .ZN BadValue
 225 error results:
 226 .LP
 227 .Ds
 228 first_keycode + num_codes \- 1
 229 .De
 230 .LP
 231 KeySym number N, counting from zero, for KeyCode K has the following index
 232 in keysyms, counting from zero:
 233 .LP
 234 .Ds
 235 (K \- first_keycode) * keysyms_per_keycode + N
 236 .De
 237 .LP
 238 The specified keysyms_per_keycode can be chosen arbitrarily by the client
 239 to be large enough to hold all desired symbols.
 240 A special KeySym value of
 241 .ZN NoSymbol
 242 should be used to fill in unused elements
 243 for individual KeyCodes.
 244 It is legal for
 245 .ZN NoSymbol
 246 to appear in nontrailing positions
 247 of the effective list for a KeyCode.
 248 .ZN XChangeKeyboardMapping
 249 generates a
 250 .ZN MappingNotify
 251 event.
 252 .LP
 253 There is no requirement that the X server interpret this mapping.
 254 It is merely stored for reading and writing by clients.
 255 .LP
 256 .ZN XChangeKeyboardMapping
 257 can generate
 258 .ZN BadAlloc
 259 and
 260 .ZN BadValue
 261 errors.
 262 .LP
 263 The
 264 .ZN XGetKeyboardMapping
 265 function returns the symbols for the specified number of KeyCodes
 266 starting with first_keycode.
 267 The value specified in first_keycode must be greater than
 268 or equal to min_keycode as returned by
 269 .ZN XDisplayKeycodes ,
 270 or a
 271 .ZN BadValue
 272 error results.
 273 In addition, the following expression must be less than or equal
 274 to max_keycode as returned by
 275 .ZN XDisplayKeycodes :
 276 .LP
 277 .Ds
 278 first_keycode + keycode_count \- 1
 279 .De
 280 .LP
 281 If this is not the case, a
 282 .ZN BadValue
 283 error results.
 284 The number of elements in the KeySyms list is:
 285 .LP
 286 .Ds
 287 keycode_count * keysyms_per_keycode_return
 288 .De
 289 .LP
 290 KeySym number N, counting from zero, for KeyCode K has the following index
 291 in the list, counting from zero:
 292 .Ds
 293 (K \- first_code) * keysyms_per_code_return + N
 294 .De
 295 .LP
 296 The X server arbitrarily chooses the keysyms_per_keycode_return value
 297 to be large enough to report all requested symbols.
 298 A special KeySym value of
 299 .ZN NoSymbol
 300 is used to fill in unused elements for
 301 individual KeyCodes.
 302 To free the storage returned by
 303 .ZN XGetKeyboardMapping ,
 304 use
 305 .ZN XFree .
 306 .LP
 307 .ZN XGetKeyboardMapping
 308 can generate a
 309 .ZN BadValue
 310 error.
 311 .LP
 312 The
 313 .ZN XDisplayKeycodes
 314 function returns the min-keycodes and max-keycodes supported by the
 315 specified display.
 316 The minimum number of KeyCodes returned is never less than 8,
 317 and the maximum number of KeyCodes returned is never greater than 255.
 318 Not all KeyCodes in this range are required to have corresponding keys.
 319 .LP
 320 The
 321 .ZN XSetModifierMapping
 322 function specifies the KeyCodes of the keys (if any) that are to be used
 323 as modifiers.
 324 If it succeeds,
 325 the X server generates a
 326 .ZN MappingNotify
 327 event, and
 328 .ZN XSetModifierMapping
 329 returns
 330 .ZN MappingSuccess .
 331 X permits at most 8 modifier keys.
 332 If more than 8 are specified in the
 333 .ZN XModifierKeymap
 334 structure, a
 335 .ZN BadLength
 336 error results.
 337 .LP
 338 The modifiermap member of the
 339 .ZN XModifierKeymap
 340 structure contains 8 sets of max_keypermod KeyCodes,
 341 one for each modifier in the order
 342 .ZN Shift ,
 343 .ZN Lock ,
 344 .ZN Control ,
 345 .ZN Mod1 ,
 346 .ZN Mod2 ,
 347 .ZN Mod3 ,
 348 .ZN Mod4 ,
 349 and
 350 .ZN Mod5 .
 351 Only nonzero KeyCodes have meaning in each set,
 352 and zero KeyCodes are ignored.
 353 In addition, all of the nonzero KeyCodes must be in the range specified by
 354 min_keycode and max_keycode in the
 355 .ZN Display
 356 structure,
 357 or a
 358 .ZN BadValue
 359 error results.
 360 .LP
 361 An X server can impose restrictions on how modifiers can be changed,
 362 for example,
 363 if certain keys do not generate up transitions in hardware,
 364 if auto-repeat cannot be disabled on certain keys,
 365 or if multiple modifier keys are not supported.
 366 If some such restriction is violated,
 367 the status reply is
 368 .ZN MappingFailed ,
 369 and none of the modifiers are changed.
 370 If the new KeyCodes specified for a modifier differ from those
 371 currently defined and any (current or new) keys for that modifier are
 372 in the logically down state,
 373 .ZN XSetModifierMapping
 374 returns
 375 .ZN MappingBusy ,
 376 and none of the modifiers is changed.
 377 .LP
 378 .ZN XSetModifierMapping
 379 can generate
 380 .ZN BadAlloc
 381 and
 382 .ZN BadValue
 383 errors.
 384 .LP
 385 The
 386 .ZN XGetModifierMapping
 387 function returns a pointer to a newly created
 388 .ZN XModifierKeymap
 389 structure that contains the keys being used as modifiers.
 390 The structure should be freed after use by calling
 391 .ZN XFreeModifiermap .
 392 If only zero values appear in the set for any modifier,
 393 that modifier is disabled.
 394 .LP
 395 The
 396 .ZN XNewModifiermap
 397 function returns a pointer to
 398 .ZN XModifierKeymap
 399 structure for later use.
 400 .LP
 401 The
 402 .ZN XInsertModifiermapEntry
 403 function adds the specified KeyCode to the set that controls the specified
 404 modifier and returns the resulting
 405 .ZN XModifierKeymap
 406 structure (expanded as needed).
 407 .LP
 408 The
 409 .ZN XDeleteModifiermapEntry
 410 function deletes the specified KeyCode from the set that controls the
 411 specified modifier and returns a pointer to the resulting
 412 .ZN XModifierKeymap
 413 structure.
 414 .LP
 415 The
 416 .ZN XFreeModifiermap
 417 function frees the specified
 418 .ZN XModifierKeymap
 419 structure.
 420 .SH STRUCTURES
 421 The
 422 .ZN XModifierKeymap
 423 structure contains:
 424 .LP
 425 .Ds 0
 426 .TA .5i 2.5i
 427 .ta .5i 2.5i
 428 typedef struct {
 429         int max_keypermod;      /\&* This server's max number of keys per modifier */
 430         KeyCode *modifiermap;   /\&* An 8 by max_keypermod array of the modifiers */
 431 } XModifierKeymap;
 432 .De
 433 .SH DIAGNOSTICS
 434 .TP 1i
 435 .ZN BadAlloc
 436 The server failed to allocate the requested resource or server memory.
 437 .TP 1i
 438 .ZN BadValue
 439 Some numeric value falls outside the range of values accepted by the request.
 440 Unless a specific range is specified for an argument, the full range defined
 441 by the argument's type is accepted.  Any argument defined as a set of
 442 alternatives can generate this error.
 443 .SH "SEE ALSO"
 444 XFree(__libmansuffix__),
 445 XkbGetMap(__libmansuffix__),
 446 XSetPointerMapping(__libmansuffix__)
 447 .br
 448 \fI\*(xL\fP