[][src]Crate wayland_client

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 Rust objects corresponding to the wayland protocol objects, receiving and handling them is done by providing implementations.

Proxies

The underlying representation of Wayland protocol objects in this crate is Proxy<I>, where 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 Proxy methods. 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 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<I> 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<I> object. Providing an implementation via its implement() method 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.

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:

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:

Modules

cursor

Cursor utilities

protocol
sinks

Message sinks

sys

C-associated types

Macros

event_enum

Generate an enum joining several objects events

global_filter

Convenience macro to create a GlobalManager callback

Structs

AnonymousObject

Anonymous interface

Display

A connection to a wayland server

EventQueue

An event queue for protocol messages

GlobalManager

An utility to manage global objects

NewProxy

A newly-created proxy that needs implementation

ProtocolError

A protocol error

Proxy

An handle to a wayland proxy

QueueToken

A token representing this event queue

ReadEventsGuard

A guard over a read intention.

Enums

ConnectError

Enum representing the possible reasons why connecting to the wayland server failed

GlobalError

An error that occurred trying to bind a global

GlobalEvent

Event provided to the user callback of GlobalManager

NoMessage

An empty enum representing a MessageGroup with no messages

ProxyMap

This type only exists for type-level compatibility with the rust implementation.

Traits

GlobalImplementor

A trait for implementation of the global advertisement

HandledBy

Provides a callback function to handle events of the implementing interface via T.

Interface

The description of a wayland interface

MessageGroup

A group of messages