man/XISelectEvents.man

   1 '\" t
   2 .\"     Title: xiselectevents
   3 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
   5 .\"      Date: 09/23/2011
   6 .\"    Manual: [FIXME: manual]
   7 .\"    Source: [FIXME: source]
   8 .\"  Language: English
   9 .\"
  10 .TH "XISELECTEVENTS" "libmansuffix" "09/23/2011" "[FIXME: source]" "[FIXME: manual]"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 XISelectEvents, XIGetSelectedEvents \- select for or get selected XI2 events on the window\&.
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 #include <X11/extensions/XInput2\&.h>
  36 .fi
  37 .sp
  38 .nf
  39 Status XISelectEvents( Display *display,
  40                        Window win,
  41                        XIEventMask *masks,
  42                        int num_masks);
  43 .fi
  44 .sp
  45 .nf
  46 display
  47        Specifies the connection to the X server\&.
  48 .fi
  49 .sp
  50 .nf
  51 masks
  52        Device event mask\&.
  53 .fi
  54 .sp
  55 .nf
  56 num_masks
  57        Number of masks in masks\&.
  58 .fi
  59 .sp
  60 .nf
  61 win
  62        Specifies the window\&.
  63 .fi
  64 .sp
  65 .nf
  66 XIEventMask *XIGetSelectedEvents( Display *display,
  67                                   Window win,
  68                                   int *num_masks_return);
  69 .fi
  70 .sp
  71 .nf
  72 display
  73        Specifies the connection to the X server\&.
  74 .fi
  75 .sp
  76 .nf
  77 num_masks_return
  78        Number of masks in the return value\&.
  79 .fi
  80 .sp
  81 .nf
  82 win
  83        Specifies the window\&.
  84 .fi
  85 .SH "DESCRIPTION"
  86 .sp
  87 .if n \{\
  88 .RS 4
  89 .\}
  90 .nf
  91 XI2 events must be selected using XISelectEvents\&.
  92 .fi
  93 .if n \{\
  94 .RE
  95 .\}
  96 .sp
  97 .if n \{\
  98 .RS 4
  99 .\}
 100 .nf
 101 XISelectEvents sets the event mask for this client on win\&.
 102 Further events are only reported to this client if the event
 103 type matches the selected event mask\&. The masks overrides the
 104 previously selected event mask for the given device\&.
 105 .fi
 106 .if n \{\
 107 .RE
 108 .\}
 109 .sp
 110 .if n \{\
 111 .RS 4
 112 .\}
 113 .nf
 114 If deviceid is a valid device, the event mask is selected only
 115 for this device\&. If deviceid is XIAllDevices or
 116 XIAllMasterDevices, the event mask is selected for all devices
 117 or all master devices, respectively\&. The effective event mask
 118 is the bit\-wise OR of the XIAllDevices, XIAllMasterDevices and
 119 the respective device\*(Aqs event mask\&.
 120 .fi
 121 .if n \{\
 122 .RE
 123 .\}
 124 .sp
 125 .if n \{\
 126 .RS 4
 127 .\}
 128 .nf
 129 typedef struct {
 130     int deviceid;
 131     int mask_len;
 132     unsigned char* mask;
 133 } XIEventMask;
 134 .fi
 135 .if n \{\
 136 .RE
 137 .\}
 138 .sp
 139 .if n \{\
 140 .RS 4
 141 .\}
 142 .nf
 143 The mask_len specifies the length of mask in bytes\&. mask is a
 144 binary mask in the form of (1 << event type)\&. deviceid must be
 145 either a device or XIAllDevices or XIAllMasterDevices\&. A client
 146 may submit several masks with the same deviceid in one request
 147 but only the last mask will be effective\&.
 148 .fi
 149 .if n \{\
 150 .RE
 151 .\}
 152 .sp
 153 .if n \{\
 154 .RS 4
 155 .\}
 156 .nf
 157 XISelectEvents can generate a BadValue, a BadDevice, and a
 158 BadWindow error\&.
 159 .fi
 160 .if n \{\
 161 .RE
 162 .\}
 163 .sp
 164 .if n \{\
 165 .RS 4
 166 .\}
 167 .nf
 168 XIGetSelectedEvents returns the events selected by this client on the given
 169 window\&. If no events were selected on this window, XIGetSelectedEvents
 170 returns NULL and num_masks_return is set to 0\&. If an internal error occurs,
 171 XIGetSelectedEvents returns NULL and num_masks_return is set to \-1\&.
 172 Otherwise, XIGetSelectedEvent returns the selected event masks for all
 173 devices including the masks for XIAllDevices and XIAllMasterDevices
 174 .fi
 175 .if n \{\
 176 .RE
 177 .\}
 178 .sp
 179 .if n \{\
 180 .RS 4
 181 .\}
 182 .nf
 183 The caller must free the returned data using XFree()\&.
 184 .fi
 185 .if n \{\
 186 .RE
 187 .\}
 188 .SH "DIAGNOSTICS"
 189 .sp
 190 .if n \{\
 191 .RS 4
 192 .\}
 193 .nf
 194 BadValue
 195        A value is outside of the permitted range\&.
 196 .fi
 197 .if n \{\
 198 .RE
 199 .\}
 200 .sp
 201 .if n \{\
 202 .RS 4
 203 .\}
 204 .nf
 205 BadWindow
 206        A value for a Window argument does not name a defined
 207        window\&.
 208 .fi
 209 .if n \{\
 210 .RE
 211 .\}
 212 .sp
 213 .if n \{\
 214 .RS 4
 215 .\}
 216 .nf
 217 BadDevice
 218        An invalid device was specified\&. The device does not
 219        exist\&.
 220 .fi
 221 .if n \{\
 222 .RE
 223 .\}