man/xkb/XkbGetNames.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 XkbGetNames __libmansuffix__ __xorgversion__ "XKB FUNCTIONS"
  24 .SH NAME
  25 XkbGetNames \- Obtain symbolic names from the server
  26 .SH SYNOPSIS
  27 .HP
  28 .B Status XkbGetNames
  29 .BI "(\^Display *" "dpy" "\^,"
  30 .BI "unsigned int " "which" "\^,"
  31 .BI "XkbDescPtr " "Xkb" "\^);"
  32 .if n .ti +5n
  33 .if t .ti +.5i
  34 .SH ARGUMENTS
  35 .TP
  36 .I \- dpy
  37 connection to the X server
  38 .TP
  39 .I \- which
  40 mask of names or map components to be updated
  41 .TP
  42 .I \- Xkb
  43 keyboard description to be updated
  44 .SH DESCRIPTION
  45 .LP
  46 .I XkbGetNames
  47 retrieves symbolic names for the components of the keyboard extension from the X server. The
  48 .I which
  49 parameter specifies the name components to be updated in the
  50 .I xkb
  51 parameter, and is the bitwise inclusive OR of the valid names mask bits defined in Table 1.
  52
  53
  54 .TS
  55 c s s s
  56 l l l l.
  57 Table 1 Symbolic Names Masks
  58 _
  59 Mask Bit        Value   Keyboard        Field
  60                 Component
  61 _
  62 XkbKeycodesNameMask     (1<<0)  Xkb->names      keycodes
  63 XkbGeometryNameMask     (1<<1)  Xkb->names      geometry
  64 XkbSymbolsNameMask      (1<<2)  Xkb->names      symbols
  65 XkbPhysSymbolsNameMask  (1<<3)  Xkb->names      phys_symbols
  66 XkbTypesNameMask        (1<<4)  Xkb->names      type
  67 XkbCompatNameMask       (1<<5)  Xkb->names      compat
  68 XkbKeyTypeNamesMask     (1<<6)  Xkb->map        type[*].name
  69 XkbKTLevelNamesMask     (1<<7)  Xkb->map        type[*].lvl_names[*]
  70 XkbIndicatorNamesMask   (1<<8)  Xkb->names      indicators[*]
  71 XkbKeyNamesMask (1<<9)  Xkb->names      keys[*], num_keys
  72 XkbKeyAliasesMask       (1<<10) Xkb->names      key_aliases[*], num_key_aliases
  73 XkbVirtualModNamesMask  (1<<11) Xkb->names      vmods[*]
  74 XkbGroupNamesMask       (1<<12) Xkb->names      groups[*]
  75 XkbRGNamesMask  (1<<13) Xkb->names      radio_groups[*], num_rg
  76 XkbComponentNamesMask   (0x3f)  Xkb->names      keycodes,
  77                         geometry,
  78                         symbols,
  79                         physical symbols,
  80                         types, and
  81                         compatibility map
  82 XkbAllNamesMask (0x3fff)        Xkb->names      all name components
  83 .TE
  84
  85 If the
  86 .I names
  87 field of the keyboard description
  88 .I xkb
  89 is NULL,
  90 .I XkbGetNames
  91 allocates and initializes the
  92 .I names
  93 component of the keyboard description before obtaining the values specified by
  94 .I which.
  95 If the
  96 .I names field of
  97 .I xkb
  98 is not NULL,
  99 .I XkbGetNames
 100 obtains the values specified by
 101 .I which
 102 and copies them into the keyboard description
 103 .I Xkb.
 104
 105 If the
 106 .I map
 107 component of the
 108 .I xkb
 109 parameter is NULL,
 110 .I XkbGetNames
 111 does not retrieve type or shift level names, even if XkbKeyTypeNamesMask or XkbKTLevelNamesMask are set in
 112 .I which.
 113
 114 .I XkbGetNames
 115 can return Success, or BadAlloc, BadLength, BadMatch, and BadImplementation errors.
 116
 117 To free symbolic names, use
 118 .I XkbFreeNames.
 119 .SH DIAGNOSTICS
 120 .TP 15
 121 .B BadAlloc
 122 Unable to allocate storage
 123 .TP 15
 124 .B BadImplementation
 125 Invalid reply from server
 126 .TP 15
 127 .B BadLength
 128 The length of a request is shorter or longer than that required to minimally contain the arguments
 129 .TP 15
 130 .B BadMatch
 131 A compatible version of Xkb was not available in the server or an argument has correct type and range, but
 132 is otherwise invalid
 133 .SH "SEE ALSO"
 134 .BR XkbFreeNames (__libmansuffix__)
 135