From 5c7a3ea783b780bc5f924849091f1f3ffb4b892c Mon Sep 17 00:00:00 2001 From: Eskil Abrahamsen Blomfeldt Date: Fri, 17 Mar 2023 13:43:39 +0100 Subject: [PATCH] doc: Add note about platform support for window positions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit On some platforms, such as Wayland (and also eglfs), manual window positioning is not supported. Since this has caused confusion in the past, we add a note to the documentation. Pick-to: 6.2 6.5 Fixes: QTBUG-86780 Change-Id: Idf8dcdfad8ccfb9eb0f704fce05216562e433e20 Reviewed-by: Tor Arne Vestbø --- src/gui/kernel/qwindow.cpp | 8 ++++++++ src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc | 9 +++++++++ src/widgets/kernel/qwidget.cpp | 4 ++++ 3 files changed, 21 insertions(+) diff --git a/src/gui/kernel/qwindow.cpp b/src/gui/kernel/qwindow.cpp index 5a0fc79f30..39cbf0d734 100644 --- a/src/gui/kernel/qwindow.cpp +++ b/src/gui/kernel/qwindow.cpp @@ -1882,6 +1882,10 @@ void QWindow::setFramePosition(const QPoint &point) For interactively moving windows, see startSystemMove(). For interactively resizing windows, see startSystemResize(). + \note Not all windowing systems support setting or querying top level window positions. + On such a system, programmatically moving windows may not have any effect, and artificial + values may be returned for the current positions, such as \c QPoint(0, 0). + \sa position(), startSystemMove() */ void QWindow::setPosition(const QPoint &pt) @@ -1905,6 +1909,10 @@ void QWindow::setPosition(int posx, int posy) \fn QPoint QWindow::position() const \brief Returns the position of the window on the desktop excluding any window frame + \note Not all windowing systems support setting or querying top level window positions. + On such a system, programmatically moving windows may not have any effect, and artificial + values may be returned for the current positions, such as \c QPoint(0, 0). + \sa setPosition() */ diff --git a/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc b/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc index 192d05aff7..827f7981ae 100644 --- a/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc +++ b/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc @@ -115,6 +115,15 @@ depends on the result of QWidget::frameGeometry() and the capability of the window manager to do proper window placement, neither of which can be guaranteed. + + \section2 Wayland Peculiarities + + On Wayland, programmatically setting or getting the position of a top-level window from the + client-side is typically not supported. Technically speaking, it depends on the shell + interface. For typical desktop compositors, however, the default shell interface will be + \c{XDG Shell}, which does not support manual positioning of windows. In such cases, Qt will + ignore calls to set the top-level position of a window, and, when queried, the window position + will always be returned as QPoint(0, 0). */ /*! diff --git a/src/widgets/kernel/qwidget.cpp b/src/widgets/kernel/qwidget.cpp index 08acae00c7..cb432c84bc 100644 --- a/src/widgets/kernel/qwidget.cpp +++ b/src/widgets/kernel/qwidget.cpp @@ -3547,6 +3547,10 @@ int QWidget::y() const See the \l{Window Geometry} documentation for an overview of geometry issues with windows. + \note Not all windowing systems support setting or querying top level window positions. + On such a system, programmatically moving windows may not have any effect, and artificial + values may be returned for the current positions, such as \c QPoint(0, 0). + \sa frameGeometry, size, x(), y() */ QPoint QWidget::pos() const