1xcb_grab_pointer(3)              XCB Requests              xcb_grab_pointer(3)
2
3
4

NAME

6       xcb_grab_pointer - Grab the pointer
7

SYNOPSIS

9       #include <xcb/xproto.h>
10
11   Request function
12       xcb_grab_pointer_cookie_t xcb_grab_pointer(xcb_connection_t *conn,
13              uint8_t owner_events, xcb_window_t grab_window,
14              uint16_t event_mask, uint8_t pointer_mode,
15              uint8_t keyboard_mode, xcb_window_t confine_to,
16              xcb_cursor_t cursor, xcb_timestamp_t time);
17
18   Reply datastructure
19       typedef struct xcb_grab_pointer_reply_t {
20           uint8_t  response_type;
21           uint8_t  status;
22           uint16_t sequence;
23           uint32_t length;
24       } xcb_grab_pointer_reply_t;
25
26   Reply function
27       xcb_grab_pointer_reply_t
28              *xcb_grab_pointer_reply(xcb_connection_t *conn,
29              xcb_grab_pointer_cookie_t cookie, xcb_generic_error_t **e);
30

REQUEST ARGUMENTS

32       conn      The XCB connection to X11.
33
34       owner_events
35                 If 1, the grab_window will still get the pointer events. If
36                 0, events are not reported to the grab_window.
37
38       grab_window
39                 Specifies the window on which the pointer should be grabbed.
40
41       event_mask
42                 Specifies which pointer events are reported to the client.
43
44                 TODO: which values?
45
46       pointer_mode
47                 One of the following values:
48
49                 XCB_GRAB_MODE_SYNC
50                           The state of the keyboard appears to freeze: No
51                           further keyboard events are generated by the server
52                           until the grabbing client issues a releasing Allow‐
53                           Events request or until the keyboard grab is re‐
54                           leased.
55
56                 XCB_GRAB_MODE_ASYNC
57                           Keyboard event processing continues normally.
58
59
60
61       keyboard_mode
62                 One of the following values:
63
64                 XCB_GRAB_MODE_SYNC
65                           The state of the keyboard appears to freeze: No
66                           further keyboard events are generated by the server
67                           until the grabbing client issues a releasing Allow‐
68                           Events request or until the keyboard grab is re‐
69                           leased.
70
71                 XCB_GRAB_MODE_ASYNC
72                           Keyboard event processing continues normally.
73
74
75
76       confine_to
77                 Specifies the window to confine the pointer in (the user will
78                 not be able to move the pointer out of that window).
79
80                 The special value XCB_NONE means don't confine the pointer.
81
82       cursor    Specifies the cursor that should be displayed or XCB_NONE to
83                 not change the cursor.
84
85       time      The time argument allows you to avoid certain circumstances
86                 that come up if applications take a long time to respond or
87                 if there are long network delays.  Consider a situation where
88                 you have two applications, both of which normally grab the
89                 pointer when clicked on. If both applications specify the
90                 timestamp from the event, the second application may wake up
91                 faster and successfully grab the pointer before the first ap‐
92                 plication. The first application then will get an indication
93                 that the other application grabbed the pointer before its re‐
94                 quest was processed.
95
96                 The special value XCB_CURRENT_TIME will be replaced with the
97                 current server time.
98

REPLY FIELDS

100       response_type
101                 The type of this reply, in this case XCB_GRAB_POINTER. This
102                 field is also present in the xcb_generic_reply_t and can be
103                 used to tell replies apart from each other.
104
105       sequence  The sequence number of the last request processed by the X11
106                 server.
107
108       length    The length of the reply, in words (a word is 4 bytes).
109
110       status    One of the following values:
111
112                 XCB_GRAB_STATUS_SUCCESS
113                           TODO: NOT YET DOCUMENTED.
114
115                 XCB_GRAB_STATUS_ALREADY_GRABBED
116                           TODO: NOT YET DOCUMENTED.
117
118                 XCB_GRAB_STATUS_INVALID_TIME
119                           TODO: NOT YET DOCUMENTED.
120
121                 XCB_GRAB_STATUS_NOT_VIEWABLE
122                           TODO: NOT YET DOCUMENTED.
123
124                 XCB_GRAB_STATUS_FROZEN
125                           TODO: NOT YET DOCUMENTED.
126                 TODO: NOT YET DOCUMENTED.
127

DESCRIPTION

129       Actively grabs control of the pointer. Further pointer events are re‐
130       ported only to the grabbing client. Overrides any active pointer grab
131       by this client.
132

RETURN VALUE

134       Returns an xcb_grab_pointer_cookie_t. Errors have to be handled when
135       calling the reply function xcb_grab_pointer_reply.
136
137       If you want to handle errors in the event loop instead, use
138       xcb_grab_pointer_unchecked. See xcb-requests(3) for details.
139

ERRORS

141       xcb_value_error_t
142                 TODO: reasons?
143
144       xcb_window_error_t
145                 The specified window does not exist.
146

EXAMPLE

148       /*
149        * Grabs the pointer actively
150        *
151        */
152       void my_example(xcb_connection_t *conn, xcb_screen_t *screen, xcb_cursor_t cursor) {
153           xcb_grab_pointer_cookie_t cookie;
154           xcb_grab_pointer_reply_t *reply;
155
156           cookie = xcb_grab_pointer(
157               conn,
158               false,               /* get all pointer events specified by the following mask */
159               screen->root,        /* grab the root window */
160               XCB_NONE,            /* which events to let through */
161               XCB_GRAB_MODE_ASYNC, /* pointer events should continue as normal */
162               XCB_GRAB_MODE_ASYNC, /* keyboard mode */
163               XCB_NONE,            /* confine_to = in which window should the cursor stay */
164               cursor,              /* we change the cursor to whatever the user wanted */
165               XCB_CURRENT_TIME
166           );
167
168           if ((reply = xcb_grab_pointer_reply(conn, cookie, NULL))) {
169               if (reply->status == XCB_GRAB_STATUS_SUCCESS)
170                   printf("successfully grabbed the pointer\n");
171               free(preply);
172           }
173       }
174

SEE ALSO

176       xcb-requests(3), xcb-examples(3), xcb_grab_keyboard(3)
177

AUTHOR

179       Generated from xproto.xml. Contact xcb@lists.freedesktop.org for cor‐
180       rections and improvements.
181
182
183
184X Version 11                      libxcb 1.13              xcb_grab_pointer(3)
Impressum