QQuickWindow Class
The QQuickWindow class provides the window for displaying a graphical QML scene. More...
| Header: | #include <QQuickWindow> |
| qmake: | QT += quick |
| Since: | Qt 5.0 |
| Instantiated By: | Window |
| Inherits: | QWindow |
| Inherited By: |
This class was introduced in Qt 5.0.
Public Types
| struct | GraphicsStateInfo |
| enum | CreateTextureOption { TextureHasAlphaChannel, TextureHasMipmaps, TextureOwnsGLTexture, TextureCanUseAtlas, TextureIsOpaque } |
| enum | NativeObjectType { NativeObjectTexture } |
| enum | RenderStage { BeforeSynchronizingStage, AfterSynchronizingStage, BeforeRenderingStage, AfterRenderingStage, AfterSwapStage, NoStage } |
| enum | SceneGraphError { ContextNotAvailable } |
| enum | TextRenderType { QtTextRendering, NativeTextRendering } |
Properties
- activeFocusItem : QQuickItem* const
- color : QColor
- contentItem : QQuickItem* const
Public Functions
| QQuickItem * | activeFocusItem() const |
| QColor | color() const |
| QQuickItem * | contentItem() const |
| void | setColor(const QColor &color) |
Signals
| void | activeFocusItemChanged() |
| void | colorChanged(const QColor &) |
Detailed Description
QQuickWindow provides the graphical scene management needed to interact with and display a scene of QQuickItems.
A QQuickWindow always has a single invisible root item. To add items to this window, reparent the items to the root item or to an existing item in the scene.
For easily displaying a scene from a QML file, see QQuickView.
Rendering
QQuickWindow uses a scene graph to represent what needs to be rendered. This scene graph is disconnected from the QML scene and potentially lives in another thread, depending on the platform implementation. Since the rendering scene graph lives independently from the QML scene, it can also be completely released without affecting the state of the QML scene.
The sceneGraphInitialized() signal is emitted on the rendering thread before the QML scene is rendered to the screen for the first time. If the rendering scene graph has been released, the signal will be emitted again before the next frame is rendered.
Integration with OpenGL
When using the default OpenGL adaptation, it is possible to integrate OpenGL calls directly into the QQuickWindow using the same OpenGL context as the Qt Quick Scene Graph. This is done by connecting to the QQuickWindow::beforeRendering() or QQuickWindow::afterRendering() signal.
Note: When using QQuickWindow::beforeRendering(), make sure to disable clearing before rendering with QQuickWindow::setClearBeforeRendering().
Exposure and Visibility
When a QQuickWindow instance is deliberately hidden with hide() or setVisible(false), it will stop rendering and its scene graph and graphics context might be released. The sceneGraphInvalidated() signal will be emitted when this happens.
Warning: It is crucial that graphics operations and interaction with the scene graph happens exclusively on the rendering thread, primarily during the updatePaintNode() phase.
Warning: As signals related to rendering might be emitted from the rendering thread, connections should be made using Qt::DirectConnection.
Resource Management
QML will try to cache images and scene graph nodes to improve performance, but in some low-memory scenarios it might be required to aggressively release these resources. The releaseResources() can be used to force the clean up of certain resources. Calling releaseResources() may result in the entire scene graph and in the case of the OpenGL adaptation the associated context will be deleted. The sceneGraphInvalidated() signal will be emitted when this happens.
Note: All classes with QSG prefix should be used solely on the scene graph's rendering thread. See Scene Graph and Rendering for more information.
Context and Surface Formats
While it is possible to specify a QSurfaceFormat for every QQuickWindow by calling the member function setFormat(), windows may also be created from QML by using the Window and ApplicationWindow elements. In this case there is no C++ code involved in the creation of the window instance, yet applications may still wish to set certain surface format values, for example to request a given OpenGL version or profile. Such applications can call the static function QSurfaceFormat::setDefaultFormat() at startup. The specified format will be used for all Quick windows created afterwards.
See also Scene Graph - OpenGL Under QML.
Member Type Documentation
enum QQuickWindow::CreateTextureOption
The CreateTextureOption enums are used to customize a texture is wrapped.
| Constant | Value | Description |
|---|---|---|
QQuickWindow::TextureHasAlphaChannel | 0x0001 | The texture has an alpha channel and should be drawn using blending. |
QQuickWindow::TextureHasMipmaps | 0x0002 | The texture has mipmaps and can be drawn with mipmapping enabled. |
QQuickWindow::TextureOwnsGLTexture | 0x0004 | The texture object owns the texture id and will delete the OpenGL texture when the texture object is deleted. |
QQuickWindow::TextureCanUseAtlas | 0x0008 | The image can be uploaded into a texture atlas. |
QQuickWindow::TextureIsOpaque | 0x0010 | The texture will return false for QSGTexture::hasAlphaChannel() and will not be blended. This flag was added in Qt 5.6. |
enum QQuickWindow::NativeObjectType
Specifies the type of the native object passed to functions such as createTextureFromNativeObject().
| Constant | Value | Description |
|---|---|---|
QQuickWindow::NativeObjectTexture | 0 | The native object is a 2D texture (OpenGL, Direct3D 11, Metal) or image (Vulkan). |
This enum was introduced or modified in Qt 5.14.
enum QQuickWindow::RenderStage
| Constant | Value | Description |
|---|---|---|
QQuickWindow::BeforeSynchronizingStage | 0 | Before synchronization. |
QQuickWindow::AfterSynchronizingStage | 1 | After synchronization. |
QQuickWindow::BeforeRenderingStage | 2 | Before rendering. |
QQuickWindow::AfterRenderingStage | 3 | After rendering. |
QQuickWindow::AfterSwapStage | 4 | After the frame is swapped. |
QQuickWindow::NoStage | 5 | As soon as possible. This value was added in Qt 5.6. |
This enum was introduced or modified in Qt 5.4.
See also Scene Graph and Rendering.
enum QQuickWindow::SceneGraphError
This enum describes the error in a sceneGraphError() signal.
| Constant | Value | Description |
|---|---|---|
QQuickWindow::ContextNotAvailable | 1 | graphics context creation failed. This typically means that no suitable OpenGL implementation was found, for example because no graphics drivers are installed and so no OpenGL 2 support is present. On mobile and embedded boards that use OpenGL ES such an error is likely to indicate issues in the windowing system integration and possibly an incorrect configuration of Qt. |
This enum was introduced or modified in Qt 5.3.
enum QQuickWindow::TextRenderType
This enum describes the default render type of text-like elements in Qt Quick (Text, TextInput, etc.).
Select NativeTextRendering if you prefer text to look native on the target platform and do not require advanced features such as transformation of the text. Using such features in combination with the NativeTextRendering render type will lend poor and sometimes pixelated results.
| Constant | Value | Description |
|---|---|---|
QQuickWindow::QtTextRendering | 0 | Use Qt's own rasterization algorithm. |
QQuickWindow::NativeTextRendering | 1 | Use the operating system's native rasterizer for text. |
This enum was introduced or modified in Qt 5.10.
Property Documentation
activeFocusItem : QQuickItem* const
This property holds the item which currently has active focus or null if there is no item with active focus.
Access functions:
| QQuickItem * | activeFocusItem() const |
Notifier signal:
| void | activeFocusItemChanged() |
See also QQuickItem::forceActiveFocus() and Keyboard Focus in Qt Quick.
color : QColor
This property holds the color used to clear the OpenGL context.
Setting the clear color has no effect when clearing is disabled. By default, the clear color is white.
Access functions:
| QColor | color() const |
| void | setColor(const QColor &color) |
Notifier signal:
| void | colorChanged(const QColor &) |
See also setClearBeforeRendering() and setDefaultAlphaBuffer().
contentItem : QQuickItem* const
This property holds the invisible root item of the scene.
A QQuickWindow always has a single invisible root item containing all of its content. To add items to this window, reparent the items to the contentItem or to an existing item in the scene.
Access functions:
| QQuickItem * | contentItem() const |