GtkLayerShell

Library and Native bindings for Gtk Layer Shell, a library for creating panels and other desktop components for Wayland, using the Layer Shell protocol.

NAME

GtkLayerShell - A Raku module for interfacing with Gtk Layer Shell

DESCRIPTION

Provides a Raku interface for Gtk Layer Shell, a library for creating panels and other desktop components for Wayland, using the Layer Shell protocol.

SYNOPSIS

use GtkLayerShell:auth<zef:CIAvash>:api<0.6>;

# With Gnome::Gtk3 module
use Gnome::Gtk3::Main;
use Gnome::Gtk3::Window;
use Gnome::Gtk3::Box;
use Gnome::Gtk3::Label;

my Gnome::Gtk3::Main   $m          .= new;
my Gnome::Gtk3::Window $gtk_window .= new;

my $window = $gtk_window.get-native-object;

my GtkLayerShell $layer_surface .= new: :$window, :init,
                                        :layer(LAYER_OVERLAY)
                                        :anchors(:EDGE_LEFT, :EDGE_TOP),
                                        :margins(:EDGE_TOP(5), :EDGE_LEFT(10)),
                                        :exclusive_zone(50);

# Or
my $layer_surface = GtkLayerShell.new: :$window;
$layer_surface.init;
$layer_surface.set: :layer(LAYER_OVERLAY),
                    :anchors(:EDGE_LEFT, :EDGE_TOP),
                    :margins(:EDGE_TOP(5), :EDGE_LEFT(10)),
                    :name_space<panel>,
                    :auto_exclusive_zone

# Or
my $layer_surface = GtkLayerShell.new: :$window, :init;
$layer_surface.set_layer:  LAYER_OVERLAY;
$layer_surface.set_anchor: EDGE_TOP,  True;
$layer_surface.set_anchor: EDGE_LEFT, True;
$layer_surface.set_margin: EDGE_TOP,  10;
$layer_surface.set_margin: EDGE_LEFT, 10;

my $box = Gnome::Gtk3::Box.new;
$box.add: Gnome::Gtk3::Label.new: :text('Gtk Layer Shell!');

$gtk_window.add: $box;

$gtk_window.show-all;

$m.gtk-main;

# With GTK::Simple
use GTK::Simple;
use GTK::Simple::App;

my GTK::Simple::App $app .= new;

my GtkLayerShell $layer_surface .= new: :window($app.WIDGET), :init, :anchors(:EDGE_RIGHT, :EDGE_BOTTOM);

$app.set-content: GTK::Simple::HBox.new: GTK::Simple::Label.new: text => 'Gtk Layer Shell!';

$app.run;

INSTALLATION

You need to have Gtk Layer Shell and a Wayland compositor that works with it, Raku and zef, then run:

zef install "GtkLayerShell:auth<zef:CIAvash>:api<0.6>"

or if you have've cloned the repo:

zef install .

TESTING

prove -ve 'raku -I.' --ext rakutest

ATTRIBUTES

has GtkLayerShell::DefinedWindow $.window

A layer surface

has Bool:D $.init

Whether to initialize layer for window on instantiation

METHODS

method major_version

method major_version() returns Int:D

Returns the major version number of the GTK Layer Shell library

method minor_version

method minor_version() returns Int:D

Returns the minor version number of the GTK Layer Shell library

method micro_version

method micro_version() returns Int:D

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

method is_supported

method is_supported() returns Bool

Returns True if the platform is Wayland and Wayland compositor supports the zwlr_layer_shell_v1 protocol. May block for a Wayland roundtrip the first time it's called.

method protocol_version

method protocol_version() returns Int:D

Returns version of the zwlr_layer_shell_v1 protocol supported by the compositor or 0 if the protocol is not supported. May block for a Wayland roundtrip the first time it's called.

method init

method init() returns Mu

Sets the window up to be a layer surface once it is mapped. This must be called before the window is realized.

method set

method set(
    LayerShellLayer :$layer,
    Str :$name_space,
    GtkLayerShell::Native::Monitor :$monitor,
    :@anchors where .all ~~ Anchor,
    :@margins where .all ~~ Margin,
    Int :$exclusive_zone,
    Bool :$auto_exclusive_zone,
    LayerShellKeyboardMode :$keyboard_mode
) returns Mu

Sets multiple properties of the layer surface at once

PARAMETERS

Enum LayerShellLayer :$layer

The LayerShellLayer on which this surface appears

Str :$name_space

The namespace of this layer surface

GtkLayerShell::Native::Monitor :$monitor

The output this layer surface will be placed on (Any to let the compositor decide)

:@anchors where .all ~~ Anchor

Pairs of LayerShellEdge, Int to set margins of this layer suface's edges

:@margins where .all ~~ Anchor

Pairs of LayerShellEdge, Bool this layer suface may be anchored to

Int :$exclusive_zone

The size of the exclusive zone for this layer surface

