man/xkb/XkbGetUpdatedMap.man

   1 '\" t
   2 .\" Copyright 1999 Oracle and/or its affiliates. All rights reserved.
   3 .\"
   4 .\" Permission is hereby granted, free of charge, to any person obtaining a
   5 .\" copy of this software and associated documentation files (the "Software"),
   6 .\" to deal in the Software without restriction, including without limitation
   7 .\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
   8 .\" and/or sell copies of the Software, and to permit persons to whom the
   9 .\" Software is furnished to do so, subject to the following conditions:
  10 .\"
  11 .\" The above copyright notice and this permission notice (including the next
  12 .\" paragraph) shall be included in all copies or substantial portions of the
  13 .\" Software.
  14 .\"
  15 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16 .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17 .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  18 .\" THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19 .\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  20 .\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  21 .\" DEALINGS IN THE SOFTWARE.
  22 .\"
  23 .TH XkbGetUpdatedMap __libmansuffix__ __xorgversion__ "XKB FUNCTIONS"
  24 .SH NAME
  25 XkbGetUpdatedMap \-  Update the client or server map information in an existing
  26 keyboard description
  27 .SH SYNOPSIS
  28 .HP
  29 .B Status XkbGetUpdatedMap
  30 .BI "(\^Display *" "display" "\^,"
  31 .BI "unsigned int " "which" "\^,"
  32 .BI "XkbDescPtr " "xkb" "\^);"
  33 .if n .ti +5n
  34 .if t .ti +.5i
  35 .SH ARGUMENTS
  36 .TP
  37 .I \- display
  38 connection to X server
  39 .TP
  40 .I \- which
  41 mask selecting subcomponents to populate
  42 .TP
  43 .I \- xkb
  44 keyboard description to be updated
  45 .SH DESCRIPTION
  46 .LP
  47 The
  48 .I which
  49 parameter is a bitwise inclusive OR of the masks in Table 1. If the needed
  50 components of the
  51 .I xkb
  52 structure are not already allocated,
  53 .I XkbGetUpdatedMap
  54 allocates them.
  55 .I XkbGetUpdatedMap
  56 fetches the requested information for the device specified in the XkbDescRec
  57 passed in the
  58 .I xkb
  59 parameter.
  60
  61 .TS
  62 c s s s s
  63 c s s s s
  64 l l l l l
  65 l l l l l
  66 lw(3i) l l lw(1i) lw(3i).
  67 Table 1 Xkb Mapping Component Masks
  68 and Convenience Functions
  69 _
  70 Mask    Value   Map     Fields  Convenience
  71                                 Functions
  72 _
  73 T{
  74 XkbKeyTypesMask
  75 T}      (1<<0)  client  T{
  76 types
  77 .br
  78 size_types
  79 .br
  80 num_types
  81 T}      T{
  82 XkbGetKeyTypes
  83 .br
  84 XkbResizeKeyType
  85 .br
  86 XkbCopyKeyType
  87 .br
  88 XkbCopyKeyTypes
  89 T}
  90 T{
  91 XkbKeySymsMask
  92 T}      (1<<1)  client  T{
  93 syms
  94 .br
  95 size_syms
  96 .br
  97 num_syms
  98 .br
  99 key_sym_map
 100 T}      T{
 101 XkbGetKeySyms
 102 .br
 103 XkbResizeKeySyms
 104 .br
 105 XkbChangeTypesOfKey
 106 T}
 107 T{
 108 XkbModifierMapMask
 109 T}      (1<<2)  client  modmap  T{
 110 XkbGetKeyModifierMap
 111 T}
 112 T{
 113 XkbExplicitComponentsMask
 114 T}      (1<<3)  server  T{
 115 explicit
 116 T}      T{
 117 XkbGetKeyExplicitComponents
 118 T}
 119 T{
 120 XkbKeyActionsMask
 121 T}      (1<<4)  server  T{
 122 key_acts
 123 .br
 124 acts
 125 .br
 126 num_acts
 127 .br
 128 size_acts
 129 T}      T{
 130 XkbGetKeyActions
 131 .br
 132 XkbResizeKeyActions
 133 T}
 134 T{
 135 XkbKeyBehaviorsMask
 136 T}      (1<<5)  server  T{
 137 behaviors
 138 T}      T{
 139 XkbGetKeyBehaviors
 140 T}
 141 T{
 142 XkbVirtualModsMask
 143 T}      (1<<6)  server  T{
 144 vmods
 145 T}      T{
 146 XkbGetVirtualMods
 147 T}
 148 T{
 149 XkbVirtualModMapMask
 150 T}      (1<<7)  server  T{
 151 vmodmap
 152 T}      T{
 153 XkbGetVirtualModMap
 154 T}
 155 .TE
 156
 157 .I XkbGetUpdatedMap
 158 is synchronous; it queries the server for the desired information, waits for a
 159 reply, and then returns. If successful,
 160 .I XkbGetUpdatedMap
 161 returns Success. If unsuccessful,
 162 .I XkbGetUpdatedMap
 163 returns one of the following: BadAlloc (unable to allocate a component in the
 164 XkbDescRec structure), BadValue (some mask bits in
 165 .I which
 166 are undefined), BadImplementation (a compatible version of the Xkb extension is
 167 not available in the server or the reply from the server was invalid).
 168 .SH "RETURN VALUES"
 169 .TP 15
 170 Success
 171 The
 172 .I XkbGetUpdatedMap
 173 function returns Success if a reply is received to the server query for the desired information.
 174 .SH STRUCTURES
 175 .LP
 176 The complete description of an Xkb keyboard is given by an XkbDescRec. The
 177 component
 178 structures in the XkbDescRec represent the major Xkb components.
 179
 180 .nf
 181 typedef struct {
 182    struct _XDisplay * display;      /\(** connection to X server */
 183    unsigned short     flags;        /\(** private to Xkb, do not modify */
 184    unsigned short     device_spec;  /\(** device of interest */
 185    KeyCode            min_key_code; /\(** minimum keycode for device */
 186    KeyCode            max_key_code; /\(** maximum keycode for device */
 187    XkbControlsPtr     ctrls;        /\(** controls */
 188    XkbServerMapPtr    server;       /\(** server keymap */
 189    XkbClientMapPtr    map;          /\(** client keymap */
 190    XkbIndicatorPtr    indicators;   /\(** indicator map */
 191    XkbNamesPtr        names;        /\(** names for all components */
 192    XkbCompatMapPtr    compat;       /\(** compatibility map */
 193    XkbGeometryPtr     geom;         /\(** physical geometry of keyboard */
 194 } XkbDescRec, *XkbDescPtr;
 195
 196 .fi
 197 The
 198 .I display
 199 field points to an X display structure. The
 200 .I flags
 201 field is private to the library: modifying
 202 .I flags
 203 may yield unpredictable results. The
 204 .I device_spec
 205 field specifies the device identifier of the keyboard input device, or
 206 XkbUseCoreKeyboard, which specifies the core keyboard device. The
 207 .I min_key_code
 208 and
 209 .I max_key_code
 210 fields specify the least and greatest keycode that can be returned by the
 211 keyboard.
 212
 213 Each structure component has a corresponding mask bit that is used in function
 214 calls to
 215 indicate that the structure should be manipulated in some manner, such as
 216 allocating it
 217 or freeing it. These masks and their relationships to the fields in the
 218 XkbDescRec are
 219 shown in Table 2.
 220 .bp
 221 .TS
 222 c s s
 223 l l l
 224 l l l.
 225 Table 2 Mask Bits for XkbDescRec
 226 _
 227 Mask Bit        XkbDescRec Field        Value
 228 _
 229 XkbControlsMask ctrls   (1L<<0)
 230 XkbServerMapMask        server  (1L<<1)
 231 XkbIClientMapMask       map     (1L<<2)
 232 XkbIndicatorMapMask     indicators      (1L<<3)
 233 XkbNamesMask    names   (1L<<4)
 234 XkbCompatMapMask        compat  (1L<<5)
 235 XkbGeometryMask geom    (1L<<6)
 236 XkbAllComponentsMask    All Fields      (0x7f)
 237 .TE
 238 .SH DIAGNOSTICS
 239 .TP 15
 240 .B BadAlloc
 241 Unable to allocate storage
 242 .TP 15
 243 .B BadImplementation
 244 Invalid reply from server
 245 .TP 15
 246 .B BadValue
 247 An argument is out of range
 248 .SH "SEE ALSO"
 249 .BR XkbChangeTypesOfKey (__libmansuffix__),
 250 .BR XkbCopyKeyType (__libmansuffix__),
 251 .BR XkbCopyKeyTypes (__libmansuffix__),
 252 .BR XkbGetKeyActions (__libmansuffix__),
 253 .BR XkbGetKeyBehaviors (__libmansuffix__),
 254 .BR XkbGetKeyExplicitComponents (__libmansuffix__),
 255 .BR XkbGetKeyModifierMap (__libmansuffix__),
 256 .BR XkbGetKeySyms (__libmansuffix__),
 257 .BR XkbGetKeyTypes (__libmansuffix__),
 258 .BR XkbResizeKeyActions (__libmansuffix__),
 259 .BR XkbResizeKeySyms (__libmansuffix__),
 260 .BR XkbResizeKeyType (__libmansuffix__),
 261 .BR XkbGetVirtualModMap (__libmansuffix__),
 262 .BR XkbGetVirtualMods (__libmansuffix__)