Integration

  1. Introduction
  2. Panels
    1. waybar
    2. sfwbar
    3. xfce4-panel
    4. lxqt-panel
  3. Menu Generators
  4. CSD
  5. Output Management
  6. Screenshots
  7. Session Lock
  8. Desktops
  9. Qt
  10. Clipboard
  11. Input Method
  12. Gtk

1. Introduction

This document describes how clients (not part of the labwc project) can be used with labwc to create a Desktop Environment. It does not attempt to describe in detail how to setup and use those other clients, but merely sign-posts to them and gives some simple hints to get started.

There are two protocols in particularly that are fundamental in integrating desktop components and that will be referred to through this document namely: wlr-layer-shell and wlr-foreign-toplevel-management.

wlr-layer-shell allows surfaces to be assigned to a “layer” with a defined z-depth and also to be anchored to the edges/corners of a screen.

wlr-foreign-toplevel-management provides clients such as taskbars and docks with a list of opened applications and supports requests for certain actions such as maximizing, etc.

2. Panels

There are a variety of wayland panels available for labwc ranging from simple to complex. Below are some that you can try.

Most panels are started from the ~/.config/labwc/autostart file like so:

mypanel >/dev/null 2>&1 &

See the autostart documentation for further information.

2.1 waybar

waybar repository

Add these two sections to enable a taskbar through the toplevel-foreign protocol to the ~/.config/waybar/config file:

"modules-left": ["wlr/taskbar"],
    "wlr/taskbar": {
        "format": "{app_id}",
        "on-click": "minimize-raise",
    },

From waybar 0.14.0 the ext-workspace protocol is supported and can be configured like this:

"modules-right": ["ext/workspaces"],
"ext/workspaces": {
    "format": "{name}",
    "sort-by-number": true,
    "on-click": "activate",
},

See the waybar documentation for further information.

2.2 sfwbar

sfwbar repository

Configure sfwbar in the ~/.config/sfwbar/sfwbar.config file.

The default config will mostly work however for more information see the sfwbar man page.

sfwbar/config contains example config files (with file extension .config) which can be used by merely copying them to ~/.config/sfwbar/sfwbar.config.

See example configuration here.

2.3 xfce4-panel

Since Xfce 4.20, Wayland support has included wlr-layer-shell and wlr-foreign-toplevel-management protocols.

For the time being it is best to force all plugins to run as internal with:

xfconf-query -c xfce4-panel -p /force-all-internal -t bool -s true --create

2.4 lxqt-panel

Since version 2.0.0, lxqt-panel supports the wlr-layer-shell protocol and thus runs natively under Wayland.

With version >=2.1.0 the wlr-foreign-toplevel-management is supported enabling taskbar functionality and thereby making this an excellent choice.

3. Menu Generators

Several menu-generators exist to automatically create a menu.xml with system applications:

They are typically used like this:

labwc-menu-generator > ~/.config/labwc/menu.xml

Some of them support several menu formats, in which case you have to specify openbox format.

4. Client Side Decoration (CSD)

4.1 gsettings

Labwc is designed to use Server Side Decoration (SSD) for windows, but does support CSD. If you prefer to use CSD or use GTK applications which will not surrender their CSD, such as nautilus, you may wish to manage some CSD properties using gsettings and associated gsettings-desktop-schemas.

For example, to display minimize, maximize and close buttons, rather than just the default close, issue the following command:

gsettings set org.gnome.desktop.wm.preferences button-layout ":minimize,maximize,close"

To also show a client-menu button, run this command:

gsettings set org.gnome.desktop.wm.preferences button-layout "menu:minimize,maximize,close"

4.2 Firefox

Firefox prefers CSD by default. In order to disable CSD, take the following steps:

5. Output Management

To most users the term ‘output’ refers to the physical display(s) used.

A good starting point for managing wayland outputs is to use wlr-randr which is tool similar to xrandr for X11.

Use wlr-randr to get your output names and associated properties such as mode, position, scale and transform by simply running:

wlr-randr

There is not configuration file for wlr-randr, but you can use to configure outputs from the command line like this:

wlr-randr --output DP-1 --mode 1920x1080@144.001007Hz

Note: Use all the frequency (Hz) decimals when specifying a mode

If you prefer to have display (output) configuration automatically selected, try kanshi which supports directive definitions (in ~/.config/kanshi/config) like this:

