man/xkb/XkbAllocClientMap.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 XkbAllocClientMap __libmansuffix__ __xorgversion__ "XKB FUNCTIONS"
  24 .SH NAME
  25 XkbAllocClientMap \- Allocate and initialize an empty client map description
  26 record
  27 .SH SYNOPSIS
  28 .HP
  29 .B Status XkbAllocClientMap
  30 .BI "(\^XkbDescPtr " "xkb" "\^,"
  31 .BI "unsigned int " "which" "\^,"
  32 .BI "unsigned int " "type_count" "\^);"
  33 .if n .ti +5n
  34 .if t .ti +.5i
  35 .SH ARGUMENTS
  36 .TP
  37 .I \- xkb
  38 keyboard description in which to allocate client map
  39 .TP
  40 .I \- which
  41 mask selecting map components to allocate
  42 .TP
  43 .I \- type_count
  44 value of num_types field in map to be allocated
  45 .SH DESCRIPTION
  46 .LP
  47 Calling
  48 .I XkbGetMap
  49 should be sufficient for most applications to get client and server maps. As a
  50 result, most applications do not need to directly allocate client and server
  51 maps.
  52
  53 If you change the number of key types or construct map components without
  54 loading the necessary components from the X server, do not allocate any map
  55 components directly using
  56 .I malloc
  57 or
  58 .I Xmalloc.
  59 Instead, use the Xkb allocators,
  60 .I XkbAllocClientMap,
  61 and
  62 .I XkbAllocServerMap.
  63
  64 Similarly, use the Xkb destructors,
  65 .I XkbFreeClientMap,
  66 and
  67 .I XkbFreeServerMap
  68 instead of
  69 .I free
  70 or
  71 .I Xfree.
  72
  73 .I XkbAllocClientMap
  74 allocates and initializes an empty client map in the
  75 .I map
  76 field of the keyboard description specified by
  77 .I xkb.
  78 The
  79 .I which
  80 parameter specifies the particular components of the client map structure to
  81 allocate and is a mask composed by a bitwise inclusive OR of one or more of the
  82 masks shown in Table 1.
  83 .bp
  84 .TS
  85 c s
  86 l l
  87 l lw(4i).
  88 Table 1 XkbAllocClientMap Masks
  89 _
  90 Mask    Effect
  91 _
  92 XkbKeyTypesMask T{
  93 The type_count field specifies the number of entries to preallocate for the
  94 types field of the client map. If the type_count field is less than
  95 XkbNumRequiredTypes returns BadValue.
  96 T}
  97 .sp
  98 XkbKeySymsMask  T{
  99 The min_key_code and max_key_code fields of the xkb parameter are used to
 100 allocate the syms and key_sym_map fields of the client map. The fields are
 101 allocated to contain the maximum number of entries necessary for max_key_code -
 102 min_key_code + 1 keys.
 103 T}
 104 .sp
 105 XkbModifierMapMask      T{
 106 The min_key_code and max_key_code fields of the xkb parameter are used to
 107 allocate the modmap field of the client map. The field is allocated to contain
 108 the maximum number of entries necessary for max_key_code - min_key_code + 1
 109 keys.
 110 T}
 111 .TE
 112
 113 NOTE: The
 114 .I min_key_code
 115 and
 116 .I max_key_code
 117 fields of the
 118 .I xkb
 119 parameter must be legal values if the XkbKeySymsMask or XkbModifierMapMask masks
 120 are set in the
 121 .I which
 122 parameter. If they are not valid,
 123 .I XkbAllocClientMap
 124 returns BadValue.
 125
 126 If the client map of the keyboard description is not NULL, and any fields are
 127 already allocated in the client map,
 128 .I XkbAllocClientMap
 129 does not overwrite the existing values; it simply ignores that part of the
 130 request. The only exception is the
 131 .I types
 132 array. If
 133 .I type_count
 134 is greater than the current
 135 .I num_types
 136 field of the client map,
 137 .I XkbAllocClientMap
 138 resizes the
 139 .I types
 140 array and resets the
 141 .I num_types
 142 field accordingly.
 143
 144 If
 145 .I XkbAllocClientMap
 146 is successful, it returns Success. Otherwise, it can return either BadMatch,
 147 BadAlloc, or BadValue errors.
 148 .SH DIAGNOSTICS
 149 .TP 15
 150 .B BadAlloc
 151 Unable to allocate storage
 152 .TP 15
 153 .B BadMatch
 154 A compatible version of Xkb was not available in the server or an argument has
 155 correct type and range, but is otherwise invalid
 156 .TP 15
 157 .B BadValue
 158 An argument is out of range
 159 .SH "SEE ALSO"
 160 .BR XkbAllocClientMap (__libmansuffix__),
 161 .BR XkbAllocServerMap (__libmansuffix__),
 162 .BR XkbFreeClientMap, (__libmansuffix__),
 163 .BR XkbFreeServerMap (__libmansuffix__),
 164 .BR XkbGetMap (__libmansuffix__)