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
54       returns 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
75       unaffected by activation of the grab.  If the keyboard_mode is GrabMod‐
76       eSync, the state of the  keyboard,  as  seen  by  client  applications,
77       appears  to  freeze,  and  the  X  server generates no further keyboard
78       events until the  grabbing  client  calls  XAllowEvents  or  until  the
79       pointer  grab  is released.  Actual keyboard changes are not lost while
80       the pointer is frozen; they are simply queued in the server  for  later
81       processing.
82
83       If a cursor is specified, it is displayed regardless of what window the
84       pointer is in.  If None is specified, the normal cursor for that window
85       is  displayed  when the pointer is in grab_window or one of its subwin‐
86       dows; otherwise, the cursor for grab_window is displayed.
87
88       If a confine_to window is specified, the pointer is restricted to  stay
89       contained in that window.  The confine_to window need have no relation‐
90       ship to the grab_window.  If the pointer is not initially in  the  con‐
91       fine_to  window,  it  is  warped automatically to the closest edge just
92       before the grab activates  and  enter/leave  events  are  generated  as
93       usual.   If  the  confine_to  window  is subsequently reconfigured, the
94       pointer is warped automatically, as necessary, to keep it contained  in
95       the window.
96
97       The  time  argument allows you to avoid certain circumstances that come
98       up if applications take a long time to respond or  if  there  are  long
99       network  delays.  Consider a situation where you have two applications,
100       both of which normally grab the  pointer  when  clicked  on.   If  both
101       applications  specify the timestamp from the event, the second applica‐
102       tion may wake up faster and successfully grab the  pointer  before  the
103       first  application.   The first application then will get an indication
104       that the other application grabbed the pointer before its  request  was
105       processed.
106
107       XGrabPointer generates EnterNotify and LeaveNotify events.
108
109       Either  if  grab_window  or confine_to window is not viewable or if the
110       confine_to window lies completely outside the boundaries  of  the  root
111       window, XGrabPointer fails and returns GrabNotViewable.  If the pointer
112       is actively grabbed by some other client, it fails and returns Already‐
113       Grabbed.  If the pointer is frozen by an active grab of another client,
114       it fails and returns GrabFrozen.  If the specified time is earlier than
115       the  last-pointer-grab time or later than the current X server time, it
116       fails and returns GrabInvalidTime.   Otherwise,  the  last-pointer-grab
117       time  is  set to the specified time is replaced by the current X server
118       time).
119
120       XGrabPointer can generate BadCursor, BadValue, and BadWindow errors.
121
122       The XUngrabPointer function releases the pointer and any queued  events
123       if  this  client  has  actively  grabbed the pointer from XGrabPointer,
124       XGrabButton, or from a normal button press.   XUngrabPointer  does  not
125       release  the  pointer  if  the specified time is earlier than the last-
126       pointer-grab time or is later than the current X server time.  It  also
127       generates EnterNotify and LeaveNotify events.  The X server performs an
128       UngrabPointer request automatically if the event window  or  confine_to
129       window  for  an  active  pointer grab becomes not viewable or if window
130       reconfiguration causes the confine_to window to lie completely  outside
131       the boundaries of the root window.
132
133       The  XChangeActivePointerGrab  function  changes  the specified dynamic
134       parameters if the pointer is actively grabbed by the client and if  the
135       specified  time  is  no  earlier than the last-pointer-grab time and no
136       later than the current X server time.  This function has no  effect  on
137       the  passive  parameters  of  a  XGrabButton.   The  interpretation  of
138       event_mask and cursor is the same as described in XGrabPointer.
139
140       XChangeActivePointerGrab can generate a BadCursor and BadValue error.
141

DIAGNOSTICS

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

SEE ALSO

154       XAllowEvents(3), XGrabButton(3), XGrabKey(3), XGrabKeyboard(3)
155       Xlib - C Language X Interface
156
157
158
159X Version 11                     libX11 1.6.12                 XGrabPointer(3)
Impressum