man/XSetDeviceFocus.man

   1 '\" t
   2 .\"     Title: xsetdevicefocus
   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 "XSETDEVICEFOCUS" "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 XSetDeviceFocus, XGetDeviceFocus \- control extension input device focus
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 #include <X11/extensions/XInput\&.h>
  36 .fi
  37 .sp
  38 .nf
  39 XSetDeviceFocus( Display *display,
  40                  XDevice *device,
  41                  Window focus,
  42                  int revert_to,
  43                  Time time);
  44 .fi
  45 .sp
  46 .nf
  47 XGetDeviceFocus( Display *display,
  48                  XDevice *device,
  49                  Window *focus_return,
  50                  int *revert_to_return,
  51                  int * time_return);
  52 .fi
  53 .sp
  54 Arguments
  55 .sp
  56 .nf
  57 display
  58        Specifies the connection to the X server\&.
  59 .fi
  60 .sp
  61 .nf
  62 device
  63        Specifies the device whose focus is to be queried or
  64        changed\&.
  65 .fi
  66 .sp
  67 .nf
  68 focus
  69        Specifies the window, PointerRoot, FollowKeyboard,or
  70        None\&.
  71 .fi
  72 .sp
  73 .nf
  74 focus_return
  75        Returns the focus window, PointerRoot, FollowKeyboard,or
  76        None\&.
  77 .fi
  78 .sp
  79 .nf
  80 revert_to
  81        Specifies where the input focus reverts to if the window
  82        becomes notviewable\&.You can pass RevertToParent,
  83        RevertToPointerRoot, RevertToFollowKeyboard,or
  84        RevertToNone\&.
  85 .fi
  86 .sp
  87 .nf
  88 revert_to_return
  89        Returns the current focus state RevertToParent,
  90        RevertToPointerRoot, RevertToFollowKeyboard,or
  91        RevertToNone\&.
  92 .fi
  93 .sp
  94 .nf
  95 time_return
  96        Returns the last_focus_time for the device\&.
  97 .fi
  98 .sp
  99 .nf
 100 time
 101        Specifies the time\&.You can pass either a timestamp or
 102        CurrentTime\&.
 103 .fi
 104 .SH "DESCRIPTION"
 105 .sp
 106 .if n \{\
 107 .RS 4
 108 .\}
 109 .nf
 110 The XSetDeviceFocus request changes the focus of the specified
 111 device and its last\-focus\-change time\&. It has no effect if the
 112 specified time is earlier than the current last\-focus\-change
 113 time or is later than the current X server time\&. Otherwise, the
 114 last\-focus\-change time is set to the specified time CurrentTime
 115 is replaced by the current X server time)\&. XSetDeviceFocus
 116 causes the X server to generate DeviceFocusIn and
 117 DeviceFocusOut events\&.
 118 .fi
 119 .if n \{\
 120 .RE
 121 .\}
 122 .sp
 123 .if n \{\
 124 .RS 4
 125 .\}
 126 .nf
 127 Depending on the focus argument, the following occurs:
 128   * If focus is None , all device events are discarded until a
 129     new focus window is set, and the revert_to argument is
 130     ignored\&.
 131   * If focus is a window, it becomes the device\*(Aqs focus window\&.
 132     If a generated device event would normally be reported to
 133     this window or one of its inferiors, the event is reported
 134     as usual\&. Otherwise, the event is reported relative to the
 135     focus window\&.
 136   * If focus is PointerRoot, the focus window is dynamically
 137     taken to be the root window of whatever screen the pointer
 138     is on at each event from the specified device\&. In this
 139     case, the revert_to argument is ignored\&.
 140   * If focus is FollowKeyboard, the focus window is dynamically
 141     taken to be the window to which the X keyboard focus is set
 142     at each input event\&.
 143 .fi
 144 .if n \{\
 145 .RE
 146 .\}
 147 .sp
 148 .if n \{\
 149 .RS 4
 150 .\}
 151 .nf
 152 The specified focus window must be viewable at the time
 153 XSetDeviceFocus is called, or a BadMatch error results\&. If the
 154 focus window later becomes not viewable, the X server evaluates
 155 the revert_to argument to determine the new focus window as
 156 follows:
 157   * If revert_to is RevertToParent, the focus reverts to the
 158     parent (or the closest viewable ancestor), and the new
 159     revert_to value is taken to be RevertToNone\&.
 160   * If revert_to is RevertToPointerRoot,
 161     RevertToFollowKeyboard, or RevertToNone, the focus reverts
 162     to PointerRoot, FollowKeyboard, or None, respectively\&.
 163 .fi
 164 .if n \{\
 165 .RE
 166 .\}
 167 .sp
 168 .if n \{\
 169 .RS 4
 170 .\}
 171 .nf
 172 When the focus reverts, the X server generates DeviceFocusIn
 173 and DeviceFocusOut events, but the last\-focus\-change time is
 174 not affected\&.
 175 .fi
 176 .if n \{\
 177 .RE
 178 .\}
 179 .sp
 180 .if n \{\
 181 .RS 4
 182 .\}
 183 .nf
 184 Input extension devices are not required to support the ability
 185 to be focused\&. Attempting to set the focus of a device that
 186 does not support this request will result in a BadMatch error\&.
 187 Whether or not given device can support this request can be
 188 determined by the information returned by XOpenDevice\&. For
 189 those devices that support focus, XOpenDevice will return an
 190 XInputClassInfo structure with the input_class field equal to
 191 the constant FocusClass (defined in the file XI\&.h)\&.
 192 .fi
 193 .if n \{\
 194 .RE
 195 .\}
 196 .sp
 197 .if n \{\
 198 .RS 4
 199 .\}
 200 .nf
 201 XSetDeviceFocus can generate BadDevice, BadMatch, BadValue, and
 202 BadWindow errors\&.
 203 .fi
 204 .if n \{\
 205 .RE
 206 .\}
 207 .sp
 208 .if n \{\
 209 .RS 4
 210 .\}
 211 .nf
 212 The XGetDeviceFocus request returns the focus window and the
 213 current focus state\&.
 214 .fi
 215 .if n \{\
 216 .RE
 217 .\}
 218 .sp
 219 .if n \{\
 220 .RS 4
 221 .\}
 222 .nf
 223 Not all input extension devices can be focused\&. Attempting to
 224 query the focus state of a device that can\*(Aqt be focused results
 225 in a BadMatch error\&. A device that can be focused returns
 226 information for input Class Focus when an XOpenDevice request
 227 is made\&.
 228 .fi
 229 .if n \{\
 230 .RE
 231 .\}
 232 .sp
 233 .if n \{\
 234 .RS 4
 235 .\}
 236 .nf
 237 XGetDeviceFocus can generate BadDevice, and BadMatch errors\&.
 238 .fi
 239 .if n \{\
 240 .RE
 241 .\}
 242 .SH "DIAGNOSTICS"
 243 .sp
 244 .if n \{\
 245 .RS 4
 246 .\}
 247 .nf
 248 BadDevice
 249        An invalid device was specified\&. The specified device
 250        does not exist or has not been opened by this client via
 251        XOpenInputDevice\&. This error may also occur if the
 252        specified device is the X keyboard or X pointer device\&.
 253 .fi
 254 .if n \{\
 255 .RE
 256 .\}
 257 .sp
 258 .if n \{\
 259 .RS 4
 260 .\}
 261 .nf
 262 BadValue
 263        Some numeric value falls outside the range of values
 264        accepted by the request\&. Unless a specific range is
 265        specified for an argument, the full range defined by the
 266        argument\*(Aqs type is accepted\&. Any argument defined as a
 267        set of alternatives can generate this error\&.
 268 .fi
 269 .if n \{\
 270 .RE
 271 .\}
 272 .sp
 273 .if n \{\
 274 .RS 4
 275 .\}
 276 .nf
 277 BadWindow
 278        A value for a Window argument does not name a defined
 279        Window\&.
 280 .fi
 281 .if n \{\
 282 .RE
 283 .\}
 284 .sp
 285 .if n \{\
 286 .RS 4
 287 .\}
 288 .nf
 289 BadMatch
 290        This error may occur if an XGetDeviceFocus or
 291        XSetDeviceFocus request was made specifying a device
 292        that the server implementation does not allow to be
 293        focused\&.
 294 .fi
 295 .if n \{\
 296 .RE
 297 .\}