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

NAME

6       xcb_grab_button - Grab pointer button(s)
7

SYNOPSIS

9       #include <xcb/xproto.h>
10
11   Request function
12       xcb_void_cookie_t xcb_grab_button(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, uint8_t button, uint16_t modifiers);
17

REQUEST ARGUMENTS

19       conn      The XCB connection to X11.
20
21       owner_events
22                 If 1, the grab_window will still get the pointer events. If
23                 0, events are not reported to the grab_window.
24
25       grab_window
26                 Specifies the window on which the pointer should be grabbed.
27
28       event_mask
29                 Specifies which pointer events are reported to the client.
30
31                 TODO: which values?
32
33       pointer_mode
34                 One of the following values:
35
36                 XCB_GRAB_MODE_SYNC
37                           The state of the keyboard appears to freeze: No
38                           further keyboard events are generated by the server
39                           until the grabbing client issues a releasing Allow‐
40                           Events request or until the keyboard grab is re‐
41                           leased.
42
43                 XCB_GRAB_MODE_ASYNC
44                           Keyboard event processing continues normally.
45
46
47
48       keyboard_mode
49                 One of the following values:
50
51                 XCB_GRAB_MODE_SYNC
52                           The state of the keyboard appears to freeze: No
53                           further keyboard events are generated by the server
54                           until the grabbing client issues a releasing Allow‐
55                           Events request or until the keyboard grab is re‐
56                           leased.
57
58                 XCB_GRAB_MODE_ASYNC
59                           Keyboard event processing continues normally.
60
61
62
63       confine_to
64                 Specifies the window to confine the pointer in (the user will
65                 not be able to move the pointer out of that window).
66
67                 The special value XCB_NONE means don't confine the pointer.
68
69       cursor    Specifies the cursor that should be displayed or XCB_NONE to
70                 not change the cursor.
71
72       button    One of the following values:
73
74                 XCB_BUTTON_INDEX_ANY
75                           Any of the following (or none):
76
77                 XCB_BUTTON_INDEX_1
78                           The left mouse button.
79
80                 XCB_BUTTON_INDEX_2
81                           The right mouse button.
82
83                 XCB_BUTTON_INDEX_3
84                           The middle mouse button.
85
86                 XCB_BUTTON_INDEX_4
87                           Scroll wheel. TODO: direction?
88
89                 XCB_BUTTON_INDEX_5
90                           Scroll wheel. TODO: direction?
91
92
93
94       modifiers The modifiers to grab.
95
96                 Using the special value XCB_MOD_MASK_ANY means grab the
97                 pointer with all possible modifier combinations.
98

DESCRIPTION

100       This request establishes a passive grab. The pointer is actively
101       grabbed as described in GrabPointer, the last-pointer-grab time is set
102       to the time at which the button was pressed (as transmitted in the But‐
103       tonPress event), and the ButtonPress event is reported if all of the
104       following conditions are true:
105
106       The pointer is not grabbed and the specified button is logically
107       pressed when the specified modifier keys are logically down, and no
108       other buttons or modifier keys are logically down.
109
110       The grab-window contains the pointer.
111
112       The confine-to window (if any) is viewable.
113
114       A passive grab on the same button/key combination does not exist on any
115       ancestor of grab-window.
116
117       The interpretation of the remaining arguments is the same as for Grab‐
118       Pointer.  The active grab is terminated automatically when the logical
119       state of the pointer has all buttons released, independent of the logi‐
120       cal state of modifier keys. Note that the logical state of a device (as
121       seen by means of the protocol) may lag the physical state if device
122       event processing is frozen. This request overrides all previous passive
123       grabs by the same client on the same button/key combinations on the
124       same window. A modifier of AnyModifier is equivalent to issuing the re‐
125       quest for all possible modifier combinations (including the combination
126       of no modifiers). It is not required that all specified modifiers have
127       currently assigned keycodes. A button of AnyButton is equivalent to is‐
128       suing the request for all possible buttons. Otherwise, it is not re‐
129       quired that the button specified currently be assigned to a physical
130       button.
131
132       An Access error is generated if some other client has already issued a
133       GrabButton request with the same button/key combination on the same
134       window.  When using AnyModifier or AnyButton, the request fails com‐
135       pletely (no grabs are established), and an Access error is generated if
136       there is a conflicting grab for any combination. The request has no ef‐
137       fect on an active grab.
138

RETURN VALUE

140       Returns an xcb_void_cookie_t. Errors (if any) have to be handled in the
141       event loop.
142
143       If you want to handle errors directly with xcb_request_check instead,
144       use xcb_grab_button_checked. See xcb-requests(3) for details.
145

ERRORS

147       xcb_access_error_t
148                 Another client has already issued a GrabButton with the same
149                 button/key combination on the same window.
150
151       xcb_cursor_error_t
152                 The specified cursor does not exist.
153
154       xcb_value_error_t
155                 TODO: reasons?
156
157       xcb_window_error_t
158                 The specified window does not exist.
159

SEE ALSO

161       xcb-requests(3)
162

AUTHOR

164       Generated from xproto.xml. Contact xcb@lists.freedesktop.org for cor‐
165       rections and improvements.
166
167
168
169X Version 11                      libxcb 1.13               xcb_grab_button(3)
Impressum