Gtk Layer Shell: gtk-layer-shell Reference Manual

## Gtk Layer Shell Gtk Layer Shell — A library to write GTK Applications using Layer Shell |

## Functions

guint | gtk_layer_get_major_version ()
guint | gtk_layer_get_minor_version ()
guint | gtk_layer_get_micro_version ()
gboolean | gtk_layer_is_supported ()
guint | gtk_layer_get_protocol_version ()
void | gtk_layer_init_for_window ()
gboolean | gtk_layer_is_layer_window ()
struct zwlr_layer_surface_v1 * | gtk_layer_get_zwlr_layer_surface_v1 ()
void | gtk_layer_set_namespace ()
const char * | gtk_layer_get_namespace ()
void | gtk_layer_set_layer ()
GtkLayerShellLayer | gtk_layer_get_layer ()
void | gtk_layer_set_monitor ()
GdkMonitor * | gtk_layer_get_monitor ()
void | gtk_layer_set_anchor ()
gboolean | gtk_layer_get_anchor ()
void | gtk_layer_set_margin ()
int | gtk_layer_get_margin ()
void | gtk_layer_set_exclusive_zone ()
int | gtk_layer_get_exclusive_zone ()
void | gtk_layer_auto_exclusive_zone_enable ()
gboolean | gtk_layer_auto_exclusive_zone_is_enabled ()
void | gtk_layer_set_keyboard_mode ()
GtkLayerShellKeyboardMode | gtk_layer_get_keyboard_mode ()
void | gtk_layer_set_keyboard_interactivity ()
gboolean | gtk_layer_get_keyboard_interactivity ()
void | gtk_layer_try_force_commit ()
void | gtk_layer_set_respect_close ()
gboolean | gtk_layer_get_respect_close ()

## Types and Values

enum | GtkLayerShellLayer
enum | GtkLayerShellEdge
enum | GtkLayerShellKeyboardMode

## Description

There is also a version of this library compatible with GTK4

### Forcing Window Size

If you wish to force your layer surface window to be a different size than it is by default:

    1
    2
    3
    gtk_widget_set_size_request (GTK_WIDGET (layer_gtk_window), width, height);
    // force the window to resize to the new request
    gtk_window_resize (layer_gtk_window, 1, 1);

If width or height is -1, the default is used for that axis. If the window is anchored to opposite edges of the output (see `gtk_layer_set_anchor()`), the size request is ignored. If you later wish to use the default window size, simply repeat the two calls but with both width and height as -1.

## Functions

### gtk_layer_get_major_version ()

    guint
    gtk_layer_get_major_version ();

#### Returns

the major version number of the GTK Layer Shell library

Since: 0.4

### gtk_layer_get_minor_version ()

    guint
    gtk_layer_get_minor_version ();

#### Returns

the minor version number of the GTK Layer Shell library

Since: 0.4

### gtk_layer_get_micro_version ()

    guint
    gtk_layer_get_micro_version ();

#### Returns

the micro/patch version number of the GTK Layer Shell library

Since: 0.4

### gtk_layer_is_supported ()

    gboolean
    gtk_layer_is_supported ();

May block for a Wayland roundtrip the first time it's called.

#### Returns

`TRUE` if the platform is Wayland and Wayland compositor supports the zwlr_layer_shell_v1 protocol.

Since: 0.5

### gtk_layer_get_protocol_version ()

    guint
    gtk_layer_get_protocol_version ();

May block for a Wayland roundtrip the first time it's called.

#### Returns

version of the zwlr_layer_shell_v1 protocol supported by the compositor or 0 if the protocol is not supported.

Since: 0.6

### gtk_layer_init_for_window ()

    void
    gtk_layer_init_for_window (GtkWindow *window);

Set the `window` up to be a layer surface once it is mapped. this must be called before the `window` is realized.

#### Parameters

window | A GtkWindow to be turned into a layer surface. |

### gtk_layer_is_layer_window ()

    gboolean
    gtk_layer_is_layer_window (GtkWindow *window);

#### Parameters

window | A GtkWindow that may or may not have a layer surface. |

#### Returns

if `window` has been initialized as a layer surface.

Since: 0.5

### gtk_layer_get_zwlr_layer_surface_v1 ()

    struct zwlr_layer_surface_v1 *
    gtk_layer_get_zwlr_layer_surface_v1 (GtkWindow *window);

#### Parameters

window | A layer surface. |

#### Returns

The underlying layer surface Wayland object

Since: 0.4

### gtk_layer_set_namespace ()

    void
    gtk_layer_set_namespace (GtkWindow *window,
                             char const*name_space);

Set the "namespace" of the surface.

No one is quite sure what this is for, but it probably should be something generic ("panel", "osk", etc). The `name_space` string is copied, and caller maintains ownership of original. If the window is currently mapped, it will get remapped so the change can take effect.

Default is "gtk-layer-shell" (which will be used if set to `NULL`)

#### Parameters

window | A layer surface. |
name_space | The namespace of this layer surface. |

### gtk_layer_get_namespace ()

    const char *
    gtk_layer_get_namespace (GtkWindow *window);

