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.