wayland-client 0.21.13

Bindings to the standard C implementation of the wayland protocol, client side.
Documentation
Client-side Wayland connector ## Overview This crate provides the interfaces and machinery to safely create client applications for the wayland protocol. It is a rust wrapper around the `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 `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 `Proxy<_>` objects, receiving and handling them is done by providing implementations. ### Proxies Wayland protocol objects are represented in this crate by `Proxy` objects, where `I` is a type representing the interface of the considered object. And 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"). To do so, you need to import the appropriate extension trait adding these methods. For example, to use a `Proxy`, you need to import `protocol::wl_surface::RequestsTrait` from this crate. It is also possible to directly use the `Proxy::::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 `Proxy` instances and protocol objects. Rather, you can think of `Proxy` as an `Rc`-like handle to a wayland object. Multiple instances of it can exist referring to the same protocol object. Similarly, the lifetimes of the protocol objects and the `Proxy` 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 `Proxy` still refers to it. In such case, these proxies will be disabled and their `alive()` method will start to return `false`. Trying to send messages with them will also fail. ### Implementations 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 receive a `NewProxy` object. Providing an implementation via its `implement()` method will turn it into a regular `Proxy` object. **All objects must be implemented**, even if it is an implementation doing nothing. Failure to do so (by dropping the `NewProxy` for example) can cause future fatal errors if the server tries to send an event to this object. An implementation is just an `FnMut(I::Event, Proxy), where `I` is the interface of the considered object. ## 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 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 `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. ## Auxiliary libraries Two auxiliary libraries are also available behind cargo features: - the `cursor` feature will try to load `libwayland-cursor.so`, a library helping with loading system themed cursor textures, to integrate your app in the system theme. - the `egl` feature 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 The `eventloop` cargo feature adds the necessary implementations to use an `EventQueue` as a `calloop` event source. If you want to use it, here are a few points to take into account: - The `EventQueue` will not call its associated callback, but rather manage all the event dispatching internally. As a result, there is no point registering it to `calloop` with anything other than a dummy callback. - You still need to call `Display::flush()` yourself between `calloop`s dispatches, or in the `EventLoop::run()` callback of `calloop`.