Wayland Interaction: GDK 3 Reference Manual

## Wayland Interaction Wayland Interaction — Wayland backend-specific functions |

## Functions

struct wl_seat * | gdk_wayland_seat_get_wl_seat ()
struct wl_keyboard * | gdk_wayland_device_get_wl_keyboard ()
struct wl_pointer * | gdk_wayland_device_get_wl_pointer ()
struct wl_seat * | gdk_wayland_device_get_wl_seat ()
struct wl_compositor * | gdk_wayland_display_get_wl_compositor ()
struct wl_display * | gdk_wayland_display_get_wl_display ()
gboolean | gdk_wayland_display_query_registry ()
struct wl_surface * | gdk_wayland_window_get_wl_surface ()
void | gdk_wayland_window_set_use_custom_surface ()
void | (*GdkWaylandWindowExported) ()
gboolean | gdk_wayland_window_export_handle ()
void | gdk_wayland_window_unexport_handle ()
gboolean | gdk_wayland_window_set_transient_for_exported ()
void | gdk_wayland_window_add_frame_callback_surface ()
void | gdk_wayland_window_remove_frame_callback_surface ()

## Includes

    #include <gdk/gdkwayland.h>

## Description

The functions in this section are specific to the GDK Wayland backend. To use them, you need to include the `<gdk/gdkwayland.h>` header and use the Wayland-specific pkg-config files to build your application (either `gdk-wayland-3.0` or `gtk+-wayland-3.0`).

To make your code compile with other GDK backends, guard backend-specific calls by an ifdef as follows. Since GDK may be built with multiple backends, you should also check for the backend that is in use (e.g. by using the `GDK_IS_WAYLAND_DISPLAY()` macro).

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    #ifdef GDK_WINDOWING_WAYLAND
      if (GDK_IS_WAYLAND_DISPLAY (display))
        {
          // make Wayland-specific calls here
        }
      else
    #endif
    #ifdef GDK_WINDOWING_X11
      if (GDK_IS_X11_DISPLAY (display))
        {
          // make X11-specific calls here
        }
      else
    #endif
      g_error ("Unsupported GDK backend");

## Functions

### gdk_wayland_seat_get_wl_seat ()

    struct wl_seat *
    gdk_wayland_seat_get_wl_seat (GdkSeat *seat);

Returns the Wayland wl_seat of a GdkSeat.

#### Parameters

device | a GdkDevice. | [type GdkWaylandDevice]

#### Returns

a Wayland wl_seat.

[transfer none]

Since: 3.20

### gdk_wayland_device_get_wl_keyboard ()

    struct wl_keyboard *
    gdk_wayland_device_get_wl_keyboard (GdkDevice *device);

Returns the Wayland wl_keyboard of a GdkDevice.

#### Parameters

device | a GdkDevice. | [type GdkWaylandDevice]

#### Returns

a Wayland wl_keyboard.

[transfer none]

Since: 3.10

### gdk_wayland_device_get_wl_pointer ()

    struct wl_pointer *
    gdk_wayland_device_get_wl_pointer (GdkDevice *device);

Returns the Wayland wl_pointer of a GdkDevice.

#### Parameters

device | a GdkDevice. | [type GdkWaylandDevice]

#### Returns

a Wayland wl_pointer.

[transfer none]

Since: 3.10

### gdk_wayland_device_get_wl_seat ()

    struct wl_seat *
    gdk_wayland_device_get_wl_seat (GdkDevice *device);

Returns the Wayland wl_seat of a GdkDevice.

#### Parameters

device | a GdkDevice. | [type GdkWaylandDevice]

#### Returns

a Wayland wl_seat.

[transfer none]

Since: 3.10

### gdk_wayland_display_get_wl_compositor ()

    struct wl_compositor *
    gdk_wayland_display_get_wl_compositor (GdkDisplay *display);

Returns the Wayland global singleton compositor of a GdkDisplay.

#### Parameters

display | a GdkDisplay. | [type GdkWaylandDisplay]

#### Returns

a Wayland wl_compositor.

[transfer none]

Since: 3.8

### gdk_wayland_display_get_wl_display ()

    struct wl_display *
    gdk_wayland_display_get_wl_display (GdkDisplay *display);

Returns the Wayland wl_display of a GdkDisplay.

#### Parameters

display | a GdkDisplay. | [type GdkWaylandDisplay]

#### Returns

a Wayland wl_display.

[transfer none]

Since: 3.8

### gdk_wayland_display_query_registry ()

    gboolean
    gdk_wayland_display_query_registry (GdkDisplay *display,
                                        const gchar *global);

Returns `TRUE` if the the interface was found in the display wl_registry.global handler.

#### Parameters

display | a wayland GdkDisplay |
interface | global interface to query in the registry |

#### Returns

`TRUE` if the global is offered by the compositor

Since: 3.22.27

### gdk_wayland_window_get_wl_surface ()

    struct wl_surface *
    gdk_wayland_window_get_wl_surface (GdkWindow *window);

Returns the Wayland surface of a GdkWindow.

#### Parameters

window | a GdkWindow. | [type GdkWaylandWindow]

#### Returns

a Wayland wl_surface.

[transfer none]

Since: 3.8

### gdk_wayland_window_set_use_custom_surface ()

    void
    gdk_wayland_window_set_use_custom_surface
                                   (GdkWindow *window);

Marks a GdkWindow as a custom Wayland surface. The application is expected to register the surface as some type of surface using some Wayland interface.

