1XGrabPointer(3)                 XLIB FUNCTIONS                 XGrabPointer(3)
2
3
4

NAME

6       XGrabPointer,   XUngrabPointer,  XChangeActivePointerGrab  -  grab  the
7       pointer
8

SYNTAX

10       int   XGrabPointer(Display   *display,   Window    grab_window,    Bool
11              owner_events,  unsigned  int  event_mask,  int pointer_mode, int
12              keyboard_mode, Window confine_to, Cursor cursor, Time time);
13
14       int XUngrabPointer(Display *display, Time time);
15
16       int XChangeActivePointerGrab(Display *display, unsigned int event_mask,
17              Cursor cursor, Time time);
18

ARGUMENTS

20       confine_to
21                 Specifies the window to confine the pointer in or None.
22
23       cursor    Specifies  the cursor that is to be displayed during the grab
24                 or None.
25
26       display   Specifies the connection to the X server.
27
28       event_mask
29                 Specifies which pointer events are reported  to  the  client.
30                 The  mask  is  the  bitwise inclusive OR of the valid pointer
31                 event mask bits.
32
33       grab_window
34                 Specifies the grab window.
35
36       keyboard_mode
37                 Specifies further processing of  keyboard  events.   You  can
38                 pass GrabModeSync or GrabModeAsync.
39
40       owner_events
41                 Specifies  a Boolean value that indicates whether the pointer
42                 events are to be reported as usual or reported  with  respect
43                 to the grab window if selected by the event mask.
44
45       pointer_mode
46                 Specifies further processing of pointer events.  You can pass
47                 GrabModeSync or GrabModeAsync.
48
49       time      Specifies the time.  You can pass either a timestamp or  Cur‐
50                 rentTime.
51

DESCRIPTION

53       The XGrabPointer function actively grabs control of the pointer and re‐
54       turns GrabSuccess if the grab was successful.  Further  pointer  events
55       are  reported  only to the grabbing client.  XGrabPointer overrides any
56       active pointer grab by this client.  If owner_events is False, all gen‐
57       erated  pointer events are reported with respect to grab_window and are
58       reported only if selected by event_mask.  If owner_events is  True  and
59       if a generated pointer event would normally be reported to this client,
60       it is reported as usual.  Otherwise, the event is reported with respect
61       to the grab_window and is reported only if selected by event_mask.  For
62       either value of owner_events, unreported events are discarded.
63
64       If the pointer_mode is GrabModeAsync, pointer event processing  contin‐
65       ues  as  usual.  If the pointer is currently frozen by this client, the
66       processing of events for the pointer is resumed.  If  the  pointer_mode
67       is  GrabModeSync,  the state of the pointer, as seen by client applica‐
68       tions, appears to freeze, and the X server generates no further pointer
69       events  until  the  grabbing  client  calls  XAllowEvents  or until the
70       pointer grab is released.  Actual pointer changes are  not  lost  while
71       the  pointer  is frozen; they are simply queued in the server for later
72       processing.
73
74       If the keyboard_mode is GrabModeAsync, keyboard event processing is un‐
75       affected  by  activation of the grab.  If the keyboard_mode is GrabMod‐
76       eSync, the state of the keyboard, as seen by client  applications,  ap‐
77       pears  to freeze, and the X server generates no further keyboard events
78       until the grabbing client calls XAllowEvents or until the pointer  grab
79       is released.  Actual keyboard changes are not lost while the pointer is
80       frozen; they are simply queued in the server for later processing.
81
82       If a cursor is specified, it is displayed regardless of what window the
83       pointer is in.  If None is specified, the normal cursor for that window
84       is displayed when the pointer is in grab_window or one of  its  subwin‐
85       dows; otherwise, the cursor for grab_window is displayed.
86
87       If  a confine_to window is specified, the pointer is restricted to stay
88       contained in that window.  The confine_to window need have no relation‐
89       ship  to  the grab_window.  If the pointer is not initially in the con‐
90       fine_to window, it is warped automatically to the closest edge just be‐
91       fore  the grab activates and enter/leave events are generated as usual.
92       If the confine_to window is subsequently reconfigured, the  pointer  is
93       warped automatically, as necessary, to keep it contained in the window.
94
95       The  time  argument allows you to avoid certain circumstances that come
96       up if applications take a long time to respond or  if  there  are  long
97       network  delays.  Consider a situation where you have two applications,
98       both of which normally grab the pointer when clicked on.  If  both  ap‐
99       plications specify the timestamp from the event, the second application
100       may wake up faster and successfully grab the pointer before  the  first
101       application.   The  first  application then will get an indication that
102       the other application grabbed the pointer before its request  was  pro‐
103       cessed.
104
105       XGrabPointer generates EnterNotify and LeaveNotify events.
106
107       Either  if  grab_window  or confine_to window is not viewable or if the
108       confine_to window lies completely outside the boundaries  of  the  root
109       window, XGrabPointer fails and returns GrabNotViewable.  If the pointer
110       is actively grabbed by some other client, it fails and returns Already‐
111       Grabbed.  If the pointer is frozen by an active grab of another client,
112       it fails and returns GrabFrozen.  If the specified time is earlier than
113       the  last-pointer-grab time or later than the current X server time, it
114       fails and returns GrabInvalidTime.   Otherwise,  the  last-pointer-grab
115       time  is set to the specified time (CurrentTime is replaced by the cur‐
116       rent X server time).
117
118       XGrabPointer can generate BadCursor, BadValue, and BadWindow errors.
119
120       The XUngrabPointer function releases the pointer and any queued  events
121       if  this  client  has  actively  grabbed the pointer from XGrabPointer,
122       XGrabButton, or from a normal button press.   XUngrabPointer  does  not
123       release  the  pointer  if  the specified time is earlier than the last-
124       pointer-grab time or is later than the current X server time.  It  also
125       generates EnterNotify and LeaveNotify events.  The X server performs an
126       UngrabPointer request automatically if the event window  or  confine_to
127       window for an active pointer grab becomes not viewable or if window re‐
128       configuration causes the confine_to window to  lie  completely  outside
129       the boundaries of the root window.
130
131       The XChangeActivePointerGrab function changes the specified dynamic pa‐
132       rameters if the pointer is actively grabbed by the client  and  if  the
133       specified  time  is  no  earlier than the last-pointer-grab time and no
134       later than the current X server time.  This function has no  effect  on
135       the  passive  parameters  of  a  XGrabButton.   The  interpretation  of
136       event_mask and cursor is the same as described in XGrabPointer.
137
138       XChangeActivePointerGrab can generate a BadCursor and BadValue error.
139

DIAGNOSTICS

141       BadCursor A value for a Cursor argument does not name a defined Cursor.
142
143       BadValue  Some numeric value falls outside the range of values accepted
144                 by  the request.  Unless a specific range is specified for an
145                 argument, the full range defined by the  argument's  type  is
146                 accepted.   Any argument defined as a set of alternatives can
147                 generate this error.
148
149       BadWindow A value for a Window argument does not name a defined Window.
150

SEE ALSO

152       XAllowEvents(3), XGrabButton(3), XGrabKey(3), XGrabKeyboard(3)
153       Xlib - C Language X Interface
154
155
156
157X Version 11                     libX11 1.8.1                  XGrabPointer(3)
Impressum