Integration

  1. Introduction
  2. Panels
    1. waybar
    2. sfwbar
    3. xfce4-panel
    4. yambar
    5. 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.

At the time of writing some common toolkits do not have full support for wlr-layer-shell, most notably GTK4 and Qt <6.5. In order to integrate components written in these eco-systems in the short/medium term, window rules can be used to achieve a reasonable setup. Please note though that the use of window-rules is a sub-optimal solution which relies on user configuration and does not always support per-output configuration.

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",
    },

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

xfce4-panel repository

Just after the release of Xfce 4.18 in Dec 2022, Wayland support was added (MR103) to xfce4-panel including the layer-shell and foreign-toplevel-management protocols.

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

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

Until the next release, you can get it going by cloning the master branch and building with the following (adjusting prefix to suit your system of course):

./autogen --prefix=/usr
make
make install

On Arch Linux you can simply install the following packages: xfce4-dev-tools, libxfce4util, libxfce4ui, libxfce4windowing-devel and xfce4-panel-git.

2.4 yambar

yambar repository

Configure yambar in the ~/.config/yambar/config.yml. Yambar configuration uses the yaml language.

Read the yambar documentation for further information.

2.5 lxqt-panel

Since version 2.0.0, lxqt-panel supports the wlr-layer-shell protocol and thus runs natively under Wayland without window rules. Should you have an older version, it can still be used with a window rule such as:

<windowRules>
  <windowRule identifier="lxqt-panel" matchOnce="true" fixedPosition="yes">
    <skipTaskbar>yes</skipTaskbar>
    <action name="MoveTo" x="0" y="0" />
    <action name="ToggleAlwaysOnTop"/>
  </windowRule>
</windowRules>

Note: lxqt-panel does not support wlr-foreign-toplevel-management so the taskbar does not work.

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)" - | swappy -f -
grim - | wl-copy

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 like Fcitx5 and IBus provide modules for GTK and Qt and an interface for xserver (xwayland) using D-Bus without wayland protocols.

You can enable input method for those platforms by setting environment variables like this:

export GTK_IM_MODULE=fcitx
export QT_IM_MODULE=fcitx
export XMODIFIERS=@im=fcitx

For apps not running on those platforms (e.g. Alacritty), labwc supports the following wayland protocols in the master branch:

Here is a quick guide for using Fcitx5 in labwc:

  1. Install fcitx5, GTK/Qt modules, configtool and language-specific module.

    • Arch Linux: pacman -S fcitx5-im fcitx5-mozc
    • Ubuntu: apt install fcitx5 fcitx5-mozc

    Replace fcitx5-mozc with a module for your language.

  2. Set GTK_IM_MODULE, QT_IM_MODULE and XMODIFIERS like described earlier. These are usually saved in files like ~/.config/labwc/environment, ~/.profile and /etc/environment.

  3. Start fcitx5. You can automatically start fcitx5 by adding fcitx5 & to ~/.config/labwc/autostart.

  4. Configure Fcitx5 with configtool to enable the installed language-specific module and to set up hotkeys. See Configtool (Fcitx 5) - Fcitx.

  5. Activate input method with hotkeys while typing in applications.

Input method on Chromium

Chromium (and Electron-based) apps don’t support the text-input-v3 protocol at this point. So if you want to use IME with Chromium under labwc, you have following options:

  1. Run Chromium under XWayland

    This is the default option. However, some features like touchpad gesture don’t work.

  2. Use GTK IM Module

    By running Chromium with --enable-features=UseOzonePlatform --ozone-platform=wayland --gtk-version=4, you can enable IME with GTK IM Module (selected by GTK_IM_MODULE) under wayland. However, IME popups might be incorrectly positioned.

  3. Patch labwc and use text-input-v1 protocol

    Since text-input-v1 is an outdated protocol, labwc doesn’t officially support it. However, you can optionally add support for it by installing labwc from the unofficial AUR or by applying its patch. Then, you can enable IME with text-input-v1 by running Chromium with --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime.

12. GTK

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.