From a761ae5119b1460068d6f62219c4e2705ef20814 Mon Sep 17 00:00:00 2001 From: Povilas Kanapickas Date: Sat, 4 Sep 2021 00:03:50 +0300 Subject: man: Document XIAllowEvents --- man/Makefile.am | 1 + man/XIAllowEvents.txt | 159 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 160 insertions(+) create mode 100644 man/XIAllowEvents.txt diff --git a/man/Makefile.am b/man/Makefile.am index b92d486..6f3826d 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -25,6 +25,7 @@ libmandir = $(LIB_MAN_DIR) # Source files for X Input v2 man pages XI2_txt = \ + XIAllowEvents.txt \ XIBarrierReleasePointer.txt \ XIChangeHierarchy.txt \ XIDefineCursor.txt \ diff --git a/man/XIAllowEvents.txt b/man/XIAllowEvents.txt new file mode 100644 index 0000000..f00b39b --- /dev/null +++ b/man/XIAllowEvents.txt @@ -0,0 +1,159 @@ +XIALLOWEVENTS(libmansuffix) +=========================== + +NAME +---- + + XIAllowEvents - Release queued events + +SYNOPSIS +-------- + + #include + + Status XIAllowEvents( Display *display, + int deviceid, + int event_mode, + Time time ); + + Status XIAllowTouchEvents( Display *dpy, + int deviceid, + unsigned int touchid, + Window grab_window, + int event_mode ); + + display + Specifies the connection to the X server. + + device + Specifies the device that is to be grabbed or released + + event_mode + Specifies whether a device is to be thawed and events are to be + replayed, or how to handle a grabbed touch sequence. + + time + A valid server time or CurrentTime. + + touchid + The ID of the touch sequence to accept or reject. The value is ignored + for event modes other than AcceptTouch and RejectTouch. + + grab_window + The window on which to accept or reject a touch sequence grab. The value + is ignored for event modes other than AcceptTouch and RejectTouch. + +DESCRIPTION +----------- + + The XIAllowEvents request releases some queued events if the client + has caused a device to freeze. It also is used to handle touch grab and + ownership processing. + + The function has no effect if the specified time is earlier than the last-grab + time of the most recent active grab for the client, or if the specified time is + later than the current X server time. The time parameter must be CurrentTime for + requests with event modes of XIAcceptTouch and XIRejectTouch. + + The following describes the processing that occurs depending on what constant + you pass to the event_mode argument: + + XIAsyncDevice: + If the specified device is frozen by the client, event processing for that + device continues as usual. If the device is frozen multiple times by the + client on behalf of multiple separate grabs, XIAsyncDevice thaws for + all. XIAsyncDevice has no effect if the specified device is not frozen + by the client, but the device need not be grabbed by the client. + + XISyncDevice: + If the specified device is frozen and actively grabbed by the client, + event processing for that device continues normally until the next + button press or release, or key press or release, or a gesture begin or end + event (depending on the grab) is reported to the client. + At this time, the specified device again appears to freeze. + However, if the reported event causes the grab to be released, the + specified device does not freeze. + XISyncDevice has no effect if the specified device is not frozen by the + client or is not grabbed by the client. + + XIReplayDevice: + If the specified device is actively grabbed by the client and is frozen + as the result of an event having been sent to the client (either from + the activation of a XIGrabButton or from a previous XIAllowEvents with + mode SyncDevice, but not from a Grab), the grab is released and + that event is completely reprocessed. This time, however, the request + ignores any passive grabs at or above (towards the root) the + grab window of the grab just released. + The request has no effect if the specified device is not grabbed by + the client or if it is not frozen as the result of an event. + In case of gesture begin event being replayed, the original grabbing + client will receive a XI_GesturePinchEnd or XI_GestureSwipeEnd event. + + XIAsyncPairedDevice: + If the paired master device is frozen by the client, event processing + for it continues as usual. If the paired device is frozen multiple + times by the client on behalf of multiple separate grabs, + XIAsyncPairedDevice thaws for all. + XIAsyncPairedDevice has no effect if the device is not frozen by the + client, but those devices need not be grabbed by the client. + XIAsyncPairedDevice has no effect if deviceid specifies a slave device. + + XISyncPair: + If both the device and the paired master device are frozen by the + client, event processing (for both devices) continues normally until + the next XI_ButtonPress, XI_ButtonRelease, XI_KeyPress, or XI_KeyRelease + event is reported to the client for a grabbed device (button event for + a pointer, key event for a keyboard), at which time the devices again + appear to freeze. However, if the reported event causes the grab to be + released, then the devices do not freeze (but if the other device is + still grabbed, then a subsequent event for it will still cause both + devices to freeze). + XISyncPair has no effect unless both the device and the paired master + device are frozen by the client. If the device or paired master device + is frozen twice by the client on behalf of two separate grabs, + XISyncPair thaws for both (but a subsequent freeze for XISyncPair will + only freeze each device once). + XISyncPair has no effect if deviceid specifies a slave device. + + XIAsyncPair: + If the device and the paired master device are frozen by the client, + event processing for both devices continues normally. If a device is + frozen twice by the client on behalf of two separate grabs, AsyncBoth + thaws for both. XIAsyncPair has no effect unless both the device and the + paired master device frozen by the client. + XIAsyncPair has no effect if deviceid specifies a slave device. + + XIAcceptTouch: + The client is deemed to have taken control of the touch sequence once it + owns the sequence. TouchEnd events will be sent to all clients listening + to the touch sequence that have either grabbed the touch sequence on a + child window of the grab_window or have received events for the touch + sequence through event selection. These clients will no longer receive + any TouchUpdate events. + + XIRejectTouch: + The client is no longer interested in the touch sequence, and will + receive a XI_TouchEnd event. If the client is the current owner of the + sequence, ownership will be passed on to the next listener. + +DIAGNOSTICS +----------- + + BadDevice + An invalid deviceid was specified. + + BadAccess + This error may occur if event_mode is XIAcceptTouch and this client + is not the current or potential owner of the specified touch ID. + + BadValue + This error may occur if event_mode is XIAcceptTouch and touch ID is invalid. + + BadWindow + A value for a grab_window argument does not name a defined + Window. + +SEE ALSO +-------- + + XIGrabButton(libmansuffix) -- cgit v1.2.3