man/xkb/XkbKeyActionEntry.man

   1 .\" Copyright 1999 Oracle and/or its affiliates. All rights reserved.
   2 .\"
   3 .\" Permission is hereby granted, free of charge, to any person obtaining a
   4 .\" copy of this software and associated documentation files (the "Software"),
   5 .\" to deal in the Software without restriction, including without limitation
   6 .\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
   7 .\" and/or sell copies of the Software, and to permit persons to whom the
   8 .\" Software is furnished to do so, subject to the following conditions:
   9 .\"
  10 .\" The above copyright notice and this permission notice (including the next
  11 .\" paragraph) shall be included in all copies or substantial portions of the
  12 .\" Software.
  13 .\"
  14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15 .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16 .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  17 .\" THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  18 .\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  19 .\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  20 .\" DEALINGS IN THE SOFTWARE.
  21 .\"
  22 .TH XkbKeyActionEntry __libmansuffix__ __xorgversion__ "XKB FUNCTIONS"
  23 .SH NAME
  24 XkbKeyActionEntry \- Returns a pointer to the key action corresponding to
  25 group grp and shift level lvl from the two-dimensional table of key actions
  26 associated with the key corresponding to
  27 keycode
  28 .SH SYNOPSIS
  29 .HP
  30 .B XkbAction * XkbKeyActionEntry
  31 .BI "(\^XkbDescPtr " "xkb" "\^,"
  32 .BI "KeyCode " "keycode" "\^,"
  33 .BI "int " "shift" "\^,"
  34 .BI "int " "grp" "\^);"
  35 .if n .ti +5n
  36 .if t .ti +.5i
  37 .SH ARGUMENTS
  38 .TP
  39 .I \- xkb
  40 Xkb description of interest
  41 .TP
  42 .I \- keycode
  43 keycode of interest
  44 .TP
  45 .I \- shift
  46 shift level within group
  47 .TP
  48 .I \- grp
  49 group index for group of interest
  50 .SH DESCRIPTION
  51 .LP
  52 A key action defines the effect key presses and releases have on the internal
  53 state of the server. For example,
  54 the expected key action associated with pressing the Shift key is to set the
  55 Shift modifier. There is zero or one
  56 key action associated with each keysym bound to each key.
  57
  58 Just as the entire list of key symbols for the keyboard mapping is held in the
  59 .I syms
  60 field of the client map, the entire list of key actions for the keyboard mapping
  61 is held in the
  62 .I acts
  63 array of the server map. The total size of
  64 .I acts
  65 is specified by
  66 .I size_acts,
  67 and the number of entries is specified by
  68 .I num_acts.
  69
  70 The
  71 .I key_acts
  72 array, indexed by keycode, describes the actions associated with a key. The
  73 .I key_acts
  74 array has
  75 .I min_key_code
  76 unused entries at the start to allow direct indexing using a keycode. If a
  77 .I key_acts
  78 entry is zero, it means the key does not have any actions associated with it. If
  79 an entry is not zero, the entry
  80 represents an index into the
  81 .I acts
  82 field of the server map, much as the
  83 .I offset
  84 field of a KeySymMapRec structure is an index into the
  85 .I syms
  86 field of the client map.
  87
  88 The reason the
  89 .I acts
  90 field is a linear list of XkbActions is to reduce the memory consumption
  91 associated with a keymap. Because Xkb
  92 allows individual keys to have multiple shift levels and a different number of
  93 groups per key, a single
  94 two-dimensional array of KeySyms would potentially be very large and sparse.
  95 Instead, Xkb provides a small
  96 two-dimensional array of XkbActions for each key. To store all of these
  97 individual arrays, Xkb concatenates each
  98 array together in the
  99 .I acts
 100 field of the server map.
 101
 102 The key action structures consist only of fields of type char or unsigned char.
 103 This is done to optimize data
 104 transfer when the server sends bytes over the wire. If the fields are anything
 105 but bytes, the server has to sift
 106 through all of the actions and swap any nonbyte fields. Because they consist of
 107 nothing but bytes, it can just
 108 copy them out.
 109
 110 .I XkbKeyActionEntry
 111 returns the key action corresponding to group
 112 .I grp
 113 and shift level
 114 .I lvl
 115 from the two-dimensional table of key actions associated with the key
 116 corresponding to
 117 .I keycode.
 118 .SH STRUCTURES
 119 .LP
 120 The KeySymMapRec structure is defined as follows:
 121 .nf
 122
 123     #define XkbNumKbdGroups             4
 124     #define XkbMaxKbdGroup              (XkbNumKbdGroups-1)
 125
 126     typedef struct {                    /\(** map to keysyms for a single keycode
 127 */
 128         unsigned char       kt_index[XkbNumKbdGroups];  /\(** key type index for
 129 each group */
 130         unsigned char       group_info; /\(** # of groups and out of range group
 131 handling */
 132         unsigned char       width;      /\(** max # of shift levels for key */
 133         unsigned short      offset;     /\(** index to keysym table in syms array
 134 */
 135 } XkbSymMapRec, *XkbSymMapPtr;
 136
 137 .fi