Module xdg 

Available on crate feature wayland_frontend only.

Utilities for handling shell surfaces with the xdg_shell protocol

This module provides automatic handling of shell surfaces objects, by being registered as a global handler for xdg_shell.

Why use this implementation

This implementation can track for you the various shell surfaces defined by the clients by handling the xdg_shell protocol.

It allows you to easily access a list of all shell surfaces defined by your clients access their associated metadata and underlying wl_surfaces.

This handler only handles the protocol exchanges with the client to present you the information in a coherent and relatively easy to use manner. All the actual drawing and positioning logic of windows is out of its scope.

How to use it

Initialization

To initialize this handler, create XdgShellState, store it in your State struct and implement the XdgShellHandler, as shown in this example:

use smithay::delegate_xdg_shell;
use smithay::reexports::wayland_server::protocol::{wl_seat, wl_surface};
use smithay::wayland::shell::xdg::{XdgShellState, XdgShellHandler, ToplevelSurface, PopupSurface, PositionerState};
use smithay::utils::Serial;

let xdg_shell_state = XdgShellState::new::<State>(
    &display.handle(),
);

// insert the xdg_shell_state into your state
// ...

// implement the necessary traits
impl XdgShellHandler for State {
    fn xdg_shell_state(&mut self) -> &mut XdgShellState {
        &mut self.xdg_shell_state
    }

    // handle the shell requests here.
    // more optional methods can be used to further customized
    fn new_toplevel(&mut self, surface: ToplevelSurface) {
        // ...
    }
    fn new_popup(
        &mut self,
        surface: PopupSurface,
        positioner: PositionerState,
    ) {
        // ...
    }
    fn grab(
        &mut self,
        surface: PopupSurface,
        seat: wl_seat::WlSeat,
        serial: Serial,
    ) {
        // ...
    }
    fn reposition_request(
        &mut self,
        surface: PopupSurface,
        positioner: PositionerState,
        token: u32,
    ) {
        // ...
    }
}

use smithay::input::{Seat, SeatState, SeatHandler, pointer::CursorImageStatus};

type Target = wl_surface::WlSurface;
impl SeatHandler for State {
    type KeyboardFocus = Target;
    type PointerFocus = Target;
    type TouchFocus = Target;

    fn seat_state(&mut self) -> &mut SeatState<Self> {
        &mut self.seat_state
    }

    fn focus_changed(&mut self, seat: &Seat<Self>, focused: Option<&Target>) {
        // handle focus changes, if you need to ...
    }
    fn cursor_image(&mut self, seat: &Seat<Self>, image: CursorImageStatus) {
        // handle new images for the cursor ...
    }
}
delegate_xdg_shell!(State);

// You're now ready to go!

Access to shell surface and clients data

There are mainly 3 kind of objects that you’ll manipulate from this implementation:

• ShellClient: This is a handle representing an instantiation of a shell global you can associate client-wise metadata to it through an UserDataMap.
• ToplevelSurface: This is a handle representing a toplevel surface, you can retrieve a list of all currently alive toplevel surface from the XdgShellState.
• PopupSurface: This is a handle representing a popup/tooltip surface. Similarly, you can get a list of all currently alive popup surface from the XdgShellState.

You’ll obtain these objects though two means: either via the callback methods of the XdgShellHandler, or via methods on the XdgShellState.

Modules

decoration

XDG Window decoration manager

dialog

XDG Dialog Windows

Structs

PopupCachedState

Represents the xdg_popup pending state

PopupConfigure

A configure message for popup surface

PopupState

Represents the state of the popup

PopupSurface

A handle to a popup surface

PositionerState

The state of a positioner, as set by the client

ShellClient

A shell client

SurfaceCachedState

Represents the client pending state

ToplevelCachedState

Represents the xdg_toplevel pending state

ToplevelConfigure

A configure message for toplevel surfaces

ToplevelState

State of a regular toplevel surface

ToplevelStateSet

Container holding the states for a XdgToplevel

ToplevelSurface

A handle to a toplevel surface

WmCapabilitySet

Container holding the xdg_toplevel::WmCapabilities for a toplevel

XdgPopupSurfaceRoleAttributes

Role specific attributes for xdg_popup

XdgPositionerUserData

User data for Xdg Positioner

XdgShellState

Shell global state

XdgShellSurfaceUserData

User data of xdg toplevel surface

XdgSurfaceUserData

User data of XdgSurface

XdgToplevelSurfaceRoleAttributes

Role specific attributes for xdg_toplevel

XdgWmBaseUserData

User data for Xdg Wm Base

Enums

Configure

Defines the possible configure variants for a XdgSurface that will be issued in the user_impl for notifying about a ack_configure

PopupConfigureError

Represents the possible errors that can be returned from PopupSurface::send_configure

Constants

XDG_POPUP_ROLE

The role of an XDG popup surface.

XDG_TOPLEVEL_ROLE

The role of an XDG toplevel surface.

Traits

XdgShellHandler

Xdg Shell handler type

Type Aliases

XdgPopupSurfaceData

Data associated with XDG popup surface

XdgToplevelSurfaceData

Data associated with XDG toplevel surface