The documentation of Qt::Popup states:
Indicates that the widget is a pop-up top-level window, i.e. that it is modal, but has a window system frame appropriate for pop-up menus.
A QWindow that has the Qt::Popup flag set behaves inconsistently across the different desktop platforms, depending on how much of QWidget's popup behavior a QPA plugin tries to take care of.
macOS redirects all mouse events to the popup.
Windows and X11 do no such thing; all mouse events go to the QWindow under the mouse.
macOS directs any key event to the active popup.
Windows directs key events to the active window, the popup can be made active by clicking into it.
X11 never sends any key events to a popup window, they go to the transient parent. The popup never gets focus.
On macOS, transient parent and popup(s) sometimes share activation state. Clicking into the parent doesn't deactivate the popup, no WindowActivate/Deactivate events are generated. Activating another application deactivates the parent, but not the popup.
On Windows, clicking into a popup deactivates the titlebar of the transient parent, but Qt still considers the parent active (isActive is true for both parent and popup). WindowActivate/Deactivate events are generated for both popup and parent, even though the state doesn't change. Activating another application generates a Deactivate event only for the QWindow that was previously active (possibly only the popup).
On X11, a popup is always active and always on top, even if another application becomes active.
On macOS (until https://codereview.qt-project.org/c/qt/qtbase/+/369794), QWindow popups are automatically closed when clicking outside of them, including anywhere in the frame of another window in the same application.
On Windows and X11, popup QWindow are not closed automatically.
Given the documentation of Qt::Popup to imply:
- top level window
- window frame appropriate for popup menus (such as "no frame, but drop shadow)
The Popup flag should mean the following for QWindow on all platforms:
Modal means that other user interface elements cannot be interacted with as long as the popup is open. This means that the active popup should implicitly grab all mouse and keyboard input.
A popup is never a window on its own, it is an extension of the parent from which it is opened. Therefore, a popup should always be as active as the parent.
Popup type QWindows should by default close themselves when the user evidently wants to transfer input focus to another window. They should be closed when the application is deactivated, or when the user clicks the mouse outside of them.
This is in essence how QWidget and QApplication implement the Qt::Popup flag. QWidget::mousePressEvent closes itself when the mouse is pressed outside of it; QApplication handles deactivation events to close the entire popup stack.