man/xkb/XkbSetCompatMap.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 XkbSetCompatMap __libmansuffix__ __xorgversion__ "XKB FUNCTIONS"
  24 .SH NAME
  25 XkbSetCompatMap \- Modify the server's compatibility map
  26 .SH SYNOPSIS
  27 .HP
  28 .B Bool XkbSetCompatMap
  29 .BI "(\^Display *" "display" "\^,"
  30 .BI "unsigned int " "which" "\^,"
  31 .BI "XkbDescPtr " "xkb" "\^,"
  32 .BI "Bool " "update_actions" "\^);"
  33 .if n .ti +5n
  34 .if t .ti +.5i
  35 .SH ARGUMENTS
  36 .TP
  37 .I \- display
  38 connection to server
  39 .TP
  40 .I \- which
  41 mask of compat map components to set
  42 .TP
  43 .I \- xkb
  44 source for compat map components
  45 .TP
  46 .I \- update_actions
  47 True => apply to server's keyboard map
  48 .SH DESCRIPTION
  49 .LP
  50 To modify the server's compatibility map, first modify a local copy of the Xkb
  51 compatibility map, then call
  52 .I XkbSetCompatMap.
  53 You may allocate a new compatibility map for this purpose using
  54 .I XkbAllocCompatMap.
  55 You may also use a compatibility map from another server, although you need to
  56 adjust the
  57 .I device_spec
  58 field in the XkbDescRec accordingly. Note that symbol interpretations in a
  59 compatibility map (
  60 .I sym_interpret,
  61 the vector of XkbSymInterpretRec structures) are also allocated using this same
  62 function.
  63
  64 .I XkbSetCompatMap
  65 copies compatibility map information from the keyboard description in
  66 .I xkb
  67 to the server specified in
  68 .I display
  69 's compatibility map for the device specified by the
  70 .I device_spec
  71 field of
  72 .I xkb.
  73 Unless you have specifically modified this field, it is the default keyboard
  74 device.
  75 .I which
  76 specifies the compatibility map components to be set, and is an inclusive OR of
  77 the bits shown in Table 1.
  78
  79 .TS
  80 c s s
  81 l l l
  82 l l lw(3i).
  83 Table 1 Compatibility Map Component Masks
  84 _
  85 Mask    Value   Affecting
  86 _
  87 XkbSymInterpMask        (1<<0)  Symbol interpretations
  88 XkbGroupCompatMask      (1<<1)  Group maps
  89 XkbAllCompatMask        (0x3)   All compatibility map components
  90 .TE
  91
  92 After updating its compatibility map for the specified device, if
  93 .I update_actions
  94 is True, the server applies the new compatibility map to its entire keyboard for
  95 the device to generate a new set of key semantics, compatibility state, and a
  96 new core keyboard map. If
  97 .I update_actions
  98 is False, the new compatibility map is not used to generate any modifications to
  99 the current device semantics, state, or core keyboard map. One reason for not
 100 applying the compatibility map immediately would be if one server was being
 101 configured to match another on a piecemeal basis; the map should not be applied
 102 until everything is updated. To force an update at a later time, use
 103 .I XkbSetCompatMap
 104 specifying
 105 .I which
 106 as zero and
 107 .I update_actions
 108 as True.
 109
 110 .I XkbSetCompatMap
 111 returns True if successful and False if unsuccessful. The server may report
 112 problems it encounters when processing the request subsequently via protocol
 113 errors.
 114 .SH "RETURN VALUES"
 115 .TP 15
 116 True
 117 The
 118 .I XkbSetCompatMap
 119 function returns True if successful.
 120 .TP 15
 121 False
 122 The
 123 .I XkbSetCompatMap
 124 function returns False if unsuccessful.
 125 .SH STRUCTURES
 126 .LP
 127 The complete description of an Xkb keyboard is given by an XkbDescRec. The
 128 component
 129 structures in the XkbDescRec represent the major Xkb components.
 130
 131 .nf
 132 typedef struct {
 133    struct _XDisplay * display;      /\(** connection to X server */
 134    unsigned short     flags;        /\(** private to Xkb, do not modify */
 135    unsigned short     device_spec;  /\(** device of interest */
 136    KeyCode            min_key_code; /\(** minimum keycode for device */
 137    KeyCode            max_key_code; /\(** maximum keycode for device */
 138    XkbControlsPtr     ctrls;        /\(** controls */
 139    XkbServerMapPtr    server;       /\(** server keymap */
 140    XkbClientMapPtr    map;          /\(** client keymap */
 141    XkbIndicatorPtr    indicators;   /\(** indicator map */
 142    XkbNamesPtr        names;        /\(** names for all components */
 143    XkbCompatMapPtr    compat;       /\(** compatibility map */
 144    XkbGeometryPtr     geom;         /\(** physical geometry of keyboard */
 145 } XkbDescRec, *XkbDescPtr;
 146
 147 .fi
 148 The
 149 .I display
 150 field points to an X display structure. The
 151 .I flags field is private to the library: modifying
 152 .I flags
 153 may yield unpredictable results. The
 154 .I device_spec
 155 field specifies the device identifier of the keyboard input device, or
 156 XkbUseCoreKeyboard, which specifies the core keyboard device. The
 157 .I min_key_code
 158 and
 159 .I max_key_code
 160 fields specify the least and greatest keycode that can be returned by the
 161 keyboard.
 162
 163 Each structure component has a corresponding mask bit that is used in function
 164 calls to
 165 indicate that the structure should be manipulated in some manner, such as
 166 allocating it
 167 or freeing it. These masks and their relationships to the fields in the
 168 XkbDescRec are
 169 shown in Table 2.
 170
 171 .TS
 172 c s s
 173 l l l
 174 l l l.
 175 Table 2 Mask Bits for XkbDescRec
 176 _
 177 Mask Bit        XkbDescRec Field        Value
 178 _
 179 XkbControlsMask ctrls   (1L<<0)
 180 XkbServerMapMask        server  (1L<<1)
 181 XkbIClientMapMask       map     (1L<<2)
 182 XkbIndicatorMapMask     indicators      (1L<<3)
 183 XkbNamesMask    names   (1L<<4)
 184 XkbCompatMapMask        compat  (1L<<5)
 185 XkbGeometryMask geom    (1L<<6)
 186 XkbAllComponentsMask    All Fields      (0x7f)
 187 .TE
 188
 189 The XkbSymInterpretRec structure specifies a symbol interpretation:
 190 .nf
 191
 192     typedef struct {
 193         KeySym        sym;         /\(** keysym of interest or NULL */
 194         unsigned char flags;       /\(** XkbSI_AutoRepeat, XkbSI_LockingKey */
 195         unsigned char match;       /\(** specifies how mods is interpreted */
 196         unsigned char mods;        /\(** modifier bits, correspond to eight real modifiers */
 197         unsigned char virtual_mod; /\(** 1 modifier to add to key virtual mod map */
 198         XkbAnyAction  act;         /\(** action to bind to symbol position on key */
 199     } XkbSymInterpretRec,*XkbSymInterpretPtr;
 200
 201 .fi
 202 .SH "SEE ALSO"
 203 .BR XkbAllocCompatMap (__libmansuffix__)