NOTE: this function does not return ownership of the string. Do not free the returned string. Future calls into the library may invalidate the returned string.

#### Parameters

window | A layer surface. |

#### Returns

a reference to the namespace property. If namespace is unset, returns the default namespace ("gtk-layer-shell"). Never returns `NULL`.

Since: 0.5

### gtk_layer_set_layer ()

    void
    gtk_layer_set_layer (GtkWindow *window,
                         GtkLayerShellLayer layer);

Set the "layer" on which the surface appears (controls if it is over top of or below other surfaces). The layer may be changed on-the-fly in the current version of the layer shell protocol, but on compositors that only support an older version the `window` is remapped so the change can take effect.

Default is `GTK_LAYER_SHELL_LAYER_TOP`

#### Parameters

window | A layer surface. |
layer | The layer on which this surface appears. |

### gtk_layer_get_layer ()

    GtkLayerShellLayer
    gtk_layer_get_layer (GtkWindow *window);

#### Parameters

window | A layer surface. |

#### Returns

the current layer.

Since: 0.5

### gtk_layer_set_monitor ()

    void
    gtk_layer_set_monitor (GtkWindow *window,
                           GdkMonitor *monitor);

Set the output for the window to be placed on, or `NULL` to let the compositor choose. If the window is currently mapped, it will get remapped so the change can take effect.

Default is `NULL`

#### Parameters

window | A layer surface. |
monitor | The output this layer surface will be placed on (`NULL` to let the compositor decide). |

### gtk_layer_get_monitor ()

    GdkMonitor *
    gtk_layer_get_monitor (GtkWindow *window);

NOTE: To get which monitor the surface is actually on, use `gdk_display_get_monitor_at_window()`.

#### Parameters

window | A layer surface. |

#### Returns

the monitor this surface will/has requested to be on, can be `NULL`.

[transfer none]

Since: 0.5

### gtk_layer_set_anchor ()

    void
    gtk_layer_set_anchor (GtkWindow *window,
                          GtkLayerShellEdge edge,
                          gboolean anchor_to_edge);

Set whether `window` should be anchored to `edge` .

- If two perpendicular edges are anchored, the surface with be anchored to that corner

- If two opposite edges are anchored, the window will be stretched across the screen in that direction

Default is `FALSE` for each GtkLayerShellEdge

#### Parameters

window | A layer surface. |
edge | A GtkLayerShellEdge this layer surface may be anchored to. |
anchor_to_edge | Whether or not to anchor this layer surface to `edge` . |

### gtk_layer_get_anchor ()

    gboolean
    gtk_layer_get_anchor (GtkWindow *window,
                          GtkLayerShellEdge edge);

#### Parameters

window | A layer surface. |

#### Returns

if this surface is anchored to the given edge.

Since: 0.5

### gtk_layer_set_margin ()

    void
    gtk_layer_set_margin (GtkWindow *window,
                          GtkLayerShellEdge edge,
                          int margin_size);

Set the margin for a specific `edge` of a `window` . Effects both surface's distance from the edge and its exclusive zone size (if auto exclusive zone enabled).

Default is 0 for each GtkLayerShellEdge

#### Parameters

window | A layer surface. |
edge | The GtkLayerShellEdge for which to set the margin. |
margin_size | The margin for `edge` to be set. |

### gtk_layer_get_margin ()

    int
    gtk_layer_get_margin (GtkWindow *window,
                          GtkLayerShellEdge edge);

#### Parameters

window | A layer surface. |

#### Returns

the size of the margin for the given edge.

Since: 0.5

### gtk_layer_set_exclusive_zone ()

    void
    gtk_layer_set_exclusive_zone (GtkWindow *window,
                                  int exclusive_zone);

Has no effect unless the surface is anchored to an edge. Requests that the compositor does not place other surfaces within the given exclusive zone of the anchored edge. For example, a panel can request to not be covered by maximized windows. See wlr-layer-shell-unstable-v1.xml for details.

Default is 0

#### Parameters

window | A layer surface. |
exclusive_zone | The size of the exclusive zone. |

### gtk_layer_get_exclusive_zone ()

    int
    gtk_layer_get_exclusive_zone (GtkWindow *window);

#### Parameters

window | A layer surface. |

#### Returns

the window's exclusive zone (which may have been set manually or automatically)

Since: 0.5

### gtk_layer_auto_exclusive_zone_enable ()

    void
    gtk_layer_auto_exclusive_zone_enable (GtkWindow *window);

When auto exclusive zone is enabled, exclusive zone is automatically set to the size of the `window` + relevant margin. To disable auto exclusive zone, just set the exclusive zone to 0 or any other fixed value.

NOTE: you can control the auto exclusive zone by changing the margin on the non-anchored edge. This behavior is specific to gtk-layer-shell and not part of the underlying protocol

#### Parameters

window | A layer surface. |

### gtk_layer_auto_exclusive_zone_is_enabled ()

    gboolean
    gtk_layer_auto_exclusive_zone_is_enabled
                                   (GtkWindow *window);

