QPlatformWindow Class

The QPlatformWindow class provides an abstraction for top-level windows. More...

Header: #include <QPlatformWindow>
Inherits: QPlatformSurface

Public Functions

QPlatformWindow(QWindow *window)
virtual ~QPlatformWindow() override
virtual bool close()
virtual void deliverUpdateRequest()
virtual qreal devicePixelRatio() const
virtual bool frameStrutEventsEnabled() const
virtual QRect geometry() const
virtual void handleContentOrientationChange(Qt::ScreenOrientation orientation)
bool hasPendingUpdateRequest() const
virtual void initialize()
virtual void invalidateSurface()
virtual bool isActive() const
virtual bool isAlertState() const
virtual bool isAncestorOf(const QPlatformWindow *child) const
virtual bool isEmbedded() const
virtual bool isExposed() const
virtual void lower()
virtual QPoint mapFromGlobal(const QPoint &pos) const
virtual QPoint mapToGlobal(const QPoint &pos) const
virtual QRect normalGeometry() const
QPlatformWindow *parent() const
virtual void propagateSizeHints()
virtual void raise()
virtual void requestActivateWindow()
virtual void requestUpdate()
virtual QMargins safeAreaMargins() const
virtual void setAlertState(bool enable)
virtual void setFrameStrutEventsEnabled(bool enabled)
virtual void setGeometry(const QRect &rect)
virtual void setMask(const QRegion &region)
virtual void setOpacity(qreal level)
virtual void setParent(const QPlatformWindow *parent)
virtual void setVisible(bool visible)
virtual void setWindowFilePath(const QString &filePath)
virtual void setWindowFlags(Qt::WindowFlags flags)
virtual void setWindowIcon(const QIcon &icon)
virtual bool setWindowModified(bool modified)
virtual void setWindowState(Qt::WindowStates state)
virtual void setWindowTitle(const QString &title)
virtual bool startSystemMove()
virtual bool startSystemResize(Qt::Edges edges)
virtual WId winId() const
QWindow *window() const
QSize windowBaseSize() const
virtual bool windowEvent(QEvent *event)
QRect windowFrameGeometry() const
QRect windowGeometry() const
QSize windowMaximumSize() const
QSize windowMinimumSize() const
QSize windowSizeIncrement() const

Reimplemented Public Functions

virtual QSurfaceFormat format() const override
virtual QPlatformScreen *screen() const override

Static Public Members

QRectF closestAcceptableGeometry(const QWindow *qWindow, const QRectF &nativeRect)
QRect initialGeometry(const QWindow *w, const QRect &initialGeometry, int defaultWidth, int defaultHeight, const QScreen **resultingScreenReturn = nullptr)

Protected Functions

QPlatformScreen *screenForGeometry(const QRect &newGeometry) const

Static Protected Members

QSize constrainWindowSize(const QSize &size)
QString formatWindowTitle(const QString &title, const QString &separator)

Detailed Description

\since4.8 \internal \preliminary \ingroup qpa

The QPlatformWindow abstraction is used by QWindow for all its top level windows. It is being created by calling the createPlatformWindow function in the loaded QPlatformIntegration instance.

QPlatformWindow is used to signal to the windowing system, how Qt perceives its frame. However, it is not concerned with how Qt renders into the window it represents.

Visible QWindows will always have a QPlatformWindow. However, it is not necessary for all windows to have a QBackingStore. This is the case for QOpenGLWindow. And could be the case for windows where some third party renders into it.

The platform specific window handle can be retrieved by the winId function.

QPlatformWindow is also the way QPA defines how native child windows should be supported through the setParent function.

Implementation Aspects

  1. Mouse grab: Qt expects windows to automatically grab the mouse if the user presses a button until the button is released. Automatic grab should be released if some window is explicitly grabbed.
  2. Enter/Leave events: If there is a window explicitly grabbing mouse events (setMouseGrabEnabled()), enter and leave events should only be sent to the grabbing window when mouse cursor passes over the grabbing window boundary. Other windows will not receive enter or leave events while the grab is active. While an automatic mouse grab caused by a mouse button press is active, no window will receive enter or leave events. When the last mouse button is released, the autograbbing window will receive leave event if mouse cursor is no longer within the window boundary. When any grab starts, the window under cursor will receive a leave event unless it is the grabbing window. When any grab ends, the window under cursor will receive an enter event unless it was the grabbing window.
  3. Window positioning: When calling QWindow::setFramePosition(), the flag QWindowPrivate::positionPolicy is set to QWindowPrivate::WindowFrameInclusive. This means the position includes the window frame, whose size is at this point unknown and the geometry's topleft point is the position of the window frame.

