Guidelines and HOWTOs/Wayland Porting Notes

This documents contains porting notes for Wayland. If you don't use the Plasma Wayland session as your daily driver, you can still test the behavior of your application on Wayland and fix the bugs. Check the KWin/Wayland wiki page and also this blog post by Martin.

Popup Menus

Chances are that many popup menus of your application will be misplaced on Wayland. This is because the compositor needs to know how to relate the QMenu's window with the main window of the application. This is done by setting a transient parent window on the QMenu. The easiest way to do so is ensuring that the menu is created with a parent widget:

// Don't
auto menu = new QMenu;
menu->popup(somePos);
// Do
auto menu = new QMenu(someParentWidget);
menu->popup(somePos);

// Don't
QMenu::exec(someActions, somePos);
// Do
QMenu::exec(someActions, somePos, nullptr, someParentWidget);

Embedding KParts

KXMLGui widgets can have "stand-alone" popup menus defined in the XML .rc file (i.e. <Menu> elements that are not children of other elements).

KXMLGui >= 5.35 has been fixed to use the QMainWindow of the application as parent of stand-alone menus. If your application is embedding a KPart widget, make sure you are not doing it wrong:

• Wrong: embed a part widget in a QDialog.
• Good: embed a part widget in a KParts::MainWindow and call createGUI() on the part.

Application Icon

On Wayland setWindowIcon() no longer works. This also means that currently is not possible to set a per-window icon (because the xdg-shell standard doesn't allow it). It is still possible to set the main application icon that will be shown in task managers and window decorations:

• The name of the application icon will be fetched from the .desktop file of the application.
• The name of the .desktop file must adhere to the reverse domain standard (e.g. org.kde.app.desktop).

Most of the KDE applications are already working fine because KAboutData takes care of all the necessary steps. If for some reason your application is not using KAboutData, you need to manually call QGuiApplication::setDesktopFileName().