#### Parameters

window | A layer surface. |

#### Returns

if the surface's exclusive zone is set to change based on the window's size

Since: 0.5

### gtk_layer_set_keyboard_mode ()

    void
    gtk_layer_set_keyboard_mode (GtkWindow *window,
                                 GtkLayerShellKeyboardMode mode);

Sets if/when `window` should receive keyboard events from the compositor, see GtkLayerShellKeyboardMode for details.

Default is `GTK_LAYER_SHELL_KEYBOARD_MODE_NONE`

#### Parameters

window | A layer surface. |
mode | The type of keyboard interactivity requested. |

Since: 0.6

### gtk_layer_get_keyboard_mode ()

    GtkLayerShellKeyboardMode
    gtk_layer_get_keyboard_mode (GtkWindow *window);

#### Parameters

window | A layer surface. |

#### Returns

current keyboard interactivity mode for `window` .

Since: 0.6

### gtk_layer_set_keyboard_interactivity ()

    void
    gtk_layer_set_keyboard_interactivity (GtkWindow *window,
                                          gboolean interactivity);

`gtk_layer_set_keyboard_interactivity` has been deprecated since version 0.6 and should not be used in newly-written code.

Use `gtk_layer_set_keyboard_mode()` instead.

Whether the `window` should receive keyboard events from the compositor.

Default is `FALSE`

#### Parameters

window | A layer surface. |
interactivity | Whether the layer surface should receive keyboard events. |

### gtk_layer_get_keyboard_interactivity ()

    gboolean
    gtk_layer_get_keyboard_interactivity (GtkWindow *window);

`gtk_layer_get_keyboard_interactivity` has been deprecated since version 0.6 and should not be used in newly-written code.

Use `gtk_layer_get_keyboard_mode()` instead.

#### Parameters

window | A layer surface. |

#### Returns

if keyboard interactivity is enabled

Since: 0.5

### gtk_layer_try_force_commit ()

    void
    gtk_layer_try_force_commit (GtkWindow *window);

Commits a surface state if there's no pending commit scheduled by the GTK. You almost never need to call this; the only known case is when the surface is in a state where it does not receive frame callbacks and the regular deferred commit mechanism is unavailable.

#### Parameters

window | A layer surface. |

Since: 0.9

### gtk_layer_set_respect_close ()

    void
    gtk_layer_set_respect_close (GtkWindow *window,
                                 gboolean respect_close);

Compositors may send the `zwlr_layer_surface_v1.closed` event in some cases (such as when an output is destroyed). Prior to v0.10 this always triggered a GTK `delete-event` signal, which would destroy the window if not intercepted by application code. In v0.10+ this behavior is disabled by default, and can be turned back on by calling this function with `TRUE`. To handle the `.closed` event without destroying your window turn respect_close on and connect a `delete-event` listener that returns `TRUE`.

#### Parameters

window | A layer surface. |
respect_close | If to forward the .closed event to GTK. |

Since: 0.10

### gtk_layer_get_respect_close ()

    gboolean
    gtk_layer_get_respect_close (GtkWindow *window);

#### Parameters

window | A layer surface. |

#### Returns

if the respect_close behavior is enabled, see `gtk_layer_set_respect_close()`

Since: 0.10

## Types and Values

### enum GtkLayerShellLayer

#### Members

GTK_LAYER_SHELL_LAYER_BACKGROUND | The background layer. |
GTK_LAYER_SHELL_LAYER_BOTTOM | The bottom layer. |
GTK_LAYER_SHELL_LAYER_TOP | The top layer. |
GTK_LAYER_SHELL_LAYER_OVERLAY | The overlay layer. |
GTK_LAYER_SHELL_LAYER_ENTRY_NUMBER | Should not be used except to get the number of entries. (NOTE: may change in future releases as more entries are added) |

### enum GtkLayerShellEdge

#### Members

GTK_LAYER_SHELL_EDGE_LEFT | The left edge of the screen. |
GTK_LAYER_SHELL_EDGE_RIGHT | The right edge of the screen. |
GTK_LAYER_SHELL_EDGE_TOP | The top edge of the screen. |
GTK_LAYER_SHELL_EDGE_BOTTOM | The bottom edge of the screen. |
GTK_LAYER_SHELL_EDGE_ENTRY_NUMBER | Should not be used except to get the number of entries. (NOTE: may change in future releases as more entries are added) |

### enum GtkLayerShellKeyboardMode

#### Members

GTK_LAYER_SHELL_KEYBOARD_MODE_NONE | This window should not receive keyboard events. |
GTK_LAYER_SHELL_KEYBOARD_MODE_EXCLUSIVE | This window should have exclusive focus if it is on the top or overlay layer. |
GTK_LAYER_SHELL_KEYBOARD_MODE_ON_DEMAND | The user should be able to focus and unfocues this window in an implementation defined way. Not supported for protocol version < 4. |
GTK_LAYER_SHELL_KEYBOARD_MODE_ENTRY_NUMBER | Should not be used except to get the number of entries. (NOTE: may change in future releases as more entries are added) |