Apart from the auto-tests (tests/auto/gui/kernel/qwindow, tests/auto/gui/kernel/qguiapplication and tests/auto/widgets/kernel/qwidget), there are a number of manual tests and examples that can help testing a platform plugin:

  1. examples/qpa/windows: Basic QWindow creation.
  2. examples/opengl/hellowindow: Basic Open GL windows.
  3. tests/manual/windowflags: Tests setting the window flags.
  4. tests/manual/windowgeometry Tests setting the window geometry.
  5. tests/manual/windowmodality Tests setting the window modality.
  6. tests/manual/widgetgrab Tests mouse grab and dialogs.

See also QBackingStore and QWindow.

Member Function Documentation

[explicit] QPlatformWindow::QPlatformWindow(QWindow *window)

Constructs a platform window with the given top level window.

[override virtual noexcept] QPlatformWindow::~QPlatformWindow()

Virtual destructor does not delete its top level window.

[virtual] bool QPlatformWindow::close()

Reimplement to let the platform handle non-spontaneous window close.

When reimplementing make sure to call the base class implementation or QWindowSystemInterface::handleCloseEvent(), which will prompt the user to accept the window close (if needed) and then close the QWindow.

[static] QRectF QPlatformWindow::closestAcceptableGeometry(const QWindow *qWindow, const QRectF &nativeRect)

Returns the closest acceptable geometry for a given geometry before a resize/move event for platforms that support it, for example to implement heightForWidth().

[static protected] QSize QPlatformWindow::constrainWindowSize(const QSize &size)

Returns a size with both dimensions bounded to [0, QWINDOWSIZE_MAX]

[virtual] void QPlatformWindow::deliverUpdateRequest()

Delivers an QEvent::UpdateRequest event to the window.

QPlatformWindow subclasses can re-implement this function to provide e.g. logging or tracing of the delivery, but should always call the base class function.

[virtual] qreal QPlatformWindow::devicePixelRatio() const

Reimplement this function in subclass to return the device pixel ratio for the window. This is the ratio between physical pixels and device-independent pixels.

See also QPlatformWindow::devicePixelRatio() and ;.

[override virtual] QSurfaceFormat QPlatformWindow::format() const

Returns the actual surface format of the window.

[static protected] QString QPlatformWindow::formatWindowTitle(const QString &title, const QString &separator)

Call this method to put together a window title composed of title separator the application display name

If the display name isn't set, and the title is empty, the raw app name is used.

[virtual] bool QPlatformWindow::frameStrutEventsEnabled() const

Reimplement this method to return whether frame strut events are enabled.

See also setFrameStrutEventsEnabled().

[virtual] QRect QPlatformWindow::geometry() const

Returns the current geometry of a window

See also setGeometry().

[virtual] void QPlatformWindow::handleContentOrientationChange(Qt::ScreenOrientation orientation)

Handle changes to the orientation of the platform window's contents.

This is a hint to the window manager in case it needs to display additional content like popups, dialogs, status bars, or similar in relation to the window.

See also QWindow::reportContentOrientationChange().

bool QPlatformWindow::hasPendingUpdateRequest() const

Returns true if the window has a pending update request.

See also requestUpdate() and deliverUpdateRequest().

[static] QRect QPlatformWindow::initialGeometry(const QWindow *w, const QRect &initialGeometry, int defaultWidth, int defaultHeight, const QScreen **resultingScreenReturn = nullptr)

Helper function to get initial geometry on windowing systems which do not do smart positioning and also do not provide a means of centering a transient window w.r.t. its parent. For example this is useful on Windows and MacOS but not X11, because an X11 window manager typically tries to layout new windows to optimize usage of the available desktop space. However if the given window already has geometry which the application has initialized, it takes priority.

initialGeometry has to be provided in native pixels. defaultWidth has to be provided in device independent pixels defaultHeight has to be provided in device independent pixels

[virtual] void QPlatformWindow::initialize()

Called as part of QWindow::create(), after constructing the window. Platforms should prefer to do initialization here instead of in the constructor, as the platform window object will be fully constructed, and associated to the corresponding QWindow, allowing synchronous event delivery.

[virtual] void QPlatformWindow::invalidateSurface()

Invalidates the window's surface by releasing its surface buffers.

