Qt Quick Controls QML Types

Qt Quick Controls provides QML types for creating user interfaces. These QML types work in conjunction with Qt Quick and Qt Quick Layouts.

Qt Quick Controls QML types can be imported into your application using the following import statement in your .qml file:

import QtQuick.Controls

QML Types

AbstractButton

Abstract base type providing functionality common to buttons

Action

Abstract user interface action

ActionGroup

Groups actions together

ApplicationWindow

Styled top-level window with support for a header and footer

BusyIndicator

Indicates background activity, for example, while content is being loaded

Button

Push-button that can be clicked to perform a command or answer a question

ButtonGroup

Mutually-exclusive group of checkable buttons

CheckBox

Check button that can be toggled on or off

CheckDelegate

Item delegate with a check indicator that can be toggled on or off

ComboBox

Combined button and popup list for selecting options

Container

Abstract base type providing functionality common to containers

Control

Abstract base type providing functionality common to all controls

DelayButton

Check button that triggers when held down long enough

Dial

Circular dial that is rotated to set a value

Dialog

Popup dialog with standard buttons and a title, used for short-term interaction with the user

DialogButtonBox

A button box used in dialogs

Drawer

Side panel that can be opened and closed using a swipe gesture

Frame

Visual frame for a logical group of controls

GroupBox

Visual frame and title for a logical group of controls

HorizontalHeaderView

Provides a horizontal header view to accompany a TableView

ItemDelegate

Basic item delegate that can be used in various views and controls

Label

Styled text label with inherited font

Menu

Popup that can be used as a context menu or popup menu

MenuBar

Provides a window menu bar

MenuBarItem

Presents a drop-down menu within a MenuBar

MenuItem

Presents an item within a Menu

MenuSeparator

Separates a group of items in a menu from adjacent items

Overlay

A window overlay for popups

Page

Styled page control with support for a header and footer

PageIndicator

Indicates the currently active page

Pane

Provides a background matching with the application style and theme

Popup

Base type of popup-like user interface controls

ProgressBar

Indicates the progress of an operation

RadioButton

Exclusive radio button that can be toggled on or off

RadioDelegate

Exclusive item delegate with a radio indicator that can be toggled on or off

RangeSlider

Used to select a range of values by sliding two handles along a track

RoundButton

A push-button control with rounded corners that can be clicked by the user

ScrollBar

Vertical or horizontal interactive scroll bar

ScrollIndicator

Vertical or horizontal non-interactive scroll indicator

ScrollView

Scrollable view

SelectionRectangle

Used to select table cells inside a TableView

Slider

Used to select a value by sliding a handle along a track

SpinBox

Allows the user to select from a set of preset values

SplitHandle

Provides attached properties for SplitView handles

SplitView

Lays out items with a draggable splitter between each item

StackView

Provides a stack-based navigation model

SwipeDelegate

Swipable item delegate

SwipeView

Enables the user to navigate pages by swiping sideways

Switch

Button that can be toggled on or off

SwitchDelegate

Item delegate with a switch indicator that can be toggled on or off

TabBar

Allows the user to switch between different views or subtasks

TabButton

Button with a look suitable for a TabBar

TextArea

Multi-line text input area

TextField

Single-line text input field

ToolBar

Container for context-sensitive controls

ToolButton

Button with a look suitable for a ToolBar

ToolSeparator

Separates a group of items in a toolbar from adjacent items

ToolTip

Provides tool tips for any control

Tumbler

Spinnable wheel of items that can be selected

VerticalHeaderView

Provides a vertical header view to accompany a TableView

Using Qt Quick Controls types in property declarations

As mentioned in Qt Quick Templates 2 QML Types, each type in Qt Quick Controls is backed by a C++ "template" type. These types are non-visual implementations of controls' logic and behavior.

For example, the Menu type's API and behavior is defined by the C++ type in Qt Quick Templates. Each style that wants to provide a Menu must have a Menu.qml available, and the root item in that file must be the Menu from Qt Quick Templates. When you import QtQuick.Controls and create a Menu in QML, the type you get is actually the QML Menu defined by the style's Menu.qml.

In order to use a control as the type in a property declaration, you should use the corresponding type from Qt Quick Templates. For example, suppose you had a PopupOpener component, which was a Button that opened a Popup:

// PopupButton.qml
import QtQuick.Controls

Button {
    required property Popup popup

    onClicked: popup.open()
}

// main.qml
PopupButton {
    popup: saveChangesDialog
}

Dialog {
    id: saveChangesDialog

    // ...
}

Running this code will result in an error:

Unable to assign Dialog_QMLTYPE to Popup_QMLTYPE

This is because of the inheritance hierarchy:

Popup (C++ type in QtQuick.Templates)
│   └── Popup (QML type in QtQuick.Controls)
└── Dialog (C++ type in QtQuick.Templates)
    └── Dialog (QML type in QtQuick.Controls)

Dialog from QtQuick.Controls does not derive from the Popup from QtQuick.Controls, but from QtQuick.Templates.

Instead, use the Popup from Qt Quick Templates as the property type:

// PopupButton.qml
import QtQuick.Controls
import QtQuick.Templates as T

Button {
    required property T.Popup popup

    onClicked: popup.open()
}

For more information on the Qt Quick Controls module, see the Qt Quick Controls module documentation.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.