Expand description

Utilities for binding globals with wl_registry in delegates.

This module is based around the RegistryHandler trait and RegistryState.

RegistryState provides an interface to bind globals regularly, creating an object with each new instantiation or caching bound globals to prevent duplicate object instances from being created. Binding a global regularly is accomplished through RegistryState::bind_one.

The delegate_registry macro is used to implement handling for wl_registry.

Sample implementation of RegistryHandler

use smithay_client_toolkit::reexports::client::{
    Connection, Dispatch, QueueHandle,
    delegate_dispatch,
    globals::GlobalList,
    protocol::wl_output,
};

use smithay_client_toolkit::registry::{
    GlobalProxy, ProvidesRegistryState, RegistryHandler, RegistryState,
};

struct ExampleApp {
    /// The registry state is needed to use the global abstractions.
    registry_state: RegistryState,
    /// This is a type we want to delegate global handling to.
    delegate_that_wants_registry: Delegate,
}

/// The delegate a global should be provided to.
struct Delegate {
    outputs: Vec<wl_output::WlOutput>,
}

// When implementing RegistryHandler, you must be able to dispatch any type you could bind using the registry state.
impl<D> RegistryHandler<D> for Delegate
where
    // In order to bind a global, you must statically assert the global may be handled with the data type.
    D: Dispatch<wl_output::WlOutput, ()>
        // ProvidesRegistryState provides a function to access the RegistryState within the impl.
        + ProvidesRegistryState
        // We need some way to access our part of the application's state.  This uses AsMut,
        // but you may prefer to create your own trait to avoid making .as_mut() ambiguous.
        + AsMut<Delegate>
        + 'static,
{
  /// New global added after initial enumeration.
   fn new_global(
       data: &mut D,
       conn: &Connection,
       qh: &QueueHandle<D>,
       name: u32,
       interface: &str,
       version: u32,
   ) {
        if interface == "wl_output" {
            // Bind `wl_output` with newest version from 1 to 4 the compositor supports
            let output = data.registry().bind_specific(qh, name, 1..=4, ()).unwrap();
            data.as_mut().outputs.push(output);
        }

        // You could either handle errors here or when attempting to use the interface.  Most
        // Wayland protocols are optional, so if your application can function without a
        // protocol it should try to do so; the From impl of GlobalProxy is written to make
        // this straightforward.
    }
}

Structs

Enums

Traits

  • Trait which asserts a data type may provide a mutable reference to the registry state.
  • A trait implemented by modular parts of a smithay’s client toolkit and protocol delegates that may be used to receive notification of a global being created or destroyed.