Problem

A typical Qt Widgets stay-on-top implementation changes Qt::WindowStaysOnTopHint and calls show() again:

window->setWindowFlag(Qt::WindowStaysOnTopHint, pinned);
window->show();

We have observed native window recreation on both Windows and macOS when toggling this flag. The hide/show and recreation cause visible flicker and require native window state to be rebound. On Windows, recreation can also cause frame position drift. Linux has not been verified.

#241 explored changing the Win32 topmost state directly in the example. The merged #243 fixes frame drift after an HWND recreation. An in-place stay-on-top operation would avoid recreation when only the stacking level needs to change.

Proposal

Could QWindowKit provide an explicit stay-on-top operation for managed windows, either as a window-agent method or a documented window attribute?

• Windows: update the existing HWND using SetWindowPos() with HWND_TOPMOST / HWND_NOTOPMOST.
• macOS: update the existing NSWindow level.
• Linux: investigate backend behavior before defining support or fallback semantics.

The requested state should be restored if the native window is recreated for another reason. The API should document that a native stacking change may not update Qt's windowFlags().

Expected behavior

On supported backends, repeatedly toggling stay-on-top should preserve window visibility, frame geometry, and native window identity without flicker.