Struct smithay_client_toolkit::environment::Environment

pub struct Environment<E> {
    pub manager: GlobalManager,
    // some fields omitted
}

A Wayland Environment

This struct is generated by the environment! macro, see module-level documentation for more details about this.

This is the central point for accessing globals for your Wayland app. Any global that has previously been declared in the environment! macro can be access from this type via the get_global, required_global and get_all_globals methods.

This Environment is a handle that can be cloned.

Fields

manager: GlobalManager

The underlying GlobalManager, if you need to do manual interaction with the registry. See wayland-client documentation for details.

Implementations

impl<E> Environment<E> where
    E: GlobalHandler<WlDataDeviceManager>, 

pub fn new_data_source<F>(
    &self,
    mime_types: Vec<String>,
    callback: F
) -> DataSource where
    F: FnMut(DataSourceEvent, DispatchData<'_>) + 'static, 

Create a new data source

This data source is the basic object for offering content to other clients, be it for clipboard selection or as drag’n’drop content.

Once this source is created, you will need to give it to a DataDevice to start interaction.

impl<E> Environment<E> where
    E: DataDeviceHandling, 

pub fn set_data_device_callback<F: FnMut(WlSeat, DndEvent<'_>, DispatchData<'_>) + 'static>(
    &mut self,
    callback: F
) -> Result<(), ()>

Set the data device callback

This callback will be invoked whenever some drag’n’drop action is done onto one of your surfaces.

You should set it before entering your main loop, to ensure you will not miss any events.

Returns an error if the compositor did not advertise a data device capability.

pub fn with_data_device<F: FnOnce(&DataDevice)>(
    &self,
    seat: &WlSeat,
    f: F
) -> Result<(), ()>

Access the data device associated with a seat

Returns an error if the seat is not found (for example if it has since been removed by the server) or if the wl_data_device_manager global is missing.

impl<E: InnerEnv + 'static> Environment<E>

pub fn new(
    display: &Attached<WlDisplay>,
    queue: &mut EventQueue,
    env: E
) -> Result<Environment<E>>

Create new Environment

This requires access to a wl_display attached to the event_queue. You also need to provide an instance of the inner environment type declared using the environment! macro.

If you instead used the default_environment!, then you need to initialize your Environment using the new_default_environment! macro.

std::io::Error could be returned if initial roundtrips to the server failed.

If this call indefinitely blocks when doing initial roundtrips this can only be caused by server bugs.

pub fn new_pending(display: &Attached<WlDisplay>, env: E) -> Environment<E>

Create new pending Environment

This requires access to a wl_display attached to an event queue (on which the main SCTK logic will be attached). You also need to provide an instance of the inner environment type declared using the environment! macro.

If you instead used the default_environment!, then you need to initialize your Environment using the new_default_environment! macro.

You should prefer to use Environment::new, unless you want to control initialization manually or you create additional environment meaning that the initialization may be fine with just dispatch_pending of the event queue, instead of two roundtrips to fully initialize environment. If you manually initialize your environment two sync roundtrips are required.

impl<E> Environment<E>

pub fn get_global<I: Interface>(&self) -> Option<Attached<I>> where
    E: GlobalHandler<I>, 

Access a “single” global

This method allows you to access any “single” global that has previously been declared in the environment! macro. It is forwarded to the get() method of the appropriate GlobalHandler.

It returns None if the global has not (yet) been signaled by the registry.

pub fn require_global<I: Interface>(&self) -> Attached<I> where
    E: GlobalHandler<I>, 

Access a “single” global or panic

This method is similar to get_global, but will panic with a detailed error message if the requested global was not advertized by the server.

pub fn get_all_globals<I: Interface>(&self) -> Vec<Attached<I>> where
    E: MultiGlobalHandler<I>, 

Access all instances of a “multi” global

This will return a Vec containing all currently existing instances of the requested “multi” global that has been previously declared in the environment! macro. It is forwarded to the get_all() method of the appropriate MultiGlobalHandler.

pub fn with_inner<T, F: FnOnce(&mut E) -> T>(&self, f: F) -> T

Access the inner environment

This gives your access, via a closure, to the inner type you declared via the environment! or default_environment! macro.

This method returns the return value of your closure.

impl<E: OutputHandling> Environment<E>

