QWindow Class
The QWindow class represents a window in the underlying windowing system. More...
| Header: | #include <QWindow> |
| qmake: | QT += gui |
| Since: | Qt 5.0 |
| Inherits: | QObject and QSurface |
| Inherited By: |
This class was introduced in Qt 5.0.
Public Types
| enum | AncestorMode { ExcludeTransients, IncludeTransients } |
| enum | Visibility { Windowed, Minimized, Maximized, FullScreen, AutomaticVisibility, Hidden } |
Properties
|
Public Functions
| Qt::ScreenOrientation | contentOrientation() const |
| Qt::WindowFlags | flags() const |
| int | height() const |
| bool | isActive() const |
| bool | isVisible() const |
| int | maximumHeight() const |
| int | maximumWidth() const |
| int | minimumHeight() const |
| int | minimumWidth() const |
| Qt::WindowModality | modality() const |
| qreal | opacity() const |
| void | reportContentOrientationChange(Qt::ScreenOrientation orientation) |
| void | setFlags(Qt::WindowFlags flags) |
| void | setModality(Qt::WindowModality modality) |
| void | setOpacity(qreal level) |
| void | setVisibility(QWindow::Visibility v) |
| QString | title() const |
| QWindow::Visibility | visibility() const |
| int | width() const |
| int | x() const |
| int | y() const |
Public Slots
| void | setHeight(int arg) |
| void | setMaximumHeight(int h) |
| void | setMaximumWidth(int w) |
| void | setMinimumHeight(int h) |
| void | setMinimumWidth(int w) |
| void | setTitle(const QString &) |
| void | setVisible(bool visible) |
| void | setWidth(int arg) |
| void | setX(int arg) |
| void | setY(int arg) |
Signals
| void | activeChanged() |
| void | contentOrientationChanged(Qt::ScreenOrientation orientation) |
| void | heightChanged(int arg) |
| void | maximumHeightChanged(int arg) |
| void | maximumWidthChanged(int arg) |
| void | minimumHeightChanged(int arg) |
| void | minimumWidthChanged(int arg) |
| void | modalityChanged(Qt::WindowModality modality) |
| void | opacityChanged(qreal opacity) |
| void | visibilityChanged(QWindow::Visibility visibility) |
| void | visibleChanged(bool arg) |
| void | widthChanged(int arg) |
| void | windowTitleChanged(const QString &title) |
| void | xChanged(int arg) |
| void | yChanged(int arg) |
Detailed Description
A window that is supplied a parent becomes a native child window of their parent window.
An application will typically use QWidget or QQuickView for its UI, and not QWindow directly. Still, it is possible to render directly to a QWindow with QBackingStore or QOpenGLContext, when wanting to keep dependencies to a minimum or when wanting to use OpenGL directly. The Raster Window Example and OpenGL Window Example are useful reference examples for how to render to a QWindow using either approach.
Resource Management
Windows can potentially use a lot of memory. A usual measurement is width times height times color depth. A window might also include multiple buffers to support double and triple buffering, as well as depth and stencil buffers. To release a window's memory resources, call the destroy() function.
Content Orientation
QWindow has reportContentOrientationChange() that can be used to specify the layout of the window contents in relation to the screen. The content orientation is simply a hint to the windowing system about which orientation the window contents are in. It's useful when you wish to keep the same window size, but rotate the contents instead, especially when doing rotation animations between different orientations. The windowing system might use this value to determine the layout of system popups or dialogs.
Visibility and Windowing System Exposure
By default, the window is not visible, and you must call setVisible(true), or show() or similar to make it visible. To make a window hidden again, call setVisible(false) or hide(). The visible property describes the state the application wants the window to be in. Depending on the underlying system, a visible window might still not be shown on the screen. It could, for instance, be covered by other opaque windows or moved outside the physical area of the screen. On windowing systems that have exposure notifications, the isExposed() accessor describes whether the window should be treated as directly visible on screen. The exposeEvent() function is called whenever an area of the window is invalidated, for example due to the exposure in the windowing system changing. On windowing systems that do not make this information visible to the application, isExposed() will simply return the same value as isVisible().
QWindow::Visibility queried through visibility() is a convenience API combining the functions of visible() and windowStates().
Rendering
There are two Qt APIs that can be used to render content into a window, QBackingStore for rendering with a QPainter and flushing the contents to a window with type QSurface::RasterSurface, and QOpenGLContext for rendering with OpenGL to a window with type QSurface::OpenGLSurface.
The application can start rendering as soon as isExposed() returns true, and can keep rendering until it isExposed() returns false. To find out when isExposed() changes, reimplement exposeEvent(). The window will always get a resize event before the first expose event.
Initial Geometry
If the window's width and height are left uninitialized, the window will get a reasonable default geometry from the platform window. If the position is left uninitialized, then the platform window will allow the windowing system to position the window. For example on X11, the window manager usually does some kind of smart positioning to try to avoid having new windows completely obscure existing windows. However setGeometry() initializes both the position and the size, so if you want a fixed size but an automatic position, you should call resize() or setWidth() and setHeight() instead.
Member Type Documentation
enum QWindow::AncestorMode
This enum is used to control whether or not transient parents should be considered ancestors.
| Constant | Value | Description |
|---|---|---|
QWindow::ExcludeTransients | 0 | Transient parents are not considered ancestors. |
QWindow::IncludeTransients | 1 | Transient parents are considered ancestors. |
enum QWindow::Visibility
This enum describes what part of the screen the window occupies or should occupy.
| Constant | Value | Description |
|---|---|---|
QWindow::Windowed | 2 | The window occupies part of the screen, but not necessarily the entire screen. This state will occur only on windowing systems which support showing multiple windows simultaneously. In this state it is possible for the user to move and resize the window manually, if WindowFlags permit it and if it is supported by the windowing system. |
QWindow::Minimized | 3 | The window is reduced to an entry or icon on the task bar, dock, task list or desktop, depending on how the windowing system handles minimized windows. |
QWindow::Maximized | 4 | The window occupies one entire screen, and the titlebar is still visible. On most windowing systems this is the state achieved by clicking the maximize button on the toolbar. |
QWindow::FullScreen | 5 | The window occupies one entire screen, is not resizable, and there is no titlebar. On some platforms which do not support showing multiple simultaneous windows, this can be the usual visibility when the window is not hidden. |
QWindow::AutomaticVisibility | 1 | This means to give the window a default visible state, which might be fullscreen or windowed depending on the platform. It can be given as a parameter to setVisibility but will never be read back from the visibility accessor. |
QWindow::Hidden | 0 | The window is not visible in any way, however it may remember a latent visibility which can be restored by setting AutomaticVisibility. |
This enum was introduced or modified in Qt 5.1.
Property Documentation
active : const bool
This property holds the active status of the window
This property was introduced in Qt 5.1.
Access functions:
| bool | isActive() const |
Notifier signal:
| void | activeChanged() |
See also requestActivate().
contentOrientation : Qt::ScreenOrientation
This property holds the orientation of the 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.
The recommended orientation is QScreen::orientation() but an application doesn't have to support all possible orientations, and thus can opt to ignore the current screen orientation.
The difference between the window and the content orientation determines how much to rotate the content by. QScreen::angleBetween(), QScreen::transformBetween(), and QScreen::mapBetween() can be used to compute the necessary transform.
The default value is Qt::PrimaryOrientation
Access functions:
| Qt::ScreenOrientation | contentOrientation() const |
| void | reportContentOrientationChange(Qt::ScreenOrientation orientation) |
Notifier signal:
| void | contentOrientationChanged(Qt::ScreenOrientation orientation) |
flags : Qt::WindowFlags
This property holds the window flags of the window
The window flags control the window's appearance in the windowing system, whether it's a dialog, popup, or a regular window, and whether it should have a title bar, etc.
The actual window flags might differ from the flags set with setFlags() if the requested flags could not be fulfilled.
Access functions:
| Qt::WindowFlags | flags() const |
| void | setFlags(Qt::WindowFlags flags) |
See also setFlag().
height : int
This property holds the height of the window's geometry
Access functions:
| int | height() const |
| void | setHeight(int arg) |
Notifier signal:
| void | heightChanged(int arg) |
maximumHeight : int
This property holds the maximum height of the window's geometry
Access functions:
| int | maximumHeight() const |
| void | setMaximumHeight(int h) |
Notifier signal:
| void | maximumHeightChanged(int arg) |
maximumWidth : int
This property holds the maximum width of the window's geometry
Access functions:
| int | maximumWidth() const |
| void | setMaximumWidth(int w) |
Notifier signal:
| void | maximumWidthChanged(int arg) |
minimumHeight : int
This property holds the minimum height of the window's geometry
Access functions:
| int | minimumHeight() const |
| void | setMinimumHeight(int h) |
Notifier signal:
| void | minimumHeightChanged(int arg) |
minimumWidth : int
This property holds the minimum width of the window's geometry
Access functions:
| int | minimumWidth() const |
| void | setMinimumWidth(int w) |
Notifier signal:
| void | minimumWidthChanged(int arg) |
modality : Qt::WindowModality
This property holds the modality of the window
A modal window prevents other windows from receiving input events. Qt supports two types of modality: Qt::WindowModal and Qt::ApplicationModal.
By default, this property is Qt::NonModal
Access functions:
| Qt::WindowModality | modality() const |
| void | setModality(Qt::WindowModality modality) |
Notifier signal:
| void | modalityChanged(Qt::WindowModality modality) |
See also Qt::WindowModality.
opacity : qreal
This property holds the opacity of the window in the windowing system.
If the windowing system supports window opacity, this can be used to fade the window in and out, or to make it semitransparent.
A value of 1.0 or above is treated as fully opaque, whereas a value of 0.0 or below is treated as fully transparent. Values inbetween represent varying levels of translucency between the two extremes.
The default value is 1.0.
This property was introduced in Qt 5.1.
Access functions:
| qreal | opacity() const |
| void | setOpacity(qreal level) |
Notifier signal:
| void | opacityChanged(qreal opacity) |
title : QString
This property holds the window's title in the windowing system
The window title might appear in the title area of the window decorations, depending on the windowing system and the window flags. It might also be used by the windowing system to identify the window in other contexts, such as in the task switcher.
Access functions:
| QString | title() const |
| void | setTitle(const QString &) |
Notifier signal:
| void | windowTitleChanged(const QString &title) |
See also flags().
visibility : Visibility
This property holds the screen-occupation state of the window
Visibility is whether the window should appear in the windowing system as normal, minimized, maximized, fullscreen or hidden.
To set the visibility to AutomaticVisibility means to give the window a default visible state, which might be fullscreen or windowed depending on the platform. When reading the visibility property you will always get the actual state, never AutomaticVisibility.
This property was introduced in Qt 5.1.
Access functions:
| QWindow::Visibility | visibility() const |
| void | setVisibility(QWindow::Visibility v) |
Notifier signal:
| void | visibilityChanged(QWindow::Visibility visibility) |
visible : bool
This property holds whether the window is visible or not
This property controls the visibility of the window in the windowing system.
By default, the window is not visible, you must call setVisible(true), or show() or similar to make it visible.
Note: Hiding a window does not remove the window from the windowing system, it only hides it. On windowing systems that give full screen applications a dedicated desktop (such as macOS), hiding a full screen window will not remove that desktop, but leave it blank. Another window from the same application might be shown full screen, and will fill that desktop. Use QWindow::close to completely remove a window from the windowing system.
Access functions:
| bool | isVisible() const |
| void | setVisible(bool visible) |
Notifier signal:
| void | visibleChanged(bool arg) |
See also show().
width : int
This property holds the width of the window's geometry
Access functions:
| int | width() const |
| void | setWidth(int arg) |
Notifier signal:
| void | widthChanged(int arg) |
x : int
This property holds the x position of the window's geometry
Access functions:
| int | x() const |
| void | setX(int arg) |
Notifier signal:
| void | xChanged(int arg) |
y : int
This property holds the y position of the window's geometry
Access functions:
| int | y() const |
| void | setY(int arg) |
Notifier signal:
| void | yChanged(int arg) |