Crate wayland_client

source ·
Expand description

Interface for interacting with the Wayland protocol, client-side.

General concepts

This crate is structured around four main objects: the Connection and EventQueue structs, proxies (objects implementing the Proxy trait), and the Dispatch trait.

The Connection is the heart of this crate. It represents your connection to the Wayland server, and you’ll generally initialize it using the Connection::connect_to_env() method, which will attempt to open a Wayland connection following the configuration specified by the environment.

Once you have a Connection, you can create an EventQueue from it. This EventQueue will take care of processing events from the Wayland server and delivering them to your processing logic, in the form of a state struct with several Dispatch implementations (see below).

Each of the Wayland objects you can manipulate is represented by a struct implementing the Proxy trait. Those structs are automatically generated from the wayland XML protocol specification. This crate provides the types generated from the core protocol in the protocol module. For other standard protocols, see the wayland-protocols crate.

Event dispatching

The core event dispatching logic provided by this crate is built around the EventQueue struct. In this paradigm, receiving and processing events is a two-step process:

  • First, events are read from the Wayland socket. For each event, the backend figures out which EventQueue manages it, and enqueues the event in an internal buffer of that queue.
  • Then, the EventQueue empties its internal buffer by sequentially invoking the appropriate Dispatch::event() method on the State value that was provided to it.

The main goal of this structure is to make your State accessible without synchronization to most of your event-processing logic, to reduce the plumbing costs. See EventQueue’s documentation for explanations of how to use it to drive your event loop, and when and how to use multiple event queues in your app.

The Dispatch trait and dispatch delegation

In this paradigm, your State needs to implement Dispatch<O, _> for every Wayland object O it needs to process events for. This is ensured by the fact that, whenever creating an object using the methods on an other object, you need to pass a QueueHandle<State> from the EventQueue that will be managing the newly created object.

However, implementing all those traits on your own is a lot of (often uninteresting) work. To make this easier a composition mechanism is provided using the delegate_dispatch! macro. This way, another library (such as Smithay’s Client Toolkit) can provide generic Dispatch implementations that you can reuse in your own app by delegating those objects to that provided implementation. See the documentation of those traits and macro for details.

Getting started example

As an overview of how this crate is used, here is a commented example of a program that connects to the Wayland server and lists the globals this server advertised through the wl_registry:

use wayland_client::{protocol::wl_registry, Connection, Dispatch, QueueHandle};
// This struct represents the state of our app. This simple app does not
// need any state, but this type still supports the `Dispatch` implementations.
struct AppData;

// Implement `Dispatch<WlRegistry, ()> for our state. This provides the logic
// to be able to process events for the wl_registry interface.
//
// The second type parameter is the user-data of our implementation. It is a
// mechanism that allows you to associate a value to each particular Wayland
// object, and allow different dispatching logic depending on the type of the
// associated value.
//
// In this example, we just use () as we don't have any value to associate. See
// the `Dispatch` documentation for more details about this.
impl Dispatch<wl_registry::WlRegistry, ()> for AppData {
    fn event(
        _state: &mut Self,
        _: &wl_registry::WlRegistry,
        event: wl_registry::Event,
        _: &(),
        _: &Connection,
        _: &QueueHandle<AppData>,
    ) {
        // When receiving events from the wl_registry, we are only interested in the
        // `global` event, which signals a new available global.
        // When receiving this event, we just print its characteristics in this example.
        if let wl_registry::Event::Global { name, interface, version } = event {
            println!("[{}] {} (v{})", name, interface, version);
        }
    }
}

// The main function of our program
fn main() {
    // Create a Wayland connection by connecting to the server through the
    // environment-provided configuration.
    let conn = Connection::connect_to_env().unwrap();

    // Retrieve the WlDisplay Wayland object from the connection. This object is
    // the starting point of any Wayland program, from which all other objects will
    // be created.
    let display = conn.display();

    // Create an event queue for our event processing
    let mut event_queue = conn.new_event_queue();
    // And get its handle to associate new objects to it
    let qh = event_queue.handle();

    // Create a wl_registry object by sending the wl_display.get_registry request.
    // This method takes two arguments: a handle to the queue that the newly created
    // wl_registry will be assigned to, and the user-data that should be associated
    // with this registry (here it is () as we don't need user-data).
    let _registry = display.get_registry(&qh, ());

    // At this point everything is ready, and we just need to wait to receive the events
    // from the wl_registry. Our callback will print the advertised globals.
    println!("Advertised globals:");

    // To actually receive the events, we invoke the `roundtrip` method. This method
    // is special and you will generally only invoke it during the setup of your program:
    // it will block until the server has received and processed all the messages you've
    // sent up to now.
    //
    // In our case, that means it'll block until the server has received our
    // wl_display.get_registry request, and as a reaction has sent us a batch of
    // wl_registry.global events.
    //
    // `roundtrip` will then empty the internal buffer of the queue it has been invoked
    // on, and thus invoke our `Dispatch` implementation that prints the list of advertised
    // globals.
    event_queue.roundtrip(&mut AppData).unwrap();
}

Advanced use

Bypassing Dispatch

It may be that for some of your objects, handling them via the EventQueue is impractical. For example, if processing the events from those objects doesn’t require accessing some global state, and/or you need to handle them in a context where cranking an event loop is impractical.

In those contexts, this crate also provides some escape hatches to directly interface with the low-level APIs from wayland-backend, allowing you to register callbacks for those objects that will be invoked whenever they receive an event and any event queue from the program is being dispatched. Those callbacks are more constrained: they don’t get a &mut State reference, and must be threadsafe. See Proxy::send_constructor for details about how to assign such callbacks to objects.

Interaction with FFI

It can happen that you’ll need to interact with Wayland states accross FFI. A typical example would be if you need to use the raw-window-handle crate.

In this case, you’ll need to do it in two steps, by explicitly working with wayland-backend, adding it to your dependencies and enabling its client_system feature.

  • If you need to send pointers to FFI, you can retrive the *mut wl_proxy pointers from the proxies by first getting the ObjectId using the Proxy::id() method, and then using the ObjectId::as_ptr() method.
  • If you need to receive pointers from FFI, you need to first create a Backend from the *mut wl_display using the from_external_display() method (see wayland-backend docs), and then make it into a Connection using Connection::from_backend(). Similarly, you can make ObjectIds from the *mut wl_proxy pointers using ObjectId::from_ptr(), and then make the proxies using Proxy::from_id.

Modules

  • backend
    Backend reexports
  • globals
    Helpers for handling the initialization of an app
  • protocol
    Generated protocol definitions

Macros

Structs

Enums

Traits

  • Dispatch
    A trait for handlers of proxies’ events delivered to an EventQueue.
  • Proxy
    Trait representing a Wayland interface