Skip to content

Wayland support

Jump to bottom Edit New page
Daniel Kondor edited this page Mar 8, 2025 · 4 revisions

Wayland support

The beta version of Cairo-Dock (3.5.99) includes support for running on Wayland, under compositors that support the layer shell protocol. It has been tested with recent versions of Wayfire, labwc, KWin / KDE Plasma, Cosmic, sway and Hyprland. Note that GNOME Shell / Mutter, including the default Ubuntu desktop, is unfortunately not supported.

Requirements

Compilation: see the guide. Note that all optional dependencies are required. When configuring, the CMake summary should include the following:

--  * With EGL support    : yes (1.5)
--  * With Wayland support: yes (1.22.0)
--  * With Wayland taskbar: yes
--  * With Wayfire IPC    : yes
--  * With gtk-layer-shell: yes

To be usable, the following protocols need to be supported by the compositor:

Optionally, if using Wayfire, this plugin provides the "present windows" feature (when an icon with a group of windows is clicked).

Main features working

  • Dock positioning along a screen edge and keeping above / below and reserving space with the layer-shell protocol.
  • Proper positioning of subdocks, menus and dialogs.
  • Hardware acceleration with EGL.
  • Taskbar.
  • Hiding and recalling docks hidden or kept below.
  • Wayfire-specific features: custom protocol for recalling the dock, scale for "present windows", toggle menu feature.
  • KWin-specific features: workspaces, detecting if windows overlap the dock
  • Labwc-specific: basic support for workspaces (display and switching; cannot track which window is on which workspace)

Known issues and limitations

  • It is not possible to set global keyboard shortcuts for actions.
  • Subdocks disappear when an app is activated (this is a limitation of using xdg-popups; seems not the be an issue on KWin).
  • "Keep the dock below" option is buggy on KWin (at least version 5.24). See here for more info; testing on more recent KWin versions is very welcome!
  • Multi-monitor support is limited: docks can be placed only on a single screen.
  • Tracking virtual desktops / workspaces is only supported on KWin and Labwc (with some limitations).
  • EGL rendering under Wayland relies on an officially unsupported interface in GTK (i.e. it uses gtk_widget_set_double_buffered() which is only supported on X11); in practice it works well at least with GTK versions 3.22.30 -- 3.24.41 on recent versions of all compositors tested.
  • EGL / OpenGL does not work on older KWin versions (5.20). An error message complains about some layer-shell surfaces having a zero size set; this might be related to the above point. Run the dock with the -c switch.
  • Placement of desklets does not work; desklets behave as regular windows and need to be positioned manually (see below for an example).

Positioning desklets

This requires either manually setting a position, or setting up a "window rule" if your compositor has such a functionality. E.g. on Wayfire, you can use the window-rules plugin to set a default position for desklets and also to keep them on top (or below). E.g. to set a specific position for the "clock" plugin, add the following to the [window-rules] section of your wayfire.ini configuration:

cd_clock = on created if title is "cairo-dock-desklet-clock" then move 1100 40

Note: the window title of any desklet will start with "cairo-dock-desklet-" followed by the plugin name. This only set an initial position; you can still move the desklet to a new position by dragging it afterwards.

To make all desklets appear always on top and sticky (appear on all workspaces), add the following:

cd_desklet_on_top = on created if title contains "cairo-dock-desklet" then set always_on_top
cd_desklet_sticky = on created if title contains "cairo-dock-desklet" then set sticky

Supporting other compositors

For full functionality, Cairo-Dock requires support for two main features in a compositor:

  • window positioning
  • information on currently running apps

While these were available by default to any app on X11, this is not the case on Wayland (due to core design decisions to better separate running apps from each other). Individual compositors might provide these as specific extensions (custom protocols) or plugins. To provide a reasonable user experience in Cairo-Dock, some form of support from the compositor side for these will be necessary.

Window positioning

Currently, Cairo-Dock uses the layer-shell protocol, which is created to provide desktop shell functionality and is emerging as a standard for this purpose (see here for explicit standardization efforts). Layer-shell is based on the concept that the compositor works together with a client app (such as Cairo-Dock) to determine its position. However, this is not a strict requirement. An alternative could be a compositor automatically positioning docks without any involvement on the Cairo-Dock side. Several compositors already provide this kind of functionality, such as a "window rules" option or similar (or such functionality can be easily added as a plugin / addon).

Taskbar

Currently, Cairo-Dock needs to receive info about running apps from the compositor, and supports several protocols for this purpose. Adding support for additional compositors that use their custom protocol would be relatively easy. Similarly, some other IPC method could be used and will be considered as necessary. For a compositor that currently does not support any such method, writing an extension or plugin would be necessary of course. An alternative is to use Cairo-Dock's DBus interface to add icons that represent running apps. However, this would require at least some modifications to how the DBus interface works and of course a matching IPC plugin on the compositor side.

Add a custom footer
Add a custom sidebar
Clone this wiki locally