Crate wayland_client

Expand description

Client-side Wayland connector

Overview

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 Display::connect_to_env().

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 callbacks.

Proxies

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. This representation is suitable if you want to access the proxy as a proxy, rather than a wayland object. You can convert between I and Proxy via the From and Into traits, and get a &Proxy from an I via the AsRef trait.
As a Main. 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. 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 protocol object.

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 and the alive() method on the underlying Proxy will start to return false.

Sending requests on dead objects will be silently ignored. And if these requests would create new objects, these objects will be created dead.

Filters

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.

Event Queues

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 handle, the child object will be assigned to the same event queue as its parent.
If the request was sent from an Attached 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 Proxy<WlDisplay> to it.

Dynamic linking with `libwayland-client.so`

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 NoWaylandLib error.