profile {
  output HDMI-A-1 position 1366,0
  output eDP-1 position 0,0
}

6. Screenshots

Screenshots can be taken using the wlr-screencopy protocol via applications such as grim.

Grim is a commandline tool which can be combined with other clients, for example

grim -g "$(slurp)"
grim -g "$(slurp)" - | swappy -f -
grim - | wl-copy

Note: Remember to use quotation marks around $(slurp)

7. Session Lock

labwc supports the ext-session-lock and ext-idle-notify protocols and you can use clients such as swaylock to lock your session.

It is common to want to lock the session/screen after a period of inactivity. This can be achieved by using swayidle as follows:

swayidle -w \
    timeout 300 'swaylock -f -c 000000' \
    timeout 600 'wlopm --off \*' \
    resume 'wlopm --on \*' \
    before-sleep 'swaylock -f -c 000000' >/dev/null 2>&1 &

Note that in the context of idle system power management, it is NOT a good idea to turn off displays by ‘disabling outputs’ for example by wlr-randr --output <whatever> --off because this re-arranges views. Instead use a wlr-output-power-management client such as wlopm

chayang is a small Wayland client which gradually dims the screen. This is useful for setting up a grace period before turning off the screens. You can use it with swayidle by changing the timeout arguments to:

'chayang && swaylock -f'

8. Desktops

LXQt

Since version 2.0.0, pcmanfm-qt --desktop supports the wlr-layer-shell protocol, and thus runs natively without window-rules.

Older version can be run with the rule below in rc.xml:

<windowRules>
  <windowRule title="pcmanfm-desktop*">
    <skipTaskbar>yes</skipTaskbar>
    <skipWindowSwitcher>yes</skipWindowSwitcher>
    <action name="MoveTo" x="0" y="0" />
    <action name="ToggleAlwaysOnBottom"/>
  </windowRule>
</windowRules>

Also, consider tweaking the following in Desktop Preferences:

Conky

Conky, starting with version 1.19.6, has the ability to run as a true Wayland application. Not all of the functionality of the X11 version is available, notably the ability to use lua as it’s X11 based. It uses waylands layer shell, and by default shows across all workspaces. Config file should have something like this:

out_to_x = false,
out_to_wayland = true,

9. Qt

To run Qt applications on Wayland it may be necessary to install a specific qt6-wayland package from the distribution repositories. For examples on Arch Linux, install qt6-wayland.

You may use qt6ct to configure Qt6 settings such as theme, font and icons; and set QT_QPA_PLATFORMTHEME=qt6ct in ~/.config/labwc/environment.

10. Clipboard

Labwc does not store clipboard contents after an application quits. For this functionality you need a clipboard manager.

For example, you could add a line similar to this to ~/.config/labwc/autostart:

wl-paste --watch cliphist store &

This uses cliphist and wl-clipboard. Other clipboard managers include clapboard and clipse.

Many clipboard managers have features beyond just keeping the clipboard alive. See the documentation of the individual tools for further information.

11. Input Method

Input methods (e.g. Fcitx5, IBus) intercepts text inputs in applications and compose them to other forms, like Chinese/Japanese/Korean or accented characters.

Fcitx5

Fcitx5 can be started with the command fcitx5. Use fcitx5-configtool to set up hotkeys and enable language-specific modules (e.g. fcitx5-mozc).

IBus

IBus can be started with the command ibus start --type=wayland. Use ibus-setup to set up hotkeys and enable language-specific modules (e.g. ibus-anthy).

12. Gtk

12.1 File Chooser

In some recent GTK (>=4.16) applications (e.g. Gnome’s Simple-Scan and Clapper) the File Chooser defaults to using xdg-portal technology which may not work depending on your system setup. There are at least two ways to fallback to a ‘normal’ File Chooser:

  1. Set the environment variable GDK_DEBUG=no-portals (in for example $HOME/.config/labwc/environment)
  2. Create a portal configuration file in the current user home based on labwc-portals.conf and add the line org.freedesktop.impl.portal.FileChooser=none to it. The location of this file should typically be $HOME/.config/xdg-desktop-portal/ but please see portal-user-home for further details.

12.2 Compose

From version 4.20.0, compose keys (e.g. typing “à” with “`” + “a” in US-intl layout) do not work in GTK4 applications without using input methods like Fcitx5 and IBus. See #3068 for details.