pub fn listen_for_outputs<F: FnMut(WlOutput, &OutputInfo, DispatchData<'_>) + 'static>(
    &self,
    f: F
) -> OutputStatusListener

Insert a new listener for outputs

The provided closure will be invoked whenever a wl_output is created or removed.

Note that if outputs already exist when this callback is setup, it’ll not be invoked on them. For you to be notified of them as well, you need to first process them manually by calling .get_all_outputs().

The returned OutputStatusListener keeps your callback alive, dropping it will disable it.

impl<E: MultiGlobalHandler<WlOutput>> Environment<E>

pub fn get_all_outputs(&self) -> Vec<WlOutput>

Shorthand method to retrieve the list of outputs

impl<E: PrimarySelectionHandling> Environment<E>

pub fn get_primary_selection_manager(
    &self
) -> Option<PrimarySelectionDeviceManager>

Get the best available primary selection device manager protocol.

Returns None if no primary selection device manager was advertised.

pub fn with_primary_selection<F: FnOnce(&PrimarySelectionDevice)>(
    &self,
    seat: &WlSeat,
    f: F
) -> Result<(), ()>

Access the primary selection associated with a seat.

Returns an error if the seat is not found (for example if it has since been removed by the server) of if the zwp_primary_selection_device_manager_v1 or gtk_primary_selection_device_manager globals are missing.

pub fn new_primary_selection_source<F>(
    &self,
    mime_types: Vec<String>,
    callback: F
) -> PrimarySelectionSource where
    F: FnMut(PrimarySelectionSourceEvent, DispatchData<'_>) + 'static, 

Create a new primary selection source.

This primary selection source is the basic object for offering primary selection clipboard to other clients.

Once this source is created, you will need to give it to a PrimarySelectionDevice to start interaction.

impl<E: SeatHandling> Environment<E>

pub fn listen_for_seats<F: FnMut(Attached<WlSeat>, &SeatData, DispatchData<'_>) + 'static>(
    &self,
    f: F
) -> SeatListener

Insert a new listener for seats

The provided closure will be invoked whenever a wl_seat is made available, removed, or see its capabilities changed.

Note that if seats already exist when this callback is setup, it’ll not be invoked on them. For you to be notified of them as well, you need to first process them manually by calling .get_all_seats().

The returned SeatListener keeps your callback alive, dropping it will disable it.

impl<E: MultiGlobalHandler<WlSeat>> Environment<E>

pub fn get_all_seats(&self) -> Vec<Attached<WlSeat>>

Shorthand method to retrieve the list of seats

impl<E: ShellHandling> Environment<E>

pub fn get_shell(&self) -> Option<Shell>

Get the best available shell protocol

Returns None if no shell was advertised.

pub fn create_shell_surface<F>(
    &self,
    surface: &WlSurface,
    f: F
) -> Box<dyn ShellSurface> where
    F: FnMut(Event, DispatchData<'_>) + 'static, 

Create a new shell surface for this surface

This helper abstracts over the xdg_shell protocol and its precursors (zxdg_shell_v6 and wl_shell) for retro-compatibility. It’ll attempt to use them in this order.

You need to provide a closure that will process the events generated by the shell surface.

Panic

This function will panic if no supported shell was advertised by the compositor.

impl<E> Environment<E> where
    E: GlobalHandler<WlShm>, 

pub fn create_simple_pool<F>(&self, callback: F) -> Result<MemPool> where
    F: FnMut(DispatchData<'_>) + 'static, 

Create a simple memory pool

This memory pool track the usage of the buffers created from it, and invokes your callback when the compositor has finished using all of them.

pub fn create_double_pool<F>(&self, callback: F) -> Result<DoubleMemPool> where
    F: FnMut(DispatchData<'_>) + 'static, 

Create a double memory pool

This can be used for double-buffered drawing. The memory pool is backed by two different SHM segments, which are used in alternance.

The provided callback is triggered when one of the pools becomes unused again after you tried to draw while both where in use.

impl<E> Environment<E> where
    E: ShmHandling, 

pub fn shm_formats(&self) -> Vec<Format>

Access the list of SHM formats supported by the compositor

impl<E> Environment<E> where
    E: GlobalHandler<WlCompositor> + GlobalHandler<WlSubcompositor> + GlobalHandler<WlShm> + ShellHandling + MultiGlobalHandler<WlSeat> + GlobalHandler<ZxdgDecorationManagerV1> + SeatHandling, 

pub fn create_window<F: Frame + 'static, CB>(
    &self,
    surface: WlSurface,
    theme_manager: Option<ThemeManager>,
    initial_dims: (u32, u32),
    callback: CB
) -> Result<Window<F>, F::Error> where
    CB: FnMut(Event, DispatchData<'_>) + 'static, 

Create a new window wrapping given surface

This window handles decorations for you, this includes drawing them if the compositor doe snot support them, resizing interactions and moving the window. It also provides close/maximize/minimize buttons.

Many interactions still require your input, and are given to you via the callback you need to provide.

impl<E: GlobalHandler<WlCompositor>> Environment<E>

pub fn create_surface(&self) -> Attached<WlSurface>

Create a DPI-aware surface

This surface will track the outputs it is being displayed on, and compute the optimal scale factor for these. You can access them using get_surface_scale_factor and get_surface_outputs.

pub fn create_surface_with_scale_callback<F: FnMut(i32, WlSurface, DispatchData<'_>) + 'static>(
    &self,
    f: F
) -> Attached<WlSurface>

Create a DPI-aware surface with callbacks

This method is like create_surface, but the provided callback will also be notified whenever the scale factor of this surface change, if you don’t want to have to periodically check it.

Trait Implementations

impl<E> Clone for Environment<E>

fn clone(&self) -> Environment<E>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.