From 3017a5124fe98eb0d1f0e4d0bdce35df06ea751b Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Thu, 14 May 2009 16:26:17 +1000 Subject: Update man pages for XI2. Shuffling device properties up before all XI2 calls and adding all XI2 calls (bar device property calls). Needs proofreading. --- man/Makefile.am | 33 +- man/XI.xml | 2539 ++++++++++++++++++++++++++++++++++--------------------- 2 files changed, 1576 insertions(+), 996 deletions(-) (limited to 'man') diff --git a/man/Makefile.am b/man/Makefile.am index 0942146..8b40787 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -30,6 +30,26 @@ LIB_MAN_DIR_SUFFIX = $(LIB_MAN_DIR:@mandir@/man%=%) libman_xml = XI.xml +XI2_manpages= \ + XIQueryPointer.man \ + XIWarpPointer.man \ + XIDefineCursor.man \ + XIUndefineCursor.man \ + XIChangeHierarchy.man \ + XISelectEvents.man \ + XISetClientPointer.man \ + XIGetClientPointer.man \ + XIQueryVersion.man \ + XISetFocus.man \ + XIGetFocus.man \ + XIGrabDevice.man \ + XIGrabButton.man \ + XIGrabKeysym.man \ + XIUngrabDevice.man \ + XIUngrabButton.man \ + XIUngrabKeysym.man + + libman_PRE = \ XAllowDeviceEvents.man \ XChangeKeyboardDevice.man \ @@ -41,10 +61,6 @@ libman_PRE = \ XSetDeviceValuators.man \ XChangeDeviceDontPropagateList.man \ XGetDeviceDontPropagateList.man \ - XChangeDeviceHierarchy.man \ - XDefineDeviceCursor.man \ - XUndefineDeviceCursor.man \ - XExtendedGrabDevice.man \ XGetDeviceControl.man \ XChangeDeviceControl.man \ XGetDeviceKeyMapping.man \ @@ -61,27 +77,22 @@ libman_PRE = \ XUngrabDeviceKey.man \ XGrabDevice.man \ XUngrabDevice.man \ - XiSelectEvent.man \ XListInputDevices.man \ XFreeDeviceList.man \ XOpenDevice.man \ XCloseDevice.man \ - XQueryDevicePointer.man \ - XQueryInputVersion.man \ XGetExtensionVersion.man \ XSelectExtensionEvent.man \ XGetSelectedExtensionEvents.man \ - XSetClientPointer.man \ - XGetClientPointer.man \ XSetDeviceButtonMapping.man \ XGetDeviceButtonMapping.man \ XSetDeviceFocus.man \ XGetDeviceFocus.man \ - XWarpDevicePointer.man \ XListDeviceProperties.man \ XGetDeviceProperty.man \ XChangeDeviceProperty.man \ - XDeleteDeviceProperty.man + XDeleteDeviceProperty.man \ + $(XI2_manpages) EXTRA_DIST = $(libman_PRE) $(libman_xml) xi.stamp diff --git a/man/XI.xml b/man/XI.xml index a8f1af4..f93bb71 100644 --- a/man/XI.xml +++ b/man/XI.xml @@ -14,6 +14,7 @@ Copyright © 2008 Peter Hutterer + Copyright © 2009 Red Hat, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), @@ -34,8 +35,7 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - Author: Peter Hutterer, UniSA, NICTA - + Author: Peter Hutterer --> X Input Extension Library @@ -4471,138 +4471,11 @@ - - - - __vendorversion__ - February 14, 2008 - - - PeterHutterer - Specification and implementation. - - - - - - XSetClientPointer, XGetClientPointer - __libmansuffix__ - __xorgversion__ - XINPUT FUNCTIONS - - - XSetClientPointer - XGetClientPointer - set or get the ClientPointer setting. - - - Syntax - - #include <X11/extensions/XInput.h> - - XSetClientPointer - Display *display - Window win - XDevice *device - - - Bool XGetClientPointer - Display *display - Window win - XID *device - - - - - Arguments - - - - display - Specifies the connection to the X server. - - - - win - Specifies a window belonging to the - client. May be None. - - - - device - Specifies the device to set as - ClientPointer. - - - - - - - Description - - The ClientPointer is the device that is percieved to be the core - pointer for non-XI protocol requests and replies. Each time a - protocol message needs device-dependent data and the device is - not explicitly given, the ClientPointer device is used to obtain - the data. For example, a XQueryPointer - request will return the coordinates of the ClientPointer. - - - XSetClientPointer request sets the - ClientPointer device for the client that owns the given window. If - win is None, the - requesting client's ClientPointer is set to the - device. Only master pointer devices can be - set as ClientPointer. - - - XSetClientPointer and can generate a - BadDevice and a - BadWindow error. - - - The XGetClientPointer request returns the - ClientPointer's device ID for the client that owns the given - window. If win is - None, the requesting client's ClientPointer - is returned. - - - win may be a client ID instead - of a window. - - - XGetClientPointer can generate a - BadWindow error. - - - - Diagnosis - - - - BadDevice - - An invalid device was specified. The device does - not exist or is not a master pointer device. - - - - - BadWindow - A value for a Window argument does not - name a defined window. - - - - - - - - + + __vendorversion__ - February 14, 2008 + July 9, 2008 PeterHutterer @@ -4612,31 +4485,24 @@ - XQueryDevicePointer + XListDeviceProperties __libmansuffix__ __xorgversion__ XINPUT FUNCTIONS - + - XQueryDevicePointer - get device pointer coordinates. + XListDeviceProperties + List a device's properties. Syntax #include <X11/extensions/XInput.h> - Bool XQueryDevicePointer + Atom* XListDeviceProperties Display *display XDevice *device - Window win - Window *root_return - Window *child_return - int *root_x_return - int *root_y_return - int *win_x_return - int *win_y_return - unsigned int *mask_return + int *nprops_return @@ -4644,112 +4510,45 @@ Arguments - - child_return - - - Returns the child window that the pointer is - located in, if any. - - - - - device - Specifies the device to query. - - display - Specifies the connection to the X server. - - - - mask_return - - - Returns the current state of the modifier keys and - pointer buttons. - - + Specifies the connection to the X server. - root_return - - - Returns the root window that the pointer is in. - - + device + The device to grab. - root_x_return - root_y_return - - - Return the pointer coordinates relative to the root - window's origin. - - - + nprops_return + Specifies the number of Atoms returned. + - win - - - Specifies the window. - - - + num_values + Specifies the number of elements in the + values list. + - win_x_return - win_y_return - - Return the pointer coordinates relative to the - specified window. - - - + property + Specifies the property to modify or query. + Description - The XQueryDevicePointer function returns the root - window the device's pointer is logically on and the pointer - coordinates relative to the root window's origin. If - XQueryDevicePointer returns - False, the pointer is not on the same screen as - the specified window, and - XQueryDevicePointer returns - None to child_return and - zero to win_x_return and - win_y_return. If - XQueryDevicePointer returns - True, the pointer coordinates returned to - win_x_return and - win_y_return are relative to the origin of the - specified window. In this case, - XQueryDevicePointer returns the child that - contains the pointer, if any, or else None to - child_return. - - - XQueryDevicePointer returns the current - logical state of the keyboard buttons and the modifier keys in - mask_return. The keyboard paired with the - master pointer is selected to obtain this data. It sets - mask_return to the bitwise inclusive OR of - one or more of the button or modifier key bitmasks to match the - current state of the mouse buttons and the modifier keys. - - - XQueryDevicePointer is identical to - XQueryPointer but specifies the device - explicitly. + The XListDeviceProperties function returns a + list of the properties associated with the input device specified + in device. + Each device may have an arbitrary number of properties attached, + some of which were created by the driver and/or server, others + created by clients at runtime. + The client is expected to free the list of properties using + XFree. - XQueryDevicePointer can generate a - BadDevice and a - BadWindow error. + XListDeviceProperties can generate a + BadDevice error. @@ -4757,35 +4556,39 @@ - BadDevice - - - An invalid device was specified. The device does - not exist or is not a pointer device. - - + BadAtom + A value does not describe a valid named + identifier. BadWindow A value for a Window argument does not name a defined window. + + + + BadDevice + An invalid device was specified. The + device does not exist. + See also - XQueryPointer + XChangeDeviceProperty, + XGetDeviceProperty, + XDeleteDeviceProperty. - - + __vendorversion__ - February 14, 2008 + July 9, 2008 PeterHutterer @@ -4795,32 +4598,53 @@ - XDefineDeviceCursor, XUndefineDeviceCursor + XGetDeviceProperty __libmansuffix__ __xorgversion__ XINPUT FUNCTIONS - + - XDefineDeviceCursor - XUndefineDeviceCursor - define device cursors. + XGetDeviceProperty + XChangeDeviceProperty + XDeleteDeviceProperty + Get, change or delete a device's property. Syntax #include <X11/extensions/XInput.h> - int XDefineCursor + int XGetDeviceProperty Display *display XDevice *device - Window win - Cursor cursor + Atom property + long offset + long length + Bool delete + Bool pending + Atom req_type + Atom *actual_type_return + int *actual_format_return + unsigned long *nitems_return + unsigned long *bytes_after_return + unsigned char **prop_return - int XUndefineCursor + void XChangeDeviceProperty Display *display XDevice *device - Window win + Atom property + Atom type + int format + int mode + const char *data + int nelements + + + void XDeleteDeviceProperty + Display *display + XDevice *device + Atom property @@ -4829,63 +4653,158 @@ - cursor - - Specifies the cursor that is to be displayed or - None. - - - + actual_type_return + Returns an atom identifier that defines + the actual type of the property. + - device - Specifies the device whose cursor is to - change. + actual_format_return + Returns the actual format of the property. + + + bytes_after_return + Returns the number of bytes remaining to + be read in the property if a partial read was + performed. + + + data + Specifies the property data. + + + delete + Specifies a Boolean value that determines + wether the property is deleted. display - Specifies the connection to the X server. - + Specifies the connection to the X server. - win - Specifies the window. + device + The device to grab. + + + format + Specifies whether the data should be + viewed as a list of 8-bit, 16-bit, or 32-bit + quantities. Possible values are 8, 16, and 32. + This information allows the X server to correctly + perform byte-swap operations as necessary. If the + format is 16-bit or 32-bit, you must explicitly + cast the data pointer to an (unsigned char*) in + the call to + XChangeDeviceProperty. + + length + Specifies the length in 32-bit multiplies + of the data to be retrieved. + + + mode + Specifies the mode of operation. You can + pass PropModeReplace, + PropModePrepend, or + PropModeAppend. + + + + nelements + Specifies the number of elements in data. + + + nitems_return + Returns the actual number of 8-bit, + 16-bit, or 32-bit items stored in the prop_return + array. + + + num_values + Specifies the number of elements in the + values list. + + + offset + Specifies the offset in the specified + property (in 32-bit quantities) where the data is + to be retrieved. + + + pending + Specifies whether to retrieve the pending + state of the property or the current state. + + + property + Specifies the property to modify or query. + + + prop_return + Returns the data in the specified format. + If the returned format is 8, the returned data is + represented as a char array. If the returned + format is 16, the returned data is represented as + an array of short int type and should be cast to + that type to obtain the elements. If the returned + format is 32, the property data will be stored as + an array of longs (which in a 64-bit application + will be 64-bit values that are padded in the upper + 4 bytes). + + + + req_type + Specifies the atom identifier associated + with the property type or + AnyPropertyType. + Description - If a cursor is set, it will be used when the device's pointer is in the - window. If the cursor is None, it is equivalent to - XUndefineDefineCursor. + The XGetDeviceProperty function returns + the actual type of the property; the actual format of the property; + the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes + remaining to be read in the property; and a pointer to the data actually + returned. + For a detailed description of this function, see the man page + to XGetWindowProperty. + + The XChangeDeviceProperty function alters the + property for the specified device and causes the server to + generate a XPropertyNotifyEvent event on that + device. + For a detailed description of this function, see the man page to + XChangeProperty. + - XDefineDeviceCursor can generate - BadCursor and - BadWindow. + The XDeleteDeviceProperty function + deletes the specified device property. Note that a client cannot + delete a property created by a driver or the server. Attempting to + do so will result in a BadAtom error. - The XUndefineDeviceCursor function undoes the - effect of a previous XDefineDeviceCursor for - this window. When the pointer is in the window, the window's - default cursor will now be used. If no default cursor is defined, - the parent's cursor for this device will be used (if defined) or - the parent's default cursor will be used. + XGetDeviceProperty can generate a + BadAtom, + BadDevice error. - XDefineDeviceCursor and - XUndefineDeviceCursor are identical to - XDefineCursor and - XUndefineCursor but specify the device - explicitly. + XChangeDeviceProperty can generate a + BadDevice, a + BadMatch, a + BadAtom, and a + BadValue error. - XUndefineDevicePointer can generate a - BadDevice and a - BadWindow error. + XDeleteDeviceProperty can generate a + BadDevice, and a + BadAtom error. @@ -4893,97 +4812,223 @@ - BadDevice - An invalid device was specified. The - device does not exist or is not a pointer - device. - - + BadAtom + A value does not describe a valid named + identifier or the client attempted to remove + a driver-allocated property. - BadWindow - A value for a Window argument does not - name a defined window. - + BadDevice + An invalid device was specified. The + device does not exist. + - See also + + See also - XDefineCursor, - XUndefineCursor + XListDeviceProperties, + XQueryDeviceProperty, + XConfigureDeviceProperty. + + + + __vendorversion__ + February 14, 2008 + + + PeterHutterer + Specification and implementation. + + + - - - __vendorversion__ - February 14, 2008 - - - PeterHutterer - Specification and implementation. - - - - - - XWarpDevicePointer + + XISetClientPointer, XIGetClientPointer __libmansuffix__ __xorgversion__ XINPUT FUNCTIONS - + - XWarpDevicePointer - move device pointer. + XISetClientPointer + XIGetClientPointer + set or get the ClientPointer device. - Syntax - - #include <X11/extensions/XInput.h> - - Bool XWarpDevicePointer - Display *display - XDevice *device - Window src_w - Window dest_w - int src_x - int src_y - int src_width - int src_height - int dest_x - int dest_y - - - + Syntax + + #include <X11/extensions/XInput2.h> + + XISetClientPointer + Display *display + Window win + int deviceid + + + Bool XIGetClientPointer + Display *display + Window win + int *device + + + + + Arguments + + + + display + Specifies the connection to the X server. + + + + win + Specifies a window belonging to the + client. May be None. + + + + deviceid + Specifies the ClientPointer device. + + + + + + + Description + + The ClientPointer is the device that is percieved to be the core + pointer for non-XI protocol requests and replies. Each time a + protocol message needs device-dependent data and the device is + not explicitly given, the ClientPointer device is used to obtain + the data. For example, a XQueryPointer + request will return the coordinates of the ClientPointer. + + + XISetClientPointer request sets the + ClientPointer device for the client that owns the given window. If + win is None, the + requesting client's ClientPointer is set to the device specified + with deviceid. Only master pointer devices can be + set as ClientPointer. + + + XISetClientPointer and can generate a + BadDevice and a + BadWindow error. + + + The XIGetClientPointer request returns the + ClientPointer's device ID for the client that owns the given + window. If win is + None, the requesting client's ClientPointer + is returned. + + + win may be a client ID instead + of a window. + + + XIGetClientPointer can generate a + BadWindow error. + + + + Diagnosis + + + + BadDevice + + An invalid device was specified. The device does + not exist or is not a master pointer device. + + + + + BadWindow + A value for a Window argument does not + name a defined window. + + + + + + + + + + __vendorversion__ + February 14, 2008 + + + PeterHutterer + Specification and implementation. + + + + + + XIQueryPointer + __libmansuffix__ + __xorgversion__ + XINPUT FUNCTIONS + + + XIQueryPointer + get device pointer coordinates. + + + Syntax + + #include <X11/extensions/XInput2.h> + + Bool XIQueryPointer + Display *display + int deviceid + Window win + Window *root_return + Window *child_return + int *root_x_return + int *root_y_return + int *win_x_return + int *win_y_return + XIModifierState *modifiers_return + XIGroupState *group_return + XIButtonState *buttons_return + + + Arguments - dest_w + buttons_return - Specifies the destination window or - None. + Returns the current button state. - dest_x - dest_y + child_return - Specify the x and y coordinates within the - destination window. + Returns the child window that the pointer is + located in, if any. - device - Specifies the device to move. + deviceid + Specifies the device to query. @@ -4992,22 +5037,53 @@ - src_x - src_y - src_width - src_height + group_return - Specify a rectangle in the source window. + Returns the current group state. - src_w + modifiers_return - Specifies the source window or - None. + Returns the current state of the modifier keys. + + + + + root_return + + + Returns the root window that the pointer is in. + + + + + root_x_return + root_y_return + + + Return the pointer coordinates relative to the root + window's origin. + + + + + win + + + Specifies the window. + + + + + win_x_return + win_y_return + + Return the pointer coordinates relative to the + specified window. @@ -5017,48 +5093,40 @@ Description - If dest_w is None, - XWarpDevicePointer moves the pointer by the - offsets (dest_x, - dest_y) relative to the current position - of the pointer. If - dest_w is a window, - XWarpDevicePointer moves the pointer to the - offsets - (dest_x, dest_y) - relative to the origin of dest_w. - However, if src_w is a window, the move - only takes place if the window src_w - contains the pointer and if the specified rectangle of - src_w contains the pointer. - - - The src_x and src_y - coordinates are relative to the origin of - src_w. If - src_height is zero, it is replaced with the - current height of src_w minus - src_y. If src_width - is zero, it is replaced with the current width of - src_w minus src_x. + The XIQueryPointer function returns the root + window the device's pointer is logically on and the pointer + coordinates relative to the root window's origin. If + XIQueryPointer returns + False, the pointer is not on the same screen as + the specified window, and + XIQueryPointer returns + None to child_return and + zero to win_x_return and + win_y_return. If + XIQueryPointer returns + True, the pointer coordinates returned to + win_x_return and + win_y_return are relative to the origin of the + specified window. In this case, + XIQueryPointer returns the child that + contains the pointer, if any, or else None to + child_return. - There is seldom any reason for calling this function. The pointer - should normally be left to the user. If you do use this function, - however, it generates events just as if the user had - instantaneously moved the pointer from one position to another. - Note that you cannot use XWarpDevicePointer - to move the pointer outside the confine_to window of an active - pointer grab. An attempt to do so will only move the pointer as - far as the closest edge of the confine_to window. + XIQueryPointer returns the current + logical state of the buttons + buttons_return. The keyboard paired with + the master pointer is selected to obtain the data for + modifiers_return and + group_return. - XWarpDevicePointer is identical to - XWarpPointer but specifies the device + XIQueryPointer is identical to + XQueryPointer but specifies the device explicitly. - XWarpDevicePointer can generate a + XIQueryPointer can generate a BadDevice and a BadWindow error. @@ -5069,26 +5137,31 @@ BadDevice - An invalid device was specified. The - device does not exist or is not a pointer - device. - + + + An invalid device was specified. The device does + not exist or is not a pointer device. + + BadWindow A value for a Window argument does not name a defined window. - + See also - XWarpPointer + + XQueryPointer + + - + __vendorversion__ February 14, 2008 @@ -5101,24 +5174,32 @@ - XChangeDeviceHierarchy + XIDefineCursor, XIUndefineCursor __libmansuffix__ __xorgversion__ XINPUT FUNCTIONS - XChangeDeviceHierarchy - change the device hierarchy. + XIDefineCursor + XIUndefineCursor + define device cursors. Syntax - #include <X11/extensions/XInput.h> + #include <X11/extensions/XInput2.h> - Status XChangeDeviceHierarchy + int XDefineCursor Display *display - XAnyHierarchyChangeInfo *changes - int num_changes + int deviceid + Window win + Cursor cursor + + + int XUndefineCursor + Display *display + int deviceid + Window win @@ -5127,25 +5208,28 @@ - display - Specifies the connection to the X server. - - - - num_changes - + cursor - Specifies the number of elements in changes. + Specifies the cursor that is to be displayed or + None. - changes - - - Specifies the changes to be made. - - + deviceid + Specifies the device whose cursor is to + change. + + + + display + Specifies the connection to the X server. + + + + win + Specifies the window. + @@ -5153,144 +5237,66 @@ Description - XChangeDeviceHierarchy modifies the device - hierarchy by creating or removing master devices or changing the - attachment of slave devices. If num_changes - is non-zero, changes is an array of - XAnyHierarchyChangeInfo structures. - - - XChangeDeviceHierarchy processes - changes in order, effective immediately. If - an error occurs, processing is aborted and the error is reported - to the client. Changes already made remain effective. - - - The list of changes is any combination of - XAnyHierarchyChangeInfo. The - type of a hierarchy change can be - CH_CreateMasterDevice, - CH_RemoveMasterDevice or - CH_ChangeAttachment. - - - - typedef union { - int type; - XCreateMasterInfo create; - XRemoveMasterInfo remove; - XChangeAttachmentInfo change; - } XAnyHierarchyChangeInfo; - - - - - typedef struct { - int type; /* CH_CreateMasterDevice */ - char* name; - Bool sendCore; - Bool enable; - } XCreateMasterInfo; - - - - - typedef struct { - int type; /* CH_RemoveMasterDevice */ - XDevice* device; - int returnMode; - XDevice* returnPointer; - XDevice* returnKeyboard; - } XRemoveMasterInfo; - - - - - typedef struct { - int type; /* CH_ChangeAttachment */ - XDevice* device; - int changeMode; - XDevice* newMaster; - } XChangeAttachmentInfo; - - - - XCreateMasterInfo creates a new master - pointer and a new master keyboard labelled - "name pointer" and - "name keyboard" respectively. - If sendCore is - True, the devices will send core events. If - enable is True, - the device is enabled immediately. - - - XCreateMasterInfo can generate a - BadValue error. + If a cursor is set, it will be used when the device's pointer is in the + window. If the cursor is None, it is equivalent to + XUndefineDefineCursor. - XRemoveMasterInfo removes - device and its paired master device. If - returnMode is - AttachToMaster, all pointers attached to - device or its paired master device are - attached to returnPointer. Likewise, - all keyboards are attached to - returnKeyboard. If - returnMode is - Floating, all attached devices are set to - floating. + XIDefineCursor can generate + BadCursor and + BadWindow. - XRemoveMasterInfo can generate a - BadValue and a - BadDevice error. + The XIUndefineCursor function undoes the + effect of a previous XIDefineCursor for + this window. When the pointer is in the window, the window's + default cursor will now be used. If no default cursor is defined, + the parent's cursor for this device will be used (if defined) or + the parent's default cursor will be used. - XChangeAttachmentInfo changes the - attachment of device to - newMaster if - changeMode is - AttachToMaster. Otherwise, if - changeMode is - Floating, device - is set floating. + XIDefineCursor and + XIUndefineCursor are identical to + XDefineCursor and + XUndefineCursor but specify the device + explicitly. - XChangeAttachmentInfo can generate a + XUndefineDevicePointer can generate a BadDevice and a - BadValue error. + BadWindow error. - Diagnosis BadDevice - - - An invalid device was specified. The device does - not exist or is not a appropriate for the type of - change. - - + An invalid device was specified. The + device does not exist or is not a pointer + device. + + - BadValue - - - Some numeric value falls out of the allowed range. - - + BadWindow + A value for a Window argument does not + name a defined window. + + See also + + XDefineCursor, + XUndefineCursor + + - + __vendorversion__ February 14, 2008 @@ -5303,25 +5309,31 @@ - XiSelectEvent + XIWarpPointer __libmansuffix__ __xorgversion__ XINPUT FUNCTIONS - XiSelectEvent - select for generic events on the window. + XIWarpPointer + move a device's pointer. Syntax - #include <X11/extensions/XInput.h> + #include <X11/extensions/XInput2.h> - Status XiSelectEvent + Bool XIWarpPointer Display *display - Window win - XDevice *device - Mask mask + int deviceid + Window src_w + Window dest_w + int src_x + int src_y + int src_width + int src_height + int dest_x + int dest_y @@ -5330,27 +5342,52 @@ - display - Specifies the connection to the X server. - + dest_w + + + Specifies the destination window or + None. + + - device - The device to select - mask for. May be - NULL. - + dest_x + dest_y + + + Specify the x and y coordinates within the + destination window. + + - mask - Generic event mask. - + deviceid + Specifies the master pointer device or + floating slave device to move. + - win + display + Specifies the connection to the X server. + + + + src_x + src_y + src_width + src_height - Specifies the window. + Specify a rectangle in the source window. + + + + + src_w + + + Specifies the source window or + None. @@ -5360,37 +5397,49 @@ Description - Events available through the X Generic Event extension (XGE) - cannot be selected with XSelectExtensionEvent. - For these events, XiSelectEvent must be used. + If dest_w is None, + XIWarpPointer moves the pointer by the + offsets (dest_x, + dest_y) relative to the current position + of the pointer. If + dest_w is a window, + XIWarpPointer moves the pointer to the + offsets + (dest_x, dest_y) + relative to the origin of dest_w. + However, if src_w is a window, the move + only takes place if the window src_w + contains the pointer and if the specified rectangle of + src_w contains the pointer. - XiSelectEvent causes the X server to report - the events defined by mask on - win. The mask - overrides the previously selected event mask. A - mask of zero de-registers - win from any generic - events. + The src_x and src_y + coordinates are relative to the origin of + src_w. If + src_height is zero, it is replaced with the + current height of src_w minus + src_y. If src_width + is zero, it is replaced with the current width of + src_w minus src_x. - If device is a valid device, the event mask - is selected only for this device. If - device is NULL, the - event mask is selected for all devices. + There is seldom any reason for calling this function. The pointer + should normally be left to the user. If you do use this function, + however, it generates events just as if the user had + instantaneously moved the pointer from one position to another. + Note that you cannot use XIWarpPointer + to move the pointer outside the confine_to window of an active + pointer grab. An attempt to do so will only move the pointer as + far as the closest edge of the confine_to window. - A mask set for a device is stored - seperately for the mask for all devices. Thus, if a mask is set - for all devices, it cannot be unset for a single device. It has to - be unset for all devices first by supplying - NULL and then re-set one-by-one for all - devices. + XIWarpPointer is identical to + XWarpPointer but specifies the device + explicitly. - XiSelectEvent can generate a - BadValue, a - BadDevice, and a + XIWarpPointer can generate a + BadDevice and a BadWindow error. @@ -5399,33 +5448,27 @@ - BadValue - A value is outside of the permitted range. - + BadDevice + An invalid device was specified. The + device does not exist or is not a pointer + device. + BadWindow A value for a Window argument does not name a defined window. - - - - BadDevice - An invalid device was specified. The - device does not exist. - + See also - - XSelectExtensionEvent - + XWarpPointer - + __vendorversion__ February 14, 2008 @@ -5438,32 +5481,24 @@ - XExtendedGrabDevice + XIChangeHierarchy __libmansuffix__ __xorgversion__ XINPUT FUNCTIONS - XExtendedGrabDevice - actively grab the device. + XIChangeHierarchy + change the device hierarchy. Syntax - #include <X11/extensions/XInput.h> + #include <X11/extensions/XInput2.h> - Status XExtendedGrabDevice + Status XIChangeHierarchy Display *display - XDevice *device - Window grab_window - int device_mode - Bool owner_events - Window confine_to - Cursor cursor - int event_count - XEventClass *event_list - int generic_event_count - XGenericEventMask *generic_events + XIAnyHierarchyChangeInfo *changes + int num_changes @@ -5471,168 +5506,160 @@ Arguments - - confine_to - Specifies the window to confine the pointer - in or None. - - - - cursor - Specifies the cursor that is to be - displayed during the grab or None. - - display Specifies the connection to the X server. - + - device - The device to grab. - - - - device_mode - Specifies further processing of device - events. You can pass GrabModeSync or - GrabModeAsync. - - - - event_count - Specifies the number of elements in the event_list array. - - - - event_list - Specifies a pointer to a list of event - classes that indicates which events the client wishes to receive. These event - classes must have been obtained specifying the device being grabbed. - - - - generic_event_count - Specifies the number of elements in the generic_event_list array. - - - - generic_event_list - Specifies a pointer to a list of generic event masks - that indicates which generic events the client wishes to receive. - - - - grab_window - Specifies the grab window. - + num_changes + + + Specifies the number of elements in changes. + + - time - Specifies the time. You can pass either a timestamp or CurrentTime. - + changes + + + Specifies the changes to be made. + + - - owner_events - Specifies a Boolean value that indicates - whether the pointer events are to be reported as usual or reported with respect - to the grab window if selected by the event mask. - - Description - The XExtendedGrabDevice request actively grabs control - of the device and generates DeviceFocusIn and - DeviceFocusOut events if the device is a keyboard and - DeviceEnterNotify and - DeviceLeaveNotify if the device is a pointer. Further - device events are reported only to the grabbing client. - XExtendedGrabDevice overrides any active device grab by - this client.event_list is a pointer to a list of event - classes. This list indicates which events the client wishes to receive - while the grab is active. generic_event_list is - a pointer to a list of generic event masks. These masks indicates which generic - events the client wishes to receive while the grab is active. - If owner_events is False, all generated device - events are reported with respect to grab_window if selected. If owner_events - is True and if a generated device event would normally be reported - to this client, it is reported normally; otherwise, the event is - reported with respect to the grab_window, and is only reported if specified in - the event_list or generic_event_list. + XIChangeHierarchy modifies the device + hierarchy by creating or removing master devices or changing the + attachment of slave devices. If num_changes + is non-zero, changes is an array of + XIAnyHierarchyChangeInfo structures. - - If the device_mode argument is - GrabModeAsync, device event processing continues as - usual. If the device is currently frozen by this client, then processing of - device events is resumed. If the device_mode - argument is GrabModeSync, the state of the device (as - seen by client applications) appears to freeze, and the X server generates no - further device events until the grabbing client issues a releasing - XAllowDeviceEvents call or until the device grab is - released. Actual device changes are not lost while the device is frozen; they - are simply queued in the server for later processing. - - If a cursor is specified and the device is a master pointer, it is - displayed regardless of what window the device's pointer is in. - If None is specified, the normal cursor for that window is - displayed when the pointer is in grab_window or one of its - subwindows; otherwise, the cursor for grab_window is displayed. - - - If a confine_to window is specified and the device is a master - pointer, the device's pointer is restricted to stay contained in - that window. The confine_to window need have no - relationship to the grab_window. If the - pointer is not initially in the confine_to - window, it is warped automatically to the closest edge just before - the grab activates and enter/leave events are generated as usual. - If the confine_to window is subsequently - reconfigured, the pointer is warped automatically, as - necessary, to keep it contained in the window. - - - The time argument allows you to avoid - certain circumstances that come up if applications take a long - time to respond or if there are long network delays. Consider a - situation where you have two applications, both of which normally - grab the pointer when clicked on. If both applications specify - the timestamp from the event, the second application may wake up - faster and successfully grab the pointer before the first - application. The first application then will get an indication - that the other application grabbed the pointer before its request - was processed. - - - If the device is actively grabbed by some other client, - XExtendedGrabDevice fails and returns - AlreadyGrabbed. If - grab_window is not viewable, it fails and - returns GrabNotViewable. If the device is - frozen by an active grab of another client, it fails and returns - GrabFrozen. If the specified time is earlier - than the last-device-grab time or later than the current X server - time, it fails and returns GrabInvalidTime. - Otherwise, the last-device-grab time is set to the specified time - (CurrentTime is replaced by the current X - server time). + XIChangeHierarchy processes + changes in order, effective immediately. If + an error occurs, processing is aborted and the error is reported + to the client. Changes already made remain effective. - XExtendedGrabDevice is mostly identical to - XGrabPointer and - XGrabDevice but enables a client to register - for generic event masks. + The list of changes is any combination of + XIAnyHierarchyChangeInfo. The + type of a hierarchy change can be + XICreateMaster, + XIRemoveMaster, + XIAttachSlave or + XIDetachSlave. - XExtendedGrabDevice can generate a - BadValue, a - BadDevice, and a - BadWindow error. + + typedef union { + int type; + XICreateMasterInfo create; + XIRemoveMasterInfo remove; + XIAttachSlave attach; + XIDetachSlave detach; + } XIAnyHierarchyChangeInfo; + + + + + typedef struct { + int type; /* XICreateMaster */ + char* name; + Bool sendCore; + Bool enable; + } XICreateMasterInfo; + + + + + typedef struct { + int type; /* XIRemoveMaster */ + int device; + int returnMode; + XDevice* returnPointer; + XDevice* returnKeyboard; + } XIRemoveMasterInfo; + + + + + typedef struct { + int type; /* XIAttachSlave */ + int device; + int newMaster; + } XIAttachSlaveInfo; + + + + + typedef struct { + int type; /* XIDetachSlave */ + int device; + } XIDetachSlaveInfo; + + + + XICreateMasterInfo creates a new master + pointer and a new master keyboard labelled + "name pointer" and + "name keyboard" respectively. + If sendCore is + True, the devices will send core events. If + enable is True, + the device is enabled immediately. + + + XICreateMasterInfo can generate a + BadValue error. + + + XIRemoveMasterInfo removes + device and its paired master device. If + returnMode is + XIAttachToMaster, all pointers attached to + device or its paired master device are + attached to returnPointer. Likewise, + all keyboards are attached to + returnKeyboard. If + returnMode is + XIFloating, all attached devices are set to + floating. + + + XIRemoveMasterInfo can generate a + BadValue and a + BadDevice error. + + + XIAttachSlaveInfo attaches + device to + newMaster. If the device is currently + attached to a master device, it is detached from the master + device and attached to the new master device. + + + XIAttachSlaveInfo can generate a + BadDevice error. + + + XIDettachSlaveInfo deattaches + device from the current master device + and sets it floating. If the device is already floating, no + changes are made. + + + XIDetachSlaveInfo can generate a + BadDevice error. + + + XIChangeHierarchy generates an + XIHierarchyEvent if any modifications were + successful. @@ -5640,39 +5667,32 @@ - BadValue - A value is outside of the permitted range. - - - - BadWindow - A value for a Window argument does not - name a defined window. - + BadDevice + + + An invalid device was specified. The device does + not exist or is not a appropriate for the type of + change. + + - BadDevice - An invalid device was specified. The - device does not exist. - + BadValue + + + Some numeric value falls out of the allowed range. + + - - See also - - XGrabDevice, - XUngrabDevice, - XGrabPointer - - - + __vendorversion__ - July 9, 2008 + February 14, 2008 PeterHutterer @@ -5682,24 +5702,25 @@ - XListDeviceProperties + XISelectEvents __libmansuffix__ __xorgversion__ XINPUT FUNCTIONS - + - XListDeviceProperties - List a device's properties. + XISelectEvents + select for XI2 events on the window. Syntax - #include <X11/extensions/XInput.h> + #include <X11/extensions/XInput2.h> - Atom* XListDeviceProperties + Status XISelectEvents Display *display - XDevice *device - int *nprops_return + Window win + XIEventMask *masks + int num_masks @@ -5709,43 +5730,78 @@ display - Specifies the connection to the X server. + Specifies the connection to the X server. + - device - The device to grab. + masks + Device event mask. + - nprops_return - Specifies the number of Atoms returned. - - - num_values - Specifies the number of elements in the - values list. - + num_masks + Number of masks in + masks. + + - property - Specifies the property to modify or query. - + win + + + Specifies the window. + + + Description - The XListDeviceProperties function returns a - list of the properties associated with the input device specified - in device. - Each device may have an arbitrary number of properties attached, - some of which were created by the driver and/or server, others - created by clients at runtime. + XI2 events must be selected using + XISelectEvents. - The client is expected to free the list of properties using - XFree. - XListDeviceProperties can generate a - BadDevice error. + XISelectEvents sets the event mask for this + client on win. Further events are only + reported to this client if the event type matches the selected + event mask. + The masks overrides the previously + selected event mask for the given device. + + + If deviceid is a valid device, the event mask + is selected only for this device. If + deviceid is + XIAllDevices or + XIAllMasterDevices, the event mask is + selected for all devices or all master devices, respectively. + The effective event mask is the bit-wise OR of the + XIAllDevices, + XIAllMasterDevices and the respective + device's event mask. + + + + typedef struct { + int deviceid; + int mask_len; + unsigned char* mask; + } XIEventMask; + + The mask_len specifies the length of mask + in bytes. mask is a binary mask in the + form of (1 << event type). deviceid + must be either a device or XIAllDevices or + XIAllMasterDevices. A client may submit several + masks with the same deviceid in one + request but only the last mask will be effective. + + + XISelectEvents can generate a + BadValue, a + BadDevice, and a + BadWindow error. @@ -5753,9 +5809,9 @@ - BadAtom - A value does not describe a valid named - identifier. + BadValue + A value is outside of the permitted range. + BadWindow @@ -5772,20 +5828,12 @@ - - See also - - XChangeDeviceProperty, - XGetDeviceProperty, - XDeleteDeviceProperty. - - - + __vendorversion__ - July 9, 2008 + February 14, 2008 PeterHutterer @@ -5795,53 +5843,24 @@ - XGetDeviceProperty + XIQueryVersion __libmansuffix__ __xorgversion__ XINPUT FUNCTIONS - + - XGetDeviceProperty - XChangeDeviceProperty - XDeleteDeviceProperty - Get, change or delete a device's property. + XIQueryVersion + announce and query the support XI2 version. Syntax - #include <X11/extensions/XInput.h> + #include <X11/extensions/XInput2.h> - int XGetDeviceProperty + Status XIQueryVersion Display *display - XDevice *device - Atom property - long offset - long length - Bool delete - Bool pending - Atom req_type - Atom *actual_type_return - int *actual_format_return - unsigned long *nitems_return - unsigned long *bytes_after_return - unsigned char **prop_return - - - void XChangeDeviceProperty - Display *display - XDevice *device - Atom property - Atom type - int format - int mode - const char *data - int nelements - - - void XDeleteDeviceProperty - Display *display - XDevice *device - Atom property + int *major_version_inout + int *minor_version_inout @@ -5850,158 +5869,169 @@ - actual_type_return - Returns an atom identifier that defines - the actual type of the property. - - - actual_format_return - Returns the actual format of the property. + display + Specifies the connection to the X server. - + - bytes_after_return - Returns the number of bytes remaining to - be read in the property if a partial read was - performed. + major_version_inout + Specifies the client's supported XI2 version, and + returns the server's supported version. + - data - Specifies the property data. + minor_version_inout + Specifies the client's supported XI2 version, and + returns the server's supported version. + + + + + + Description + + XIQueryVersion announces the client's + supported XI2 version to the server and returns server's + supported version. The server may treat a client differently + depending on the version support announced. The + major_version_inout must be 2 or greater, + otherwise a BadValue error occurs. + + + XIQueryVersion can generate a + BadValue error. + + + + Diagnosis + + - delete - Specifies a Boolean value that determines - wether the property is deleted. + BadValue + A value is outside of the permitted range. + + + + + + + + + __vendorversion__ + February 14, 2008 + + + PeterHutterer + Specification and implementation. + + + + + + XISetFocus, XIGetFocus + __libmansuffix__ + __xorgversion__ + XINPUT FUNCTIONS + + + XISetFocus + XIGetFocus + set or get the device's focus. + + + Syntax + + #include <X11/extensions/XInput2.h> + + Status XISetFocus + Display *display + int deviceid + Window focus + Time time + + + Status XIGetFocus + Display *display + Window *focus_return + + + + + Arguments + + display - Specifies the connection to the X server. + Specifies the connection to the X server. + - - device - The device to grab. + deviceid + Specifies the device whose focus is to be + queried or changed. + - format - Specifies whether the data should be - viewed as a list of 8-bit, 16-bit, or 32-bit - quantities. Possible values are 8, 16, and 32. - This information allows the X server to correctly - perform byte-swap operations as necessary. If the - format is 16-bit or 32-bit, you must explicitly - cast the data pointer to an (unsigned char*) in - the call to - XChangeDeviceProperty. + focus + The new focus window. - length - Specifies the length in 32-bit multiplies - of the data to be retrieved. - - - mode - Specifies the mode of operation. You can - pass PropModeReplace, - PropModePrepend, or - PropModeAppend. - - - - nelements - Specifies the number of elements in data. - - - nitems_return - Returns the actual number of 8-bit, - 16-bit, or 32-bit items stored in the prop_return - array. - - - num_values - Specifies the number of elements in the - values list. - - - offset - Specifies the offset in the specified - property (in 32-bit quantities) where the data is - to be retrieved. - - - pending - Specifies whether to retrieve the pending - state of the property or the current state. - - - property - Specifies the property to modify or query. - - - prop_return - Returns the data in the specified format. - If the returned format is 8, the returned data is - represented as a char array. If the returned - format is 16, the returned data is represented as - an array of short int type and should be cast to - that type to obtain the elements. If the returned - format is 32, the property data will be stored as - an array of longs (which in a 64-bit application - will be 64-bit values that are padded in the upper - 4 bytes). + focus_return + Returns the current focus window. - + - req_type - Specifies the atom identifier associated - with the property type or - AnyPropertyType. - + time + A valid timestamp or CurrentTime. + + Description - The XGetDeviceProperty function returns - the actual type of the property; the actual format of the property; - the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes - remaining to be read in the property; and a pointer to the data actually - returned. - For a detailed description of this function, see the man page - to XGetWindowProperty. + XISetFocus changes the focus of the + specified device ans its last-focus-change time. It + has no effect if the specified time is earlier than the current + last-focus-change time or is later than the current X server time. + Otherwise, the last-focus-change time is set to the specified + time. + CurrentTime is replaced by the current X + server time). XISetFocus causes the X + server to generate core, XI and XI2 focus events. - - The XChangeDeviceProperty function alters the - property for the specified device and causes the server to - generate a XPropertyNotifyEvent event on that - device. - For a detailed description of this function, see the man page to - XChangeProperty. - - The XDeleteDeviceProperty function - deletes the specified device property. Note that a client cannot - delete a property created by a driver or the server. Attempting to - do so will result in a BadAtom error. + If the focus window is + None all keyboard events by this device are + discarded until a new focus window is set. Otherwise, if + focus is a window, it becomes the device's + focus window. If a generated device event would normally be + reported to this window or one of its inferiors, the event is + reported as usual. Otherwise, the event is reported relative to + the focus window. - XGetDeviceProperty can generate a - BadAtom, - BadDevice error. + The specified focus window must be viewable at the time + XISetFocus is called, or a + BadMatch error results. If the focus window + later becomes not viewable, the focus reverts to the parent (or + the closest viewable ancestor. When the focus reverts, the X + server generates core, XI and XI2 focus events but the + last-focus-change time is not affected. - XChangeDeviceProperty can generate a - BadDevice, a - BadMatch, a - BadAtom, and a - BadValue error. + Attempting to set the focus on a master pointer device or an + attached slave device will result in a + BadDevice error. - XDeleteDeviceProperty can generate a - BadDevice, and a - BadAtom error. + XISetFocus can generate + BadDevice, BadMatch, + BadValue, and + BadWindow errors. @@ -6009,27 +6039,566 @@ - BadAtom - A value does not describe a valid named - identifier or the client attempted to remove - a driver-allocated property. + BadValue + A value is outside of the permitted range. + BadDevice - An invalid device was specified. The - device does not exist. - + + + An invalid device was specified. The device does + not exist or is not a appropriate for the type of + change. + + + + + BadMatch + + + The window is not viewable. + + + + + BadWindow + A value for a Window argument does not name a defined Window. + + + + + + __vendorversion__ + February 14, 2008 + + + PeterHutterer + Specification and implementation. + + + - See also - - XListDeviceProperties, - XQueryDeviceProperty, - XConfigureDeviceProperty. - + + XIGrabDevice, XIUngrabDevice + __libmansuffix__ + __xorgversion__ + XINPUT FUNCTIONS + + + XIGrabDevice + XIUngrabDevice + grab or ungrab the device. + + + Syntax + + #include <X11/extensions/XInput2.h> + + Status XIGrabDevice + Display *display + int deviceid + Window grab_window + Time time + Cursor cursor + int grab_mode + int paired_device_mode + Bool owner_events + XIEventMask *mask + + + Status XIUngrabDevice + Display *display + int deviceid + Time time + + + + + Arguments + + + + cursor + Specifies the cursor image to display + for the duration of the grab. + + + + display + Specifies the connection to the X server. + + + deviceid + Specifies the device that should be + grabbed or ungrabbed. + + + + grab_mode + paired_device_mode + The grab mode for this device and (if + applicable) the paired device. + + + + grab_window + The grab window. + + + + mask + Event mask. + + + + owner_events + True if events are to be reported + normally. + + + + time + A valid timestamp or CurrentTime. + + + + + + + Description + + XIGrabDevice actively grabs control of the + device. Further device events are reported only to the grabbing + client. XIGrabDevice overrides any active + device grab by this client. if deviceid + is an attached slave device, the device is set floating until + the client calls XIUngrabDevice. + + + If owner_events is + False, all generated device events are + reported with respect to grab_window if selected. If + owner_events is True + and if a generated device event would normally be reported to + this client, it is reported normally; otherwise, the event is + reported with respect to the grab_window, and is only reported + if specified in the event mask. + + + If the grab_mode argument is + GrabModeAsync, device event processing + continues as usual. If the device is currently frozen by this + client, then processing of device events is resumed. If the + grab_mode argument is + GrabModeSync, the state of the device (as + seen by client applications) appears + to freeze, and the X server generates no further device events + until the grabbing client issues a releasing + XIAllowEvents call or until the device + grab is released. Actual device changes are not lost while the + device is frozen; they are simply queued in the server for later + processing. + + + If paired_device_mode is + GrabModeAsync, processing of events from + the paired master device is unaffected by + activation of the grab. If + paired_device_mode is + GrabModeSync, the state of the paired + master device (as seen by client applications) appears to + freeze, and the X server generates no further events from this + device until the grabbing client issues a releasing + XIAllowEvents call or until the device + grab is released. Actual events are not lost while the devices are + frozen; they are simply queued in the server for later processing. + If the device is a slave device + paired_device_mode is ignored. + + + If the device is actively grabbed by some other client, + XIGrabDevice fails and returns + AlreadyGrabbed. If + grab_window is not + viewable, it fails and returns + GrabNotViewable. If the device is frozen by + an active grab of another client, it fails and returns + GrabFrozen. If the specified time is earlier + than the last-device-grab time or later than the current X server + time, it fails and returns GrabInvalidTime. + Otherwise, the last-device-grab time is set to the specified + time. CurrentTime is replaced by the + current X server time. + + + If cursor is not None this cursor is + displayed until the client calls + XIUngrabDevice. + + + XIGrabDevice can generate + BadDevice, BadValue, + and BadWindow errors. + + + The XIUngrabDevice request releases the + device and any queued events if this client has it actively + grabbed from either XIGrabDevice or + XIGrabKey or + XIGrabButton. If other devices are frozen + by the grab, XUngrabDevice thaws + them. XUngrabDevice does not release the + device and any queued events if the specified time is earlier than + the last-device-grab time or is later than the current X server + time. The X server automatically performs an + XIUngrabDevice request if the event window + for an active device grab becomes not + viewable. + + + XIUngrabDevice can generate a + BadDevice error. + + + + Diagnosis + + + + BadValue + A value is outside of the permitted range. + + + + BadDevice + + + An invalid device was specified. The device does + not exist or is not a appropriate for the type of + change. + + + + + BadMatch + + + The window is not viewable. + + + + + BadWindow + A value for a Window argument does not name a defined Window. + + + + + + + + + + __vendorversion__ + + + + XIGrabButton, XIGrabKeysym + __libmansuffix__ + __xorgversion__ + XINPUT FUNCTIONS + + + XIGrabButton + XIUngrabButton + XIGrabKeysym + XIUngrabKeysym + grab/ungrab buttons or keys + + + Syntax + + #include <X11/extensions/XInput.h> + + int XIGrabButton + Display *display + int deviceid + int button + Window grab_window + Cursor cursor + int grab_mode + int paired_device_mode + Boolowner_events + XIEventMask *mask + int num_modifiers + XIGrabModifiers *modifiers_inout + + + int XIUngrabButton + Display *display + int deviceid + int button + Window grab_window + int num_modifiers + XIGrabModifiers *modifiers + + + int XIGrabKeysym + Display *display + int deviceid + int keysym + Window grab_window + Cursor cursor + int grab_mode + int paired_device_mode + Boolowner_events + XIEventMask *mask + int num_modifiers + XIGrabModifiers *modifiers_inout + + + int XIUngrabKeysym + Display *display + int deviceid + int keysym + Window grab_window + int num_modifiers + XIGrabModifiers *modifiers + + + + Arguments + + + + display + Specifies the connection to the X server. + + + device + Specifies the device that is to be + grabbed or released + + button + Specifies the device button that is to + be grabbed or released or XIAnyButton. + + + keysym + Specifies the keysym that is to + be grabbed or released or XIAnyKeysym. + + + num_modifiers + Number of elements in + modifiers or + modifiers_return + + + modifiers + Specifies the set of latched and base + modifiers or XIAnyModifier + to ungrab. The data type is for consistency with + the respective grab request and the status code + of the XIGrabModifiers struct is ignored. + + + modifiers_inout + Specifies the set of latched and base + modifiers or XIAnyModifier + to grab. Returns the modifiers that could not be + grabbed and their status code. + + + grab_window + Specifies the grab window. + + + owner_events + Specifies a Boolean value that indicates + whether the are to be reported as + usual or reported with respect to the grab + window. + + + mask + Specifies the event mask. + + + grab_mode + Specifies further processing of events + from this device. You can pass + GrabModeSync or + GrabModeAsync. + + + paired_device_mode + Specifies further processing of events + from the paired master device. You can pass + GrabModeSync or + GrabModeAsync. + If deviceid specifies a + floating slave device, this parameter is + ignored. + + + + + + + Description + + XIGrabButton and + XIGrabKeysym establishes a + passive grab. The modifier device for a button grab is the + paired master device if deviceid + specifies a master pointer. Otherwise, the modifier device is + the device specified with deviceid. + In the future, the device is actively grabbed (as + for XIGrabDevice, the last-grab time is set + to the time at which the button or keysym was pressed and the + X_XIButtonPress or + X_XIKeyPress event is reported if all + of the following conditions are true: + + + + + The device is not grabbed, and the specified button + or keysym is logically pressed when the specified + modifier keys are logically down on the modifier + device and no other buttons or modifier keys are + logically down. + + + + Either the grab window is an ancestor of (or is) the + focus window, OR the grab window is a descendent of the + focus window and contains the device. + + + + + A passive grab on the same button/modifier combination + does not exist on any ancestor of grab_window. + + + + + + The interpretation of the remaining arguments is as for + XIGrabDevice. The active grab is terminated + automatically when the logical state of the device has all + buttons or keys released (independent of the logical state of + the modifier keys). + + + Note that the logical state of a device (as seen by client + applications) may lag the physical state if device event + processing is frozen. + + + This request overrides all previous grabs by the same client on + the same button/modifier or keysym/modifier combinations on the + same window. A modifiers of XIAnyModifier + is equivalent to issuing the grab request for all possible + modifier combinations (including the combination of no + modifiers). It is not required that all modifiers specified have + currently assigned KeyCodes. A button of + XIAnyButton is equivalent to + issuing the request for all possible buttons. Otherwise, it is not + required that the specified button currently be assigned to a + physical button. + + + If some other client has already issued a + XIGrabButton or + XIGrabKeysym with the same + button/modifier or keysym/modifier combination on the same + window, a BadAccess error results. When + using XIAnyModifier or + XIAnyButton , the request fails completely, and + a XIBadAccess error results (no grabs are + established) if there is a conflicting grab for any combination. + XIGrabButton and + XIGrabKeysym have no effect on an active + grab. + + + XIGrabButton and + XIGrabKeysym can generate + BadClass, BadDevice, + BadMatch, BadValue, and + BadWindow errors. + + + XIUngrabButton and + XIUngrabKeysym releases the + passive grab for a button/modifier or keysym/modifier + combination on the specified window if it was grabbed by this + client. A modifier of XIAnyModifier is + equivalent to issuing the ungrab request for all possible + modifier combinations, including the combination of no + modifiers. A button of XIAnyButton is + equivalent to issuing the request for all possible buttons. + XIUngrabButton and + XIUngrabKeysym have no effect on an + active grab. + + + XIUngrabButton and + XIUngrabKeysym can generate + BadDevice, BadMatch, + BadValue and BadWindow + errors. + + + + Diagnostics + + + BadDevice + An invalid deviceid was specified. + + + + BadMatch + This error may occur if + XIGrabButton + specified a device that has no + buttons, or XIGrabKeysym + specified a device that has no keys. + + + + + BadValue + Some numeric value falls outside the range + of values accepted by the request. Unless a + specific range is specified for an argument, the + full range defined by the argument's type is + accepted. Any argument defined as a set of + alternatives can generate this error. + + + + + BadWindow + A value for a Window argument does not name a defined Window. + + + + + + + + See also + XIAllowEvents(3), XIGrabDevice(3) -- cgit v1.2.3