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 appropriateDispatch::event()
method on theState
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()
and ObjectData
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 theObjectId
using theProxy::id()
method, and then using the [ObjectId::as_ptr()
] method.
Modules§
- Backend reexports
- Helpers for handling the initialization of an app
- Generated protocol definitions
Macros§
- A helper macro which delegates a set of
Dispatch
implementations for proxies to a static handler. - Macro used to override
Dispatch::event_created_child()
Structs§
- The Wayland connection
- An event queue
- A handle that temporarily pauses event processing on an
EventQueue
. - A handle representing an
EventQueue
, used to assign objects upon creation. - The
ObjectData
implementation used by Wayland proxies, integrating withDispatch
- A weak handle to a Wayland object
Enums§
- An error when trying to establish a Wayland connection.
- Wayland dispatching error
- An enum value in the protocol.
Traits§
- A trait for handlers of proxies’ events delivered to an
EventQueue
. - Trait representing a Wayland interface