1//! XWayland related protocols
2
3#![cfg_attr(rustfmt, rustfmt_skip)]
4
5#[cfg(feature = "staging")]
6pub mod shell {
7 //! This protocol adds a xwayland_surface role which allows an Xwayland
8 //! server to associate an X11 window to a wl_surface.
9 //!
10 //! Before this protocol, this would be done via the Xwayland server
11 //! providing the wl_surface's resource id via the a client message with
12 //! the WL_SURFACE_ID atom on the X window.
13 //! This was problematic as a race could occur if the wl_surface
14 //! associated with a WL_SURFACE_ID for a window was destroyed before the
15 //! client message was processed by the compositor and another surface
16 //! (or other object) had taken its id due to recycling.
17 //!
18 //! This protocol solves the problem by moving the X11 window to wl_surface
19 //! association step to the Wayland side, which means that the association
20 //! cannot happen out-of-sync with the resource lifetime of the wl_surface.
21 //!
22 //! This protocol avoids duplicating the race on the other side by adding a
23 //! non-zero monotonic serial number which is entirely unique that is set on
24 //! both the wl_surface (via. xwayland_surface_v1's set_serial method) and
25 //! the X11 window (via. the `WL_SURFACE_SERIAL` client message) that can be
26 //! used to associate them, and synchronize the two timelines.
27 //!
28 //! The key words "must", "must not", "required", "shall", "shall not",
29 //! "should", "should not", "recommended", "may", and "optional" in this
30 //! document are to be interpreted as described in IETF RFC 2119.
31
32 #[allow(missing_docs)]
33 pub mod v1 {
34 wayland_protocol!(
35 "./protocols/staging/xwayland-shell/xwayland-shell-v1.xml",
36 []
37 );
38 }
39}
40
41#[cfg(feature = "unstable")]
42pub mod keyboard_grab {
43 //! Protocol for grabbing the keyboard from Xwayland
44 //!
45 //! This protocol is application-specific to meet the needs of the X11
46 //! protocol through Xwayland. It provides a way for Xwayland to request
47 //! all keyboard events to be forwarded to a surface even when the
48 //! surface does not have keyboard focus.
49 //!
50 //! In the X11 protocol, a client may request an "active grab" on the
51 //! keyboard. On success, all key events are reported only to the
52 //! grabbing X11 client. For details, see XGrabKeyboard(3).
53 //!
54 //! The core Wayland protocol does not have a notion of an active
55 //! keyboard grab. When running in Xwayland, X11 applications may
56 //! acquire an active grab inside Xwayland but that cannot be translated
57 //! to the Wayland compositor who may set the input focus to some other
58 //! surface. In doing so, it breaks the X11 client assumption that all
59 //! key events are reported to the grabbing client.
60 //!
61 //! This protocol specifies a way for Xwayland to request all keyboard
62 //! be directed to the given surface. The protocol does not guarantee
63 //! that the compositor will honor this request and it does not
64 //! prescribe user interfaces on how to handle the respond. For example,
65 //! a compositor may inform the user that all key events are now
66 //! forwarded to the given client surface, or it may ask the user for
67 //! permission to do so.
68 //!
69 //! Compositors are required to restrict access to this application
70 //! specific protocol to Xwayland alone.
71
72 /// Unstable version 1
73 pub mod zv1 {
74 wayland_protocol!(
75 "./protocols/unstable/xwayland-keyboard-grab/xwayland-keyboard-grab-unstable-v1.xml",
76 []
77 );
78 }
79}
80