Client-side Wayland connector
This crate provides the interfaces and machinery to safely create
client applications for the Wayland protocol. It can be used as a rust
implementation of the protocol or as a wrapper around the system-wide
libwayland-client.so if you enable the
use_system_lib cargo feature.
The Wayland protocol revolves around the creation of various objects
and the exchange of messages associated to these objects. The initial
object is always the
Display, that you get at initialization of the
connection, exposed by this crate as
The protocol being bi-directional, you can send and receive messages. Sending messages is done via methods of Rust objects corresponding to the wayland protocol objects, receiving and handling them is done by providing callbacks.
Wayland objects are represented by proxies, which are handles to them. You can interact with them in 4 states:
- As the interface object directly
I. This representation is the most immediate one. It allows you to send requests though this object and can be send accross threads.
- As a
Proxy<I>. This representation is suitable if you want to access the proxy as a proxy, rather than a wayland object. You can convert between
Intotraits, and get a
- As a
Main<I>. This represents a main handle to this proxy, and allows you greater control of the object, but cannot be shared accros threads. This handle allows you to assign filters to the object, and send requests that create new objects.
- As an
Attached<I>. If you use more than one event queue (see below), this allows you to control on which event queue the children object are created.
There is not a 1 to 1 mapping between Rust object instances and protocol
objects. Rather, you can think of the Rust objects as
Rc-like handles to a
Wayland object. Multiple instances of a Rust object can exist referring to the same
Similarly, the lifetimes of the protocol objects and the Rust objects are
not tightly tied. As protocol objects are created and destroyed by protocol
messages, it can happen that an object gets destroyed while one or more
Rust objects still refer to it. In such case, these Rust objects will be disabled
alive() method on the underlying
Proxy<I> will start to return
Sending requests on dead objects will be silently ignored. And if these requests would create new objects, these objects will be created dead.
Your wayland objects can receive events from the server, which need to be processed.
To do so, you can assign
Filters to your object. These are specially wrapped closure
so that several objects can be assigned to the same
Filter, to ease state sharing
between the code handling different objects.
If an object is not assigned to any
Filter, its events will instead be delivered to the
fallback closure given to its event queue when dispatching it.
The Wayland client machinery provides the possibility to have one or more event queues handling the processing of received messages. All Wayland objects are associated to an event queue, which controls when its events are dispatched.
Events received from the server are stored in an internal buffer, and processed (by calling the appropriate callbacks) when the associated event queue is dispatched.
When you send a request creating a new object, this new object will be assigned to an event queue depending on the parent object that created it.
- If the request was sent from a
Main<I>handle, the child object will be assigned to the same event queue as its parent.
- If the request was sent from an
Attached<I>handle, the child object will be assigned to the event queue its parent has been attached to.
At the beginning you'll need to create an event queue and assign the initial
If you need to gracefully handle the case of a system on which Wayland is not installed (by
fallbacking to X11 for example), you can do so by activating the
dlopen cargo feature.
When this is done, the library will be loaded a runtime rather than directly linked. And trying
to create a
Display on a system that does not have this library will return a
Generate an enum joining several objects events
Convenience macro to create a
A handle to a proxy that has been attached to an event queue
Holder of global dispatch-related data
A connection to a wayland server
An event queue for protocol messages
An event filter
An utility to manage global objects
A main handle to a proxy
A protocol error
An handle to a wayland proxy
A token representing this event queue
An generic event
A guard over a read intention.
A wrapper for user data, able to store any type, and correctly handling access from a wrong thread
Enum of possible argument in an event
Enum representing the possible reasons why connecting to the wayland server failed
An error that occurred trying to bind a global
Event provided to the user callback of GlobalManager
An empty enum representing a MessageGroup with no messages
This type only exists for type-level compatibility with the rust implementation.
A trait for implementation of the global advertisement
The description of a wayland interface
A group of messages