Many platforms do not support releasing the surface memory, and the default implementation does nothing.

The platform window is expected to recreate the surface again if it is needed. For instance, if an OpenGL context is made current on this window.

[virtual] bool QPlatformWindow::isActive() const

Returns true if the window should appear active from a style perspective.

This function can make platform-specific isActive checks, such as checking if the QWindow is embedded in an active native window.

[virtual] bool QPlatformWindow::isAlertState() const

Reimplement this method return whether the window is in an alert state.

\since5.1

See also setAlertState().

[virtual] bool QPlatformWindow::isAncestorOf(const QPlatformWindow *child) const

Returns true if the window is an ancestor of the given child.

Platform overrides should iterate the native window hierarchy of the child, to ensure that ancestary is reflected even with native windows in the window hierarchy.

[virtual] bool QPlatformWindow::isEmbedded() const

Returns true if the window is a child of a non-Qt window.

A embedded window has no parent platform window as reflected though parent(), but will have a native parent window.

[virtual] bool QPlatformWindow::isExposed() const

Returns if this window is exposed in the windowing system.

An exposeEvent() is sent every time this value changes.

[virtual] void QPlatformWindow::lower()

Reimplement to be able to let Qt lower windows to the bottom of the desktop

[virtual] QPoint QPlatformWindow::mapFromGlobal(const QPoint &pos) const

Translates the global screen coordinate pos to window coordinates using native methods. This is required for embedded windows, where the topmost QWindow coordinates are not global screen coordinates.

Returns pos if there is no platform specific implementation.

[virtual] QPoint QPlatformWindow::mapToGlobal(const QPoint &pos) const

Translates the window coordinate pos to global screen coordinates using native methods. This is required for embedded windows, where the topmost QWindow coordinates are not global screen coordinates.

Returns pos if there is no platform specific implementation.

[virtual] QRect QPlatformWindow::normalGeometry() const

Returns the geometry of a window in 'normal' state (neither maximized, fullscreen nor minimized) for saving geometries to application settings.

\since5.3

QPlatformWindow *QPlatformWindow::parent() const

Returns the parent platform window (or nullptr if orphan).

See also setParent().

[virtual] void QPlatformWindow::propagateSizeHints()

Reimplement to propagate the size hints of the QWindow.

The size hints include QWindow::minimumSize(), QWindow::maximumSize(), QWindow::sizeIncrement(), and QWindow::baseSize().

[virtual] void QPlatformWindow::raise()

Reimplement to be able to let Qt raise windows to the top of the desktop

[virtual] void QPlatformWindow::requestActivateWindow()

Reimplement to let Qt be able to request activation/focus for a window

Some window systems will probably not have callbacks for this functionality, and then calling QWindowSystemInterface::handleWindowActivated(QWindow *w) would be sufficient.

If the window system has some event handling/callbacks then call QWindowSystemInterface::handleWindowActivated(QWindow *w) when the window system gives the notification.

Default implementation calls QWindowSystem::handleWindowActivated(QWindow *w)

[virtual] void QPlatformWindow::requestUpdate()

Requests an QEvent::UpdateRequest event. The event will be delivered to the QWindow.

QPlatformWindow subclasses can re-implement this function to provide display refresh synchronized updates. The event should be delivered using QPlatformWindow::deliverUpdateRequest() to not get out of sync with the internal state of QWindow.

The default implementation posts an UpdateRequest event to the window after an interval that is at most 5 ms. If the window's associated screen reports a refresh rate higher than 60 Hz, the interval is scaled down to a valid smaller than 5. The additional time is there to give the event loop a bit of idle time to gather system events.

[virtual] QMargins QPlatformWindow::safeAreaMargins() const

The safe area margins of a window represent the area that is safe to place content within, without intersecting areas of the screen where system UI is placed, or where a screen bezel may cover the content.

[override virtual] QPlatformScreen *QPlatformWindow::screen() const

Returns the platform screen handle corresponding to this platform window, or null if the window is not associated with a screen.

[protected] QPlatformScreen *QPlatformWindow::screenForGeometry(const QRect &newGeometry) const

Helper function for finding the new screen for newGeometry in response to a geometry changed event. Returns the new screen if the window was moved to another virtual sibling. If the screen changes, the platform plugin should call QWindowSystemInterface::handleWindowScreenChanged().

Note: : The current screen will always be returned for child windows since they should never signal screen changes.

\since5.4

