Enum ashpd::WindowIdentifier

#[non_exhaustive]
pub enum WindowIdentifier {
}

Most portals interact with the user by showing dialogs. These dialogs should generally be placed on top of the application window that triggered them. To arrange this, the compositor needs to know about the application window. Many portal requests expect a WindowIdentifier for this reason.

Under X11, the WindowIdentifier should have the form x11:XID, where XID is the XID of the application window in hexadecimal. Under Wayland, it should have the form wayland:HANDLE, where HANDLE is a surface handle obtained with the xdg-foreign protocol.

See also Parent window identifiers.

Usage

From an X11 XID

let identifier = WindowIdentifier::from_xid(212321);

/// Open some portals

From a Wayland Surface

The wayland feature must be enabled. The exported surface handle will be unexported on Drop.

// let wl_surface = some_surface;
// let identifier = WindowIdentifier::from_wayland(wl_surface).await;

/// Open some portals

Or using a raw wl_surface pointer

// let wl_surface_ptr = some_surface;
// let wl_display_ptr = corresponding_display;
// let identifier = WindowIdentifier::from_wayland_raw(wl_surface_ptr, wl_display_ptr).await;

/// Open some portals

With GTK 4

The feature gtk4 must be enabled. You can get a WindowIdentifier from a IsA<gtk4::Native> using WindowIdentifier::from_native

let widget = gtk4::Button::new();

let ctx = glib::MainContext::default();
ctx.spawn_async(async move {
    let identifier = WindowIdentifier::from_native(&widget.native().unwrap()).await;

    /// Open some portals
});

The constructor should return a valid identifier under both X11 and Wayland and fallback to the Default implementation otherwise.

Other Toolkits

If you have access to RawWindowHandle you can convert it to a WindowIdentifier with

let handle = RawWindowHandle::Xlib(XlibHandle::empty());
let identifier = WindowIdentifier::from_raw_handle(handle, None);

/// Open some portals

In case you don’t have access to a WindowIdentifier:

use ashpd::WindowIdentifier;

let identifier = WindowIdentifier::default();

Implementations

impl WindowIdentifier

pub async fn from_native(native: &impl IsA<Native>) -> Self

Available on crate features gtk4_wayland or gtk4_x11 only.

Creates a WindowIdentifier from a gtk4::Native.

The constructor returns a valid handle under both Wayland & x11.

Note the function has to be async as the Wayland handle retrieval API is async as well.

pub async fn from_raw_handle( window_handle: &RawWindowHandle, display_handle: Option<&RawDisplayHandle> ) -> Self

Available on crate feature raw_handle only.

Create an instance of WindowIdentifier from a RawWindowHandle.

The constructor returns a valid handle under both Wayland & X11.

This method is only async and requires a RawDisplayHandle only for Wayland handles.

pub fn from_xid(xid: c_ulong) -> Self

Create an instance of WindowIdentifier from an X11 window’s XID.

pub async unsafe fn from_wayland_raw( surface_ptr: *mut c_void, display_ptr: *mut c_void ) -> Self

Available on crate feature wayland only.

Create an instance of WindowIdentifier from a Wayland surface.

Safety

Both pointers have to be valid surface and display pointers. You must ensure the display_ptr lives longer than the returned WindowIdentifier.

pub async fn from_wayland(surface: &WlSurface) -> Self

Available on crate feature wayland only.

Create an instance of WindowIdentifier from a Wayland surface.

Trait Implementations

impl Debug for WindowIdentifier

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for WindowIdentifier

fn default() -> WindowIdentifier

Returns the “default value” for a type.

impl Display for WindowIdentifier

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl HasDisplayHandle for WindowIdentifier

fn display_handle(&self) -> Result<DisplayHandle<'_>, HandleError>

Convert a WindowIdentifier to RawDisplayHandle.

Panics

If you attempt to convert a WindowIdentifier created from a RawDisplayHandle instead of the gtk4 constructors.

impl HasWindowHandle for WindowIdentifier

fn window_handle(&self) -> Result<WindowHandle<'_>, HandleError>

Convert a WindowIdentifier to RawWindowHandle.

Panics

If you attempt to convert a WindowIdentifier created from a RawWindowHandle instead of the gtk4 constructors.

impl Serialize for WindowIdentifier

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Type for WindowIdentifier

fn signature() -> Signature<'static>

Get the signature for the implementing type.

impl Send for WindowIdentifier

impl Sync for WindowIdentifier