man/xkb/XkbGetCompatMap.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 XkbGetCompatMap __libmansuffix__ __xorgversion__ "XKB FUNCTIONS"
  24 .SH NAME
  25 XkbGetCompatMap \- Fetch any combination of the current compatibility map
  26 components from the server
  27 .SH SYNOPSIS
  28 .HP
  29 .B Status XkbGetCompatMap
  30 .BI "(\^Display *" "display" "\^,"
  31 .BI "unsigned int " "which" "\^,"
  32 .BI "XkbDescRec *" "xkb" "\^);"
  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 compatibility map components to fetch
  42 .TP
  43 .I \- xkb
  44 keyboard description where results placed
  45 .SH DESCRIPTION
  46 .LP
  47 When another client modifies the compatibility map, you are notified if you have
  48 selected for XkbCompatMapNotify events.
  49 .I XkbGetCompatMap
  50 is particularly useful when you receive an event of this type, as it allows you
  51 to update your program's version of the compatibility map to match the modified
  52 version now in the server. If your program is dealing with multiple servers and
  53 needs to configure them all in a similar manner, the updated compatibility map
  54 may be used to reconfigure other servers.
  55
  56 .I XkbGetCompatMap
  57 fetches the components of the compatibility map specified in
  58 .I which
  59 from the server specified by
  60 .I display
  61 and places them in the
  62 .I compat
  63 structure of the keyboard description
  64 .I xkb.
  65 Valid values for
  66 .I which
  67 are an inclusive OR of the values shown in Table 1.
  68
  69 .TS
  70 c s s
  71 l l l
  72 l l l.
  73 Table 1 Compatibility Map Component Masks
  74 _
  75 Mask    Value   Affecting
  76 _
  77 XkbSymInterpMask        (1<<0)  Symbol interpretations
  78 XkbGroupCompatMask      (1<<1)  Group maps
  79 XkbAllCompatMask        (0x3)   All compatibility map components
  80 .TE
  81
  82 If no compatibility map structure is allocated in
  83 .I xkb
  84 upon entry,
  85 .I XkbGetCompatMap
  86 allocates one. If one already exists, its contents are overwritten with the
  87 returned results.
  88
  89 .I XkbGetCompatMap
  90 fetches compatibility map information for the device specified by the
  91 .I device_spec
  92 field of
  93 .I xkb.
  94 Unless you have specifically modified this field, it is the default keyboard
  95 device.
  96 .I XkbGetCompatMap
  97 returns Success if successful, BadAlloc if it is unable to obtain necessary
  98 storage for either the return values or work space, BadMatch if the
  99 .I dpy
 100 field of the
 101 .I xkb
 102 argument is non-NULL and does not match the
 103 .I display
 104 argument, and BadLength under certain conditions caused by server or Xkb
 105 implementation errors.
 106 .SH DIAGNOSTICS
 107 .TP 15
 108 .B BadAlloc
 109 Unable to allocate storage
 110 .TP 15
 111 .B BadLength
 112 The length of a request is shorter or longer than that required to minimally contain the arguments
 113 .TP 15
 114 .B BadMatch
 115 A compatible version of Xkb was not available in the server or an argument has
 116 correct type and range, but is otherwise invalid