f56d07aa47
This PR allows applications to activate themselves *if they provide
a valid xdg_activation token* (e.g. raise to the top and get keyboard
focus).
These tokens are given out by the xdg_activation protocol implemented
by wlroots and can be configured by the client requesting the token
in three ways:
- an "empty" token
(apparently used to tell the compositor about "urgency")
- seat / input serial attached
- surface attached
Wlroots makes sure that
- If the client attached the seat / input serial: those two are valid.
- If the client attached a surface: that it has keyboard focus at the
point where the request is finalized. There is a patch [1] pending
for backport to wlroots 0.16 that also allows valid tokens when the
supplied surface had cursor focus.
- a token is only valid for 30 seconds after being given out
The token can then be used by the client or given to other clients by
unspecified means (e.g. via environment variable or dbus) which then
may use the token on their own surface and request activation.
We only handle the actual request activation part:
- If the seat is set on the token we know wlroots validated seat and
input serial
- Thus, if no seat is set we deny the activation request so we don't
have windows suddenly popping up and taking over the keyboard focus
(focus stealing prevention)
- We should also check for the surface being set but we can't do that
with wlroots 0.16 as it will reset the surface to `NULL` when it is
destroyed (which is something that usually happens for
notifications). Once we move to wlroots 0.17.x we can add the
missing surface check because it provides a `new_token` signal.
We can use it to attach further details to the token which are then
verified later when we decide if we allow the activate request or
not.
With this PR in place the following setup should activate windows:
- launching an URL in foot should activate the target application if
it is already running, foot requests a proper token and then sets it
as `XDG_ACTIVATION_TOKEN` environment var before spawning `xdg-open`
- clicking on a `mako` notification with a `default` action defined
should request a proper token which is then given to the application
starting the notification and can thus be used to activate itself
This protocol is still very much in the process of being
implemented / finalized all over the place (e.g. GTK / QT / Firefox /
notification daemons, ..) but we should do our part and remove labwc
from the puzzle of potential issues causing this not to work.
[1]
|
||
|---|---|---|
| .github/workflows | ||
| docs | ||
| include | ||
| po | ||
| protocols | ||
| scripts | ||
| src | ||
| subprojects | ||
| .editorconfig | ||
| .gitattributes | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| meson.build | ||
| meson_options.txt | ||
| NEWS.md | ||
| README.md | ||
labwc
[Website] [Scope] [IRC Channel] [Release Notes]
- 1. Project Description
- 2. Build and Installation
- 3. Configuration
- 4. Theming
- 5. Usage
- 6. Integration
1. Project Description
1.1 What Is This?
Labwc stands for Lab Wayland Compositor, where lab can mean any of the following:
- sense of experimentation and treading new ground
- inspired by BunsenLabs and ArchLabs
- your favorite pet
Labwc is a wlroots-based window-stacking compositor for wayland, inspired by openbox.
It is light-weight and independent with a focus on simply stacking windows well and rendering some window decorations. It takes a no-bling/frills approach and says no to features such as icons (except window buttons), animations, decorative gradients and any other options not required to reasonably render common themes. It relies on clients for panels, screenshots, wallpapers and so on to create a full desktop environment.
Labwc tries to stay in keeping with wlroots and sway in terms of general approach and coding style.
Labwc has no reliance on any particular Desktop Environment, Desktop Shell or session. Nor does it depend on any UI toolkits such as Qt or GTK.
1.2 Why?
Firstly, we believe that there is a need for a simple Wayland window-stacking compositor which strikes a balance between minimalism and bloat approximately at the level where Window Managers like Openbox reside in the X11 domain. Most of the core developers are accustomed to low resource Desktop Environments such as Mate/XFCE or standalone Window Managers such as Openbox under X11. Labwc aims to make a similar setup possible under Wayland, with small and independent components rather than a large, integrated software eco-system.
Secondly, the Wayland community has achieved an amazing amount so far, and we want to help solve the unsolved problems to make Wayland viable for more people. We think that standardisation and de-fragmentation is a route to greater Wayland adoption, and wanting to play our part in this, Labwc only understands wayland-protocols & wlr-protocols, and it cannot be controlled with dbus, sway/i3/custom-IPC or other technology.
Thirdly, it is important to us that scope is tightly controlled so that the compositor matures to production quality. On the whole, we value robustness, reliability, stability and simplicity over new features. Coming up with new ideas and features is easy - maintaining and stabilising them is not.
Fourthly, we are of the view that a compositor should be boring in order to do its job well. In this regard we follow in the footsteps of metacity which describes itself as a "Boring window manager for the adult in you. Many window managers are like Marshmallow Froot Loops; Metacity is like Cheerios."
Finally, we think that an elegant solution to all of this does not need feel square and pixelated like something out of the 1990s, but should look contemporary and enable cutting-edge performance.
1.3 Why The Openbox Theme Specification?
In order to avoid reinventing configuration and theme syntaxes, the openbox 3.6 specification is used. This does not mean that labwc is an openbox clone but rather that configuration files will look and feel familiar.
Also, parsing GTK3+ and Qt themes for window decorations is very complicated, so using much simpler specs such as those used by openbox and xfwm makes sense for a compositor such as labwc, both in terms of implementation and for user modification.
Openbox spec is somewhat of a stable standard considering how long it has remained unchanged for and how wide-spread its adoption is by lightweight distributions such as LXDE, LXQt, BunsenLabs, ArchLabs, Mabox and Raspian. Some widely used themes (for example Numix and Arc) have built-in support.
We could have invented a whole new syntax, but that's not where we want to spend our effort.
1.4 Very High Level Scope
A lot of emphasis is put on code simplicity when considering features.
The main development effort is focused on producing a solid foundation for a stacking compositor rather than adding configuration and theming options.
See scope for full details on implemented features.
High-level summary of items that Labwc supports:
- Config files (rc.xml, autostart, environment, menu.xml)
- Theme files and xbm icons
- Basic desktop and client menus
- HiDPI
- wlroots protocols such as
output-management,layer-shellandforeign-toplevel - Optionally xwayland
Items which are not intended to be implemented:
- Icons (except window buttons)
- Animations
- Gradients for decoration and menus
- Any theme option not required to reasonably render common themes (it is amazing how few options are actually required).
1.5 Videos
| video link | date | content |
|---|---|---|
| Video (2:48) | 31-Oct-2022 | 0.6.0 release video |
| Video (1:10) | 05-Aug-2021 | window gymnastics, theming and waybar |
| Video (3:42) | 25-Feb-2021 | setting background and themes; xwayland/xdg-shell windows |
1.6 Screenshot
The obligatory screenshot:
2. Build and Installation
To build, simply run:
meson setup build/
meson compile -C build/
Run-time dependencies include:
- wlroots, wayland, libinput, xkbcommon
- libxml2, cairo, pango, glib-2.0
- xwayland, xcb (optional)
Build dependencies include:
- meson, ninja, gcc/clang
- wayland-protocols
Disable xwayland with meson -Dxwayland=disabled build/
For OS/distribution specific details see see wiki.
3. Configuration
For a step-by-step initial configuration guide, see getting-started
User config files are located at ${XDG_CONFIG_HOME:-$HOME/.config/labwc/}
with the following four files being used:
| file | man page |
|---|---|
| rc.xml | labwc-config(5), labwc-actions(5) |
| menu.xml | labwc-menu(5) |
| autostart | labwc(1) |
| environment | labwc-config(5) |
| themerc-override | labwc-theme(5) |
The example rc.xml has been kept simple. For all options and default values, see rc.xml.all
Configuration and theme files are reloaded on receiving SIGHUP
(e.g. killall -s SIGHUP labwc)
For keyboard settings, see environment and xkeyboard-config(7)
4. Theming
Themes are located at ~/.local/share/themes/\<theme-name\>/openbox-3/ or
equivalent XDG_DATA_{DIRS,HOME} location in accordance with freedesktop XDG
directory specification.
For full theme options, see labwc-theme(5) or the themerc example file.
For themes, search the internet for "openbox themes" and place them in
~/.local/share/themes/. Some good starting points include:
- https://github.com/addy-dclxvi/openbox-theme-collections
- https://github.com/the-zero885/Lubuntu-Arc-Round-Openbox-Theme
- https://bitbucket.org/archlabslinux/themes/
- https://github.com/BunsenLabs/bunsen-themes
5. Usage
./build/labwc [-s <command>]
NOTE: If you are running on NVIDIA, you will need the
nvidia-drm.modeset=1kernel parameter.
If you have not created an rc.xml config file, default bindings will be:
| combination | action |
|---|---|
alt-tab |
activate next window |
super-return |
alacritty |
alt-F3 |
bemenu |
alt-F4 |
close window |
super-a |
toggle maximize |
alt-mouse-left |
move window |
alt-mouse-right |
resize window |
alt-arrow |
move window to edge |
super-arrow |
resize window to fill half the output |
XF86_AudioLowerVolume |
amixer sset Master 5%- |
XF86_AudioRaiseVolume |
amixer sset Master 5%+ |
XF86_AudioMute |
amixer sset Master toggle |
XF86_MonBrightnessUp |
brightnessctl set +10% |
XF86_MonBrightnessDown |
brightnessctl set 10%- |
A root-menu can be opened by clicking on the desktop.
6. Integration
Suggested apps to use with labwc:
- Screen shooter: grim
- Screen recorder: wf-recorder
- Background image: swaybg
- Panel: waybar, yambar, lavalauncher, sfwbar
- Launchers: bemenu, fuzzel, wofi
- Output managers: wlopm, kanshi, wlr-randr
- Screen locker: swaylock
See integration for further details.