man/xkb/XkbFreeDeviceInfo.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 XkbFreeDeviceInfo __libmansuffix__ __xorgversion__ "XKB FUNCTIONS"
  24 .SH NAME
  25 XkbFreeDeviceInfo \- Free an XkbDeviceInfoRec structure
  26 .SH SYNOPSIS
  27 .HP
  28 .B void XkbFreeDeviceInfo
  29 .BI "(\^XkbDeviceInfoPtr " "device_info" "\^,"
  30 .BI "unsigned int " "which" "\^,"
  31 .BI "Bool " "free_all" "\^);"
  32 .if n .ti +5n
  33 .if t .ti +.5i
  34 .SH ARGUMENTS
  35 .TP
  36 .I \- device_info
  37 pointer to XkbDeviceInfoRec in which to free items
  38 .TP
  39 .I \- which
  40 mask of components of device_info to free
  41 .TP
  42 .I \- free_all
  43 True => free everything, including device_info
  44 .SH DESCRIPTION
  45 .LP
  46 If
  47 .I free_all
  48 is True, the
  49 .I XkbFreeDeviceInfo
  50 frees all components of
  51 .I device_info
  52 and the XkbDeviceInfoRec structure pointed to by
  53 .I device_info
  54 itself. If
  55 .I free_all
  56 is False, the value of
  57 .I which
  58 determines which subcomponents are freed.
  59 .I which
  60 is an inclusive OR of one or more of the values from Table 1. If
  61 .I which
  62 contains XkbXI_ButtonActionsMask, all button actions associated with
  63 .I device_info
  64 are freed,
  65 .I device_info->btn_acts
  66 is set to NULL, and
  67 .I device_info->num_btns
  68 is set to zero. If
  69 .I which
  70 contains all bits in XkbXI_IndicatorsMask, all XkbDeviceLedInfoRec structures associated with
  71 .I device_info
  72 are freed,
  73 .I device_info->leds
  74 is set to NULL, and
  75 .I device_info->sz_leds
  76 and
  77 .I device_info->num_leds
  78 are set to zero. If
  79 .I which
  80 contains XkbXI_IndicatorMapsMask, all indicator maps associated with
  81 .I device_info
  82 are cleared, but the number of LEDs and the leds structures themselves is preserved. If
  83 .I which
  84 contains XkbXI_IndicatorNamesMask, all indicator names associated with
  85 .I device_info
  86 are cleared, but the number of LEDs and the leds structures themselves is preserved. If
  87 .I which
  88 contains XkbXI_IndicatorStateMask, the indicator state associated with the
  89 .I device_info
  90 leds are set to zeros but the number of LEDs and the leds structures themselves is preserved.
  91 .bp
  92 .nf
  93                          Table 1 XkbDeviceInfoRec Mask Bits
  94 ____________________________________________________________________________________
  95 Name                         XkbDeviceInfoRec Value     Capability If Set
  96                              Fields Effected
  97 ____________________________________________________________________________________
  98 XkbXI_KeyboardsMask                           (1L <<0) Clients can use all
  99                                                        Xkb requests and events
 100                                                        with KeyClass devices
 101                                                        supported by the input
 102                                                        device extension.
 103
 104 XkbXI_ButtonActionsMask       num_btns        (1L <<1) Clients can assign key
 105                               btn_acts                 actions to buttons
 106                                                        non-KeyClass input
 107                                                        extension devices.
 108
 109 XkbXI_IndicatorNamesMask      leds->names     (1L <<2) Clients can assign
 110                                                        names to indicators on
 111                                                        non-KeyClass input
 112                                                        extension devices.
 113
 114 XkbXI_IndicatorMapsMask       leds->maps      (1L <<3) Clients can assign
 115                                                        indicator maps to
 116                                                        indicators on
 117                                                        non-KeyClass input
 118                                                        extension devices.
 119
 120 XkbXI_IndicatorStateMask      leds->state     (1L <<4) Clients can request
 121                                                        the status of indicators
 122                                                        on non-KeyClass input
 123                                                        extension devices.
 124
 125 XkbXI_IndicatorsMask          sz_leds         (0x1c)   XkbXI_IndicatorNamesMask |
 126                               num_leds                 XkbXI_IndicatorMapsMask |
 127                               leds->*                  XkbXI_IndicatorStateMask
 128
 129 XkbXI_UnsupportedFeaturesMask unsupported     (1L <<15)
 130
 131 XkbXI_AllDeviceFeaturesMask   Those selected  (0x1e)   XkbXI_IndicatorsMask |
 132                               by Value Column          XkbSI_ButtonActionsMask
 133                               masks
 134
 135 XkbXI_AllFeaturesMask         Those selected  (0x1f)   XkbSI_AllDeviceFeaturesMask |
 136                               by Value Column          XkbSI_KeyboardsMask
 137                               masks
 138
 139 XkbXI_AllDetailsMask          Those selected  (0x801f) XkbXI_AllFeaturesMask |
 140                               by Value column          XkbXI_UnsupportedFeaturesMask
 141                               masks
 142 .fi
 143 .SH STRUCTURES
 144 .LP
 145 Information about X Input Extension devices is transferred between a client program and the Xkb
 146 extension in an XkbDeviceInfoRec structure:
 147 .nf
 148
 149 typedef struct {
 150     char *               name;          /\(** name for device */
 151     Atom                 type;          /\(** name for class of devices */
 152     unsigned short       device_spec;   /\(** device of interest */
 153     Bool                 has_own_state; /\(** True=>this device has its own state */
 154     unsigned short       supported;     /\(** bits indicating supported capabilities */
 155     unsigned short       unsupported;   /\(** bits indicating unsupported capabilities */
 156     unsigned short       num_btns;      /\(** number of entries in btn_acts */
 157     XkbAction *          btn_acts;      /\(** button actions */
 158     unsigned short       sz_leds;       /\(** total number of entries in LEDs vector */
 159     unsigned short       num_leds;      /\(** number of valid entries in LEDs vector */
 160     unsigned short       dflt_kbd_fb;   /\(** input extension ID of default (core kbd) indicator */
 161     unsigned short       dflt_led_fb;   /\(** input extension ID of default indicator feedback */
 162     XkbDeviceLedInfoPtr  leds;          /\(** LED descriptions */
 163 } XkbDeviceInfoRec, *XkbDeviceInfoPtr;
 164
 165 typedef struct {
 166     unsigned short      led_class;        /\(** class for this LED device*/
 167     unsigned short      led_id;           /\(** ID for this LED device */
 168     unsigned int        phys_indicators;  /\(** bits for which LEDs physically present */
 169     unsigned int        maps_present;     /\(** bits for which LEDs have maps in maps */
 170     unsigned int        names_present;    /\(** bits for which LEDs are in names */
 171     unsigned int        state;            /\(** 1 bit => corresponding LED is on */
 172     Atom                names[XkbNumIndicators];   /\(** names for LEDs */
 173     XkbIndicatorMapRec  maps;             /\(** indicator maps for each LED */
 174 } XkbDeviceLedInfoRec, *XkbDeviceLedInfoPtr;
 175
 176 .fi