Bool :$auto_exclusive_zone

Automatically set the size of exclusive zone for this layer surface

Enum LayerShellKeyboardMode :$keyboard_mode

The type of keyboard interactivity requested

method is_layer_window

method is_layer_window() returns Bool

Returns if window has been initialized as a layer surface.

method zwlr_layer_surface_v1

method zwlr_layer_surface_v1() returns GtkLayerShell::Native::ZwlrLayerSurfaceV1

Returns The underlying layer surface Wayland object

method set_namespace

method set_namespace(
    Str:D $name_space
) returns Mu

Sets the namespace of the surface. No one is quite sure what this is for, but it probably should be something generic ("panel", "osk", etc). If the window is currently mapped, it will get remapped so the change can take effect.

PARAMETERS

Str:D $name_space

The namespace of this layer surface

method get_namespace

method get_namespace() returns Str:D

Returns the namespace property. If namespace is unset, returns the default namespace ("gtk-layer-shell")

method set_layer

method set_layer(
    LayerShellLayer:D $layer
) returns Mu

Sets 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 LAYER_TOP

PARAMETERS

LayerShellLayer:D $layer

The layer on which this surface appears

method get_layer

method get_layer() returns LayerShellLayer:D

Returns the current layer

method set_monitor

method set_monitor(
    GtkLayerShell::Native::Monitor $monitor
) returns Mu

Sets the output for the window to be placed on, or Pointer type object to let the compositor choose. If the window is currently mapped, it will get remapped so the change can take effect.

Default behavior is to let the compositor choose

PARAMETERS

GtkLayerShell::Native::Monitor:D $monitor

The output this layer surface will be placed on

method get_monitor

method get_monitor() returns GtkLayerShell::Native::Monitor

Returns the monitor this surface will/has requested to be on, can be Pointer type object

NOTE: To get which monitor the surface is actually on, use gdk_get_monitor_at_window from a Gdk module.

method set_anchor

method set_anchor(
    LayerShellEdge:D $edge,
    Bool:D $anchor_to_edge
) returns Mu

Sets 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 LayerShellEdge

PARAMETERS

Enum LayerShellEdge:D $edge

A LayerShellEdge this layer suface may be anchored to

Bool:D $anchor_to_edge

Whether or not to anchor this layer surface to edge

method get_anchor

method get_anchor(
    LayerShellEdge:D $edge
) returns Bool

Returns if this surface is anchored to the given edge LayerShellEdge

method set_margin

method set_margin(
    LayerShellEdge:D $edge,
    Int:D $margin_size
) returns Mu

Sets 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 LayerShellEdge

PARAMETERS

Enum LayerShellEdge:D $edge

The LayerShellEdge for which to set the margin

Int:D $margin_size

The margin for edge to be set

method get_margin

method get_margin(
    LayerShellEdge:D $edge
) returns Int:D

Returns the size of the margin for the given edge LayerShellEdge

method set_exclusive_zone

method set_exclusive_zone(
    Int $exclusive_zone
) returns Mu

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

Int $exclusive_zone

The size of the exclusive zone

method get_exclusive_zone

method get_exclusive_zone() returns Int:D

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

method enable_auto_exclusive_zone

method enable_auto_exclusive_zone() returns Mu

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

method is_auto_exclusive_zone_enabled

method is_auto_exclusive_zone_enabled() returns Bool

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

method set_keyboard_mode

method set_keyboard_mode(
    LayerShellKeyboardMode:D $mode
) returns Mu

Sets if/when window should receive keyboard events from the compositor, see LayerShellKeyboardMode for details. Default is KEYBOARD_MODE_NONE

PARAMETERS

Enum LayerShellKeyboardMode:D $mode

The type of keyboard interactivity requested

method get_keyboard_mode

method get_keyboard_mode() returns LayerShellKeyboardMode:D

Returns current keyboard interactivity mode for window

REPOSITORY

https://github.com/CIAvash/GtkLayerShell/

BUG

https://github.com/CIAvash/GtkLayerShell/issues

AUTHOR

Siavash Askari Nasr - https://www.ciavash.name

COPYRIGHT

Copyright Ā© 2021 Siavash Askari Nasr

LICENSE

This file is part of GtkLayerShell.

GtkLayerShell is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

GtkLayerShell is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with GtkLayerShell. If not, see http://www.gnu.org/licenses/.

GtkLayerShell v0.1.0

Library and Native bindings for Gtk Layer Shell, a library for creating panels and other desktop components for Wayland, using the Layer Shell protocol.

Authors

  • Siavash Askari Nasr

License

LGPL-3.0-or-later

Dependencies

NativeLibs:auth<github:salortiz>:ver<0.0.9+>

Provides

  • GtkLayerShell
  • GtkLayerShell::Native

Documentation

The Camelia image is copyright 2009 by Larry Wall. "Raku" is trademark of the Yet Another Society. All rights reserved.