[][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 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<I>. 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<I> via the From and Into traits, and get a &Proxy<I> from an I via the AsRef trait.
  • 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 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.

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

Modules

protocol
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

Attached

A handle to a proxy that has been attached to an event queue

DispatchData

Holder of global dispatch-related data

Display

A connection to a wayland server

EventQueue

An event queue for protocol messages

Filter

An event filter

GlobalManager

An utility to manage global objects

Main

A main handle to a proxy

ProtocolError

A protocol error

Proxy

An handle to a wayland proxy

ProxyMap

A handle to the object map internal to the library state.

QueueToken

A token representing this event queue

RawEvent

An generic event

ReadEventsGuard

A guard over a read intention.

UserData

A wrapper for user data, able to store any type, and correctly handling access from a wrong thread

Enums

Argument

Enum of possible argument in an event

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

Traits

GlobalImplementor

A trait for implementation of the global advertisement

Interface

The description of a wayland interface

MessageGroup

A group of messages