X Window System Core Protocol - Grabs

Grabs

A grab is a condition in which all keyboard or mouse events are sent to a single client. A client can request a grab of the keyboard, the mouse, or both: if the request is fulfilled by the server, all keyboard/mouse events are sent to the grabbing client until the grab is released. The other clients will not receive these events.

When requesting a grab, a client specifies a grab window: all events are sent to the grabbing client as if they were relative to the grab window. However, the other clients do not receive events even if they have selected them in the grab window. There are two kinds of grabs:

active

the grab takes place immediately

passive

the grab takes place only when a previously specified key or mouse button is pressed and terminates when it is released

A client can establish a grab over the keyboard, the pointer, or both. A request for grabbing can include a request for freezing the keyboard or the pointer. The difference between grabbing and freezing is that grabbing changes the recipient of events, while freezing stops their delivery altogether. When a device is frozen, the events it generates are stored in a queue to be delivered as usual when the freeze is over.

For pointer events, an additional parameter affects the delivery of events: an event mask, which specifies which types of events are to be delivered and which ones are to be discarded.

The requests for grabbing include a field for specifying what happens to events that would be sent to the grabbing client even if it had not established the grab. In particular, the client can request them to be sent as usual or according to the grab. These two conditions are not the same as they may appear. For example, a client that would normally receive the keyboard events on a first window may request the keyboard to be grabbed by a second window. Events that would normally be sent to the first window may or may not be redirected to the grab window depending on the parameter in the grab request.

A client can also request the grab of the entire server. In this case, no request will be processed by the server except the ones coming from the grabbing client.