diff --git a/src/kstartupinfo.h b/src/kstartupinfo.h
--- a/src/kstartupinfo.h
+++ b/src/kstartupinfo.h
@@ -120,6 +120,8 @@
      * or a new one, before being shown. Note that this function is usually
      * needed only when a window is reused.
      * @deprecated since 5.62, use setNewStartupId(QWindow *) instead
+     * Note: if all you have is a QWidget*, you might need to call
+     * setAttribute(Qt::WA_NativeWindow, true); before calling window()->windowHandle().
      */
 #ifndef KWINDOWSYSTEM_NO_DEPRECATED
     KWINDOWSYSTEM_DEPRECATED static void setNewStartupId(QWidget *window, const QByteArray &startup_id);
diff --git a/src/kwindowsystem.h b/src/kwindowsystem.h
--- a/src/kwindowsystem.h
+++ b/src/kwindowsystem.h
@@ -224,6 +224,20 @@
      */
     static void setOnActivities(WId win, const QStringList &activities);
 
+    /**
+     * Sets the parent window of @p subwindow to be @p mainwindow.
+     * This overrides the parent set the usual way as the QWidget or QWindow parent,
+     * but only for the window manager - e.g. stacking order and window grouping
+     * will be affected, but features like automatic deletion of children
+     * when the parent is deleted are unaffected and normally use
+     * the QObject parent.
+     *
+     * This function should be used before a dialog is shown for a window
+     * that belongs to another application.
+     */
+    static void setMainWindow(QWindow *subwindow, WId mainwindow);
+
+#ifndef KWINDOWSYSTEM_NO_DEPRECATED
     /**
      * Sets the parent window of @p subwindow to be @p mainwindow.
      * This overrides the parent set the usual way as the QWidget parent,
@@ -234,9 +248,12 @@
      *
      * This function should be used before a dialog is shown for a window
      * that belongs to another application.
+     * @deprecated since 5.62, use setMainWindow(QWindow *). If all you have is a QWidget*,
+     * you might need to call setAttribute(Qt::WA_NativeWindow, true); before calling
+     * >window()->windowHandle().
      */
-    static void setMainWindow(QWidget *subwindow, WId mainwindow);
-#ifndef KWINDOWSYSTEM_NO_DEPRECATED
+    KWINDOWSYSTEM_DEPRECATED static void setMainWindow(QWidget *subwindow, WId mainwindow);
+
     /**
      * Returns the WM_TRANSIENT_FOR property for the given window, i.e. the mainwindow
      * for this window.
diff --git a/src/kwindowsystem.cpp b/src/kwindowsystem.cpp
--- a/src/kwindowsystem.cpp
+++ b/src/kwindowsystem.cpp
@@ -455,30 +455,39 @@
     d->demandAttention(win, set);
 }
 
+static QWindow* setMainWindowHelper(QWindow *subWindow, WId mainWindowId)
+{
+    QWindow *mainWindow = QWindow::fromWinId(mainWindowId);
+    if (mainWindow) { // foreign windows not supported on all platforms
+        subWindow->setTransientParent(mainWindow);
+    }
+    return mainWindow;
+}
+
 #ifndef KWINDOWSYSTEM_NO_DEPRECATED
 WId KWindowSystem::transientFor(WId win)
 {
     Q_D(KWindowSystem);
     return d->transientFor(win);
 }
-#endif
 
 void KWindowSystem::setMainWindow(QWidget *subWidget, WId mainWindowId)
 {
     // Set the WA_NativeWindow attribute to force the creation of the QWindow.
     // Without this QWidget::windowHandle() returns 0.
     subWidget->setAttribute(Qt::WA_NativeWindow, true);
     QWindow *subWindow = subWidget->windowHandle();
     Q_ASSERT(subWindow);
+    QWindow *mainWindow = setMainWindowHelper(subWindow, mainWindowId);
 
-    QWindow *mainWindow = QWindow::fromWinId(mainWindowId);
-    if (!mainWindow) {
-        // foreign windows not supported on all platforms
-        return;
-    }
     // mainWindow is not the child of any object, so make sure it gets deleted at some point
     connect(subWidget, &QObject::destroyed, mainWindow, &QObject::deleteLater);
-    subWindow->setTransientParent(mainWindow);
+}
+#endif
+
+void KWindowSystem::setMainWindow(QWindow *subWindow, WId mainWindowId)
+{
+    (void) setMainWindowHelper(subWindow, mainWindowId);
 }
 
 #ifndef KWINDOWSYSTEM_NO_DEPRECATED