Client-side Wayland connector
This crate provides the interfaces and machinery to safely create
client applications for the Wayland protocol. It is a rust wrapper
libwayland-client.so C library.
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
Protocol and messages handling model
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 implementations.
The underlying representation of Wayland protocol objects in this crate is
I is the type of the considered Rust object. An object's interface (think "class"
in an object-oriented context) defines which messages it can send and receive.
These proxies are used to send messages to the server (in the Wayland context,
these are called "requests"). You usually don't use them directly, and instead call
methods on the Rust objects themselves, which invoke the appropriate
It is also possible to directly use the
Proxy::<I>::send(..) method, but
this should only be done carefully: using it improperly can mess the protocol
state and cause protocol errors, which are fatal to the connection (the server
will kill you).
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
Trying to send messages with them will also fail.
To receive and process messages from the server to you (in Wayland context they are
called "events"), you need to provide an
Implementation for each Wayland object
created in the protocol session. Whenever a new protocol object is created, you will
NewProxy<I> object. Providing an implementation via its
will turn it into a regular Rust object.
All objects must be implemented, even if it is an implementation doing nothing.
Failure to do so (by dropping the
NewProxy<I> for example) can cause future fatal
errors if the server tries to send an event to this object.
An implementation is a struct implementing the
EventHandler trait for the interface
of the considered object. Alternatively, an
FnMut(I::Event, I) closure can be
used with the
implement_closure() method, where
I is the interface
of the considered object.
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 implementations) when the associated event queue is dispatched.
A default event queue is created at the same time as the initial
Display, and by default
whenever a Wayland object is created, it inherits the queue of its parent (the object that sent
or receive the message that created the new object). It means that if you only plan to use the
default event queue, you don't need to worry about assigning objects to their queues.
See the documentation of
EventQueue for details about dispatching and integrating the event
queue into the event loop of your application. See the
Proxy::make_wrapper() method for
details about assigning objects to event queues.
Dynamic linking with
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
Two auxiliary libraries are also available behind cargo features:
cursorfeature will try to load
libwayland-cursor.so, a library helping with loading system themed cursor textures, to integrate your app in the system theme.
eglfeature will try to load
libwayland-egl.so, a library allowing the creation of OpenGL surface from Wayland surfaces.
Both of them will also be loaded at runtime if the
dlopen feature was provided. See their
respective submodules for details about their use.
Event Loop integration
eventloop cargo feature adds the necessary implementations to use an
calloop event source. If you want to use it, here are a few points to take into
EventQueuewill not call its associated callback, but rather manage all the event dispatching internally. As a result, there is no point registering it to
calloopwith anything other than a dummy callback.
- You still need to call
calloops dispatches, or in the