See also QWindowSystemInterface::handleWindowScreenChanged().

[virtual] void QPlatformWindow::setAlertState(bool enable)

Reimplement this method to set whether the window demands attention (for example, by flashing the taskbar icon) depending on enabled.

\since5.1

See also isAlertState().

[virtual] void QPlatformWindow::setFrameStrutEventsEnabled(bool enabled)

Reimplement this method to set whether frame strut events should be sent to enabled.

See also frameStrutEventsEnabled.

[virtual] void QPlatformWindow::setGeometry(const QRect &rect)

This function is called by Qt whenever a window is moved or resized using the QWindow API.

Unless you also override QPlatformWindow::geometry(), you need to call the baseclass implementation of this function in any override of QPlatformWindow::setGeometry(), as QWindow::geometry() is expected to report back the set geometry until a confirmation (or rejection) of the new geometry comes back from the window manager and is reported via QWindowSystemInterface::handleGeometryChange().

Window move/resizes can also be triggered spontaneously by the window manager, or as a response to an earlier requested move/resize via the Qt APIs. There is no need to call this function from the window manager callback, instead call QWindowSystemInterface::handleGeometryChange().

The position(x, y) part of the rect might be inclusive or exclusive of the window frame as returned by frameMargins(). You can detect this in the plugin by checking qt_window_private(window())->positionPolicy.

See also geometry().

[virtual] void QPlatformWindow::setMask(const QRegion &region)

Reimplement to be able to let Qt set the mask of a window

[virtual] void QPlatformWindow::setOpacity(qreal level)

Reimplement to be able to let Qt set the opacity level of a window

[virtual] void QPlatformWindow::setParent(const QPlatformWindow *parent)

This function is called to enable native child window in QPA. It is common not to support this feature in Window systems, but can be faked. When this function is called all geometry of this platform window will be relative to the parent.

See also parent().

[virtual] void QPlatformWindow::setVisible(bool visible)

Reimplemented in subclasses to show the surface if visible is true, and hide it if visible is false.

The default implementation sends a synchronous expose event.

[virtual] void QPlatformWindow::setWindowFilePath(const QString &filePath)

Reimplement to set the window file path to filePath

[virtual] void QPlatformWindow::setWindowFlags(Qt::WindowFlags flags)

Requests setting the window flags of this surface to flags.

[virtual] void QPlatformWindow::setWindowIcon(const QIcon &icon)

Reimplement to set the window icon to icon

[virtual] bool QPlatformWindow::setWindowModified(bool modified)

Reimplement to be able to let Qt indicate that the window has been modified. Return true if the native window supports setting the modified flag, false otherwise.

[virtual] void QPlatformWindow::setWindowState(Qt::WindowStates state)

Requests setting the window state of this surface to type.

Qt::WindowActive can be ignored.

[virtual] void QPlatformWindow::setWindowTitle(const QString &title)

Reimplement to set the window title to title.

The implementation might want to append the application display name to the window title, like Windows and Linux do.

See also QGuiApplication::applicationDisplayName().

[virtual] bool QPlatformWindow::startSystemMove()

Reimplement this method to start a system move operation if the system supports it and return true to indicate success.

The default implementation is empty and does nothing.

\since5.15

[virtual] bool QPlatformWindow::startSystemResize(Qt::Edges edges)

Reimplement this method to start a system resize operation if the system supports it and return true to indicate success.

The default implementation is empty and does nothing with edges.

\since5.15

[virtual] WId QPlatformWindow::winId() const

Reimplement in subclasses to return a handle to the native window

QWindow *QPlatformWindow::window() const

Returns the window which belongs to the QPlatformWindow

QSize QPlatformWindow::windowBaseSize() const

Returns the QWindow base size.

[virtual] bool QPlatformWindow::windowEvent(QEvent *event)

Reimplement this method to be able to do any platform specific event handling. All non-synthetic events for window() are passed to this function before being sent to QWindow::event().

Return true if the event should not be passed on to the QWindow.

Subclasses should always call the base class implementation.

QRect QPlatformWindow::windowFrameGeometry() const

Returns the QWindow frame geometry.

QRect QPlatformWindow::windowGeometry() const

Returns the QWindow geometry.

QSize QPlatformWindow::windowMaximumSize() const

Returns the QWindow maximum size.

QSize QPlatformWindow::windowMinimumSize() const

Returns the QWindow minimum size.

QSize QPlatformWindow::windowSizeIncrement() const

Returns the QWindow size increment.