A good example would be writing a panel or on-screen-keyboard as an out-of-process helper - as opposed to having those in the compositor process. In this case the underlying surface isn’t an xdg_shell surface and the panel or OSK client need to identify the wl_surface as a panel or OSK to the compositor. The assumption is that the compositor will expose a private interface to the special client that lets the client identify the wl_surface as a panel or such.

This function should be called before a GdkWindow is shown. This is best done by connecting to the “realize” signal:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    static void
    widget_realize_cb (GtkWidget *widget)
    {
      GdkWindow *window;
      struct wl_surface *surface;
      struct input_panel_surface *ip_surface;

      window = gtk_widget_get_window (widget);
      gdk_wayland_window_set_custom_surface (window);

      surface = gdk_wayland_window_get_wl_surface (window);
      ip_surface = input_panel_get_input_panel_surface (input_panel, surface);
      input_panel_surface_set_panel (ip_surface);
    }

    static void
    setup_window (GtkWindow *window)
    {
      g_signal_connect (window, "realize", G_CALLBACK (widget_realize_cb), NULL);
    }

#### Parameters

window | a GdkWindow. | [type GdkWaylandWindow]

Since: 3.10

### GdkWaylandWindowExported ()

    void
    (*GdkWaylandWindowExported) (GdkWindow *window,
                                 const char *handle,
                                 gpointer user_data);

Callback that gets called when the handle for a window has been obtained from the Wayland compositor. The handle can be passed to other processes, for the purpose of marking windows as transient for out-of-process surfaces.

#### Parameters

window | the GdkWindow that is exported |
handle | the handle |
user_data | user data that was passed to `gdk_wayland_window_export_handle()` |

Since: 3.22

### gdk_wayland_window_export_handle ()

    gboolean
    gdk_wayland_window_export_handle (GdkWindow *window,
                                      GdkWaylandWindowExported callback,
                                      gpointer user_data,
                                      GDestroyNotify destroy_func);

Asynchronously obtains a handle for a surface that can be passed to other processes. When the handle has been obtained, `callback` will be called.

Up until 3.22.15 it was an error to call this function on a window that is already exported. When the handle is no longer needed, `gdk_wayland_window_unexport_handle()` should be called to clean up resources.

Starting with 3.22.16, calling this function on an already exported window will cause the callback to be invoked with the same handle as was already invoked, from an idle callback. To unexport the window, `gdk_wayland_window_unexport_handle()` must be called the same number of times as `gdk_wayland_window_export_handle()` was called. Any 'exported' callback may still be invoked until the window is unexported or destroyed.

The main purpose for obtaining a handle is to mark a surface from another window as transient for this one, see `gdk_wayland_window_set_transient_for_exported()`.

Note that this API depends on an unstable Wayland protocol, and thus may require changes in the future.

#### Parameters

window | the GdkWindow to obtain a handle for |
callback | callback to call with the handle |
user_data | user data for `callback` |
destroy_func | destroy notify for `user_data` |

#### Returns

`TRUE` if the handle has been requested, `FALSE` if an error occurred.

Since: 3.22

### gdk_wayland_window_unexport_handle ()

    void
    gdk_wayland_window_unexport_handle (GdkWindow *window);

Destroys the handle that was obtained with `gdk_wayland_window_export_handle()`.

It is an error to call this function on a window that does not have a handle.

Note that this API depends on an unstable Wayland protocol, and thus may require changes in the future.

#### Parameters

window | the GdkWindow to unexport |

Since: 3.22

### gdk_wayland_window_set_transient_for_exported ()

    gboolean
    gdk_wayland_window_set_transient_for_exported
                                   (GdkWindow *window,
                                    char *parent_handle_str);

Marks `window` as transient for the surface to which the given `parent_handle_str` refers. Typically, the handle will originate from a `gdk_wayland_window_export_handle()` call in another process.

Note that this API depends on an unstable Wayland protocol, and thus may require changes in the future.

#### Parameters

window | the GdkWindow to make as transient |
parent_handle_str | an exported handle for a surface |

#### Returns

`TRUE` if the window has been marked as transient, `FALSE` if an error occurred.

Since: 3.22

### gdk_wayland_window_add_frame_callback_surface ()

    void
    gdk_wayland_window_add_frame_callback_surface
                                   (GdkWindow *window,
                                    struct wl_surface *surface);

Add `surface` to a list of surfaces for which frame callback listeners will get set up, additionally to the one of `window` .

This is useful when clients use subsurfaces independently of GDK. For example if a client creates a subsurface that covers `window` entirely. If this subsurface is opaque, Wayland compositors may not emit callbacks for the surface of `window` any more. Adding the covering subsurface via this function ensures the `window` will continue to update.

A single callback is sufficient to trigger the next update. If more than one are triggered, the later ones will get ignored.

Before `surface` gets destroyed it must get removed again using `gdk_wayland_window_remove_frame_callback_surface()`.

Note that the client is responsible to commit the `surface` . One way to archive this is to always commit after the “after-paint” signal was triggered.

#### Parameters

window | the GdkWindow requesting callbacks |
surface | the wl_surface to add |

Since: 3.24.25

### gdk_wayland_window_remove_frame_callback_surface ()

    void
    gdk_wayland_window_remove_frame_callback_surface
                                   (GdkWindow *window,
                                    struct wl_surface *surface);

Remove `surface` from the list of surfaces again that got added via `gdk_wayland_window_add_frame_callback_surface()`.

This function must be called before `surface` gets destroyed.

#### Parameters

window | the GdkWindow requesting callbacks |
surface | the surface to remove |

Since: 3.24.25