qtquickcontrols-customize.qdoc

Go to the documentation of this file.

// Copyright (C) 2017 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
    \page qtquickcontrols-customize.html
    \keyword Customizing Qt Quick Controls 2
    \title Customizing Qt Quick Controls
    \brief A set of UI controls to create user interfaces in Qt Quick
 
    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.
 
    \section1 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 \l {Control::}{background} item and set the radius
    property of Rectangle:
 
    \include customize-button-background.qdocinc file
 
    \note as the different items that make up a control in any given style are
    designed to work together, it may be necessary to override other items to
    get the look you're after. In addition, not all styles can be customized.
    See the note in \l {Customization Reference} for more information.
 
    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
    \c Button.qml. This file can be found in the following path in your Qt
    installation:
 
    \c {$QTDIR/qml/QtQuick/Controls/Basic/Button.qml}
 
    After doing that, we'll simply add the following line:
 
    \code
    radius: 4
    \endcode
 
    To avoid confusion with the controls in the
    module itself, we'll call the file \c MyButton.qml. To use the control in
    your application, refer to it by its filename:
 
    \qml
    import QtQuick.Controls.Basic
 
    ApplicationWindow {
        MyButton {
            text: qsTr("A Special Button")
        }
    }
    \endqml
 
    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) \c controls. To use the
    control, first import the folder into a namespace:
 
    \qml
    import QtQuick.Controls.Basic
    import "controls" as MyControls
 
    ApplicationWindow {
        MyControls.Button {
            text: qsTr("A Special Button")
        }
    }
    \endqml
 
    As you now have the \c 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.
 
    \note the three approaches mentioned here do not work for customizing the
    attached \l ToolTip, as that is a shared item created internally. To do
    a one-off customization of a \c ToolTip, see \l {Custom Tool Tips}. To
    customize the attached \c ToolTip, it must be provided as part of
    \l {Creating a Custom Style}{your own style}.
 
    \section1 Creating a Custom Style
 
    There are several ways to go about creating your own styles. Below, we'll
    explain the various approaches.
 
    \section2 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
    \l {Using Styles in Qt Quick Controls}{usable}:
 
    \list
    \li At least one QML file whose name matches a control (for example,
        \c Button.qml) must exist.
    \li Each QML file must contain the relevant type from the \l {Qt Quick Templates 2}
        {QtQuick.Templates} 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 \l {Qt Quick Controls}
        {QtQuick.Controls} import as we did in the previous section, it would not work:
        the control we were defining would try to derive from itself.
    \li A \l {Module Definition qmldir Files}{qmldir} file must exist alongside
        the QML file(s). Below is an example of a simple \c qmldir file for a style that
        provides a button:
 
        \badcode
        module MyStyle
        Button 2.15 Button.qml
        \endcode
 
        If you're using \l {Compile-Time Style Selection}{compile-time style
        selection}, the qmldir should also import the fallback style:
 
        \badcode
        # ...
        import QtQuick.Controls.Basic auto
        \endcode
 
        This can also be done for \l {Run-Time Style Selection}{run-time style selection}
        instead of using, for example, \l QQuickStyle::setFallbackStyle().
 
        The directory structure for such a style looks like this:
 
        \badcode
        MyStyle
        ├─── Button.qml
        └─── qmldir
        \endcode
    \li The files must be in a directory that is findable via the \l[QtQml]{QML Import Path}.
 
        For example, if the path to \e MyStyle directory mentioned above was
        \c /home/user/MyApp/MyStyle, then \c /home/user/MyApp must be added to
        the QML import path.
 
        To \l {Using Styles in Qt Quick Controls}{use} \e MyStyle in \e MyApp,
        refer to it by name:
 
        \list
        \li \c {./MyApp -style MyStyle}
        \endlist
 
        The style name must match the casing of the style directory; passing
        \e mystyle or \e MYSTYLE is not supported.
    \endlist
 
    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
    \l[QtQuickControls2]{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.
 
    \section3 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
    \l {Qt Quick Controls Configuration File}{qtquickcontrols2.conf} file,
    and that the following entry exists:
 
    \badcode
    [Controls]
    Style=MyStyle
    \endcode
 
    For more information, take a look at the
    \l {Qt Quick Controls - Flat Style}{Flat Style example}.
 
    \section2 Style-specific C++ Extensions
 
    Sometimes you may need to use C++ to extend your custom style.
 
    \list
    \li If the style that uses the type is the only style used by an
    application, register the type with the QML engine by adding the QML_ELEMENT
    macro and making the file part of your QML module:
    \br
    \br
 
    \if defined(onlinedocs)
        \tab {expose-cpp-to-qml}{tab-cmake}{CMake}{checked}
        \tab {expose-cpp-to-qml}{tab-qmake}{qmake}{}
        \tabcontent {tab-cmake}
    \else
        \section3 Using CMake
    \endif
        \badcode
        qt_add_qml_module(ACoolItem
            URI MyItems
            VERSION 1.0
            SOURCES
                acoolcppitem.cpp acoolcppitem.h
        )
        \endcode
    \if defined(onlinedocs)
        \endtabcontent
        \tabcontent {tab-qmake}
    \else
        \section3 Using QMake
    \endif
        \code
        CONFIG += qmltypes
        QML_IMPORT_NAME = MyItems
        QML_IMPORT_MAJOR_VERSION = 1
        \endcode
 
        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.
 
        \code
        INCLUDEPATH += MyItems
        \endcode
    \if defined(onlinedocs)
        \endtabcontent
    \endif
 
        See \l {Defining QML Types from C++} and \l {Building a QML application}
        for more information.
    \li If the style that uses the type is one of many styles used by an
        application, consider putting each style into a separate module. The
        modules will then be loaded on demand.
    \endlist
 
    \section3 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.
 
    \section4 Avoid assigning an id to styles' implementations of item delegates
 
    As explained in \l {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 \c Button.qml will be structured
    similarly to this:
 
    \qml
    T.Button {
        // ...
 
        background: Rectangle {
            // ...
        }
 
        contentItem: Text {
            // ...
        }
 
        // ...
    }
    \endqml
 
    When you use a Button in your application, the \c background and
    \c contentItem items will be created and parented to the root \c Button
    item:
 
    \qml
    // Creates the Button root item, the Rectangle background,
    // and the Text contentItem.
    Button {
        text: qsTr("Confirm")
    }
    \endqml
 
    Suppose you then needed to do a one-off customization of the Button (as
    explained in \l {Customizing a Control}):
 
    \include customize-button-background.qdocinc file
 
    In QML, this would normally result in both the default \c background
    implementation and the one-off, custom \c background items being created.
    Qt Quick Controls uses a technique that avoids creating both items, and
    instead only creates the custom \c background, greatly improving the
    creation performance of controls.
 
    This technique relies on the absence of an \l {The id Attribute}{id} 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 \c background or \c contentItem so that
    other objects within the file can refer to those items:
 
    \qml
    T.Button {
        // ...
 
        background: Rectangle {
            id: backgroundRect
            // ...
        }
 
        contentItem: Text {
            // Use backgroundRect in some way...
        }
 
        // ...
    }
    \endqml
 
    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 \c 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.
 
    \section4 Avoid imperative assignments of custom items
 
    The technique mentioned in the section above only works when an item is
    \l {Prefer Declarative Bindings Over Imperative Assignments}{declaratively}
    assigned for the first time, and so imperative assignments will result in
    orphaned items. Always use declarative bindings to assign custom items
    when possible.
 
    \section4 Don't import QtQuick.Controls in QML implementations
 
    When writing the QML for your style's implementation of a control,
    it's important not to import \c {QtQuick.Controls}. Doing so will
    prevent the QML from being compiled by the QML compiler.
 
    \section4 Implement types used by other types
 
    Suppose you were using ScrollViews in your application, and decided that
    you want to customize their scroll bars. It is tempting to just implement a
    custom ScrollBar.qml and have ScrollView pick up the customized ScrollBar
    automatically. However, this will not work. You must implement both
    ScrollBar.qml \e and ScrollView.qml.
 
    \section3 Attached properties
 
    It is common for a style to have certain properties or attributes that
    apply to all controls. \l {Attached Properties and Attached Signal
    Handlers}{Attached properties} 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 \l {Material Style}{Material} and \l {Universal
    Style}{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 \l {\QC: Create Qt Quick Applications}
    {create a new Qt Quick Controls application} in \QC. After that, we
    \l {\QC: Create C++ classes}{add a C++ type} 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 \c MyStyle.h:
 
    \code
    #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
    \endcode
 
    \c MyStyle.cpp:
 
    \code
    #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();
    }
    \endcode
 
    The \c 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 \c main.cpp:
 
    \code
    #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();
    }
    \endcode
 
    We then copy \c Button.qml from the Basic style in
    \c {$QTDIR/qml/QtQuick/Controls/Basic/} into a new \c myproject folder in our
    project directory. Add the newly copied \c Button.qml to \c qml.qrc, which is
    the resource file that contains our QML files.
 
    Next, we add a drop shadow to the \l {Control::}{background} delegate of
    the Button:
 
    \qml
    // ...
    import QtQuick.Effects
    import MyStyle
    // ...
 
    background: Rectangle {
        // ...
 
        layer.enabled: control.enabled && control.MyStyle.elevation > 0
        layer.effect: MultiEffect {
            shadowEnabled: true
            shadowHorizontalOffset: 3
            shadowVerticalOffset: 3
            shadowColor: control.visualFocus ? "#330066ff" : "#aaaaaa"
            shadowBlur: control.pressed ? 0.8 : 0.4
        }
    }
    \endqml
 
    Note that we:
 
    \list
    \li Don't bother using the drop shadow when the elevation is \c 0
    \li Change the shadow's color depending on whether or not the button has
        focus
    \li Make the size of the shadow depend on the elevation
    \endlist
 
    To try out the attached property, we create a \l Row with two Buttons in
    \c main.qml:
 
    \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
            }
        }
    }
    \endqml
 
    One button has no elevation, and the other has an elevation of \c 10.
 
    With that in place, we can run our example. To tell the application to
    use our new style, we pass \c {-style MyStyle} as an application
    argument, but there are \l {Using Styles in Qt Quick Controls}{many
    ways} to specify the style to use.
 
    The end result:
 
    \image qtquickcontrols-customize-buttons.png
           {Custom styled buttons}
 
    Note that the \c {import MyStyle 1.0} statement is only necessary
    because we are using the attached property belonging to \c MyStyle.
    Both buttons will use our custom style, even if we were to remove the
    import.
 
    \section1 Customization Reference
 
    The following snippets present examples where the Basic style's controls
    have been customized using the same approach as the
    \l {Customizing a Control} section. The code can be used as a starting
    point to implement a custom look and feel.
 
    \note The \l {macOS Style}{macOS} and \l {Windows Style}{Windows} styles
    are not suitable for customizing.
    \include customizing-native-styles.qdocinc
 
    \note When modifying the size of controls, the actual content size will
    typically remain the same. For example, some styles may make their Button
    fill the bounds of the control, but horizontally and/or vertically center
    the check indicator and text of a CheckBox. If the default resizing
    behaviour is not desired, override the respective delegate(s).
 
    \section2 Customizing ApplicationWindow
 
        ApplicationWindow consists of one visual item:
        \l {ApplicationWindow::background}{background}.
 
        \qml
        import QtQuick
        import QtQuick.Controls.Basic
 
        ApplicationWindow {
            visible: true
 
            background: Rectangle {
                gradient: Gradient {
                    GradientStop { position: 0; color: "#ffffff" }
                    GradientStop { position: 1; color: "#c1bbf9" }
                }
            }
        }
        \endqml
 
 
    \section2 Customizing BusyIndicator
 
        BusyIndicator consists of two visual items: \l {Control::background}{background}
        and \l {Control::}{contentItem}.
 
        \image qtquickcontrols-busyindicator-custom.png
               {Custom styled busy indicator}
 
        \snippet qtquickcontrols-busyindicator-custom.qml file
 
 
    \section2 Customizing Button
 
        Button consists of two visual items: \l {Control::background}{background}
        and \l {Control::}{contentItem}.
 
        \image qtquickcontrols-button-custom.png
               {Custom styled button}
 
        \snippet qtquickcontrols-button-custom.qml file
 
 
    \section2 Customizing CheckBox
 
        CheckBox consists of three visual items: \l {Control::background}{background},
        \l {Control::}{contentItem} and \l {AbstractButton::indicator}{indicator}.
 
        \image qtquickcontrols-checkbox-custom.png
               {Custom styled checkbox}
 
        \snippet qtquickcontrols-checkbox-custom.qml file
 
    \section2 Customizing CheckDelegate
 
        CheckDelegate consists of three visual items: \l {Control::background}{background},
        \l {Control::}{contentItem} and \l {AbstractButton::indicator}{indicator}.
 
        \image qtquickcontrols-checkdelegate-custom.png
               {Custom styled check delegate}
 
        \snippet qtquickcontrols-checkdelegate-custom.qml file
 
 
    \section2 Customizing ComboBox
 
        ComboBox consists of \l {Control::background}{background},
        \l {Control::}{contentItem}, \l {ComboBox::popup}{popup},
        \l {ComboBox::indicator}{indicator}, and \l {ComboBox::delegate}{delegate}.
 
        \image qtquickcontrols-combobox-custom.png
               {Custom styled combo box}
 
        \snippet qtquickcontrols-combobox-custom.qml file
 
        As explained in \l {ComboBox Model Roles}, ComboBox supports multiple
        types of models.
 
        Since \l {qml-data-models}{all the models provide an anonymous property}
        with \c modelData, the following expression retrieves the right text in
        all cases:
 
        \code
        text: model[control.textRole]
        \endcode
 
        When you provide a specific \c textRole and a model with structured
        data that provides the selected role, this is expression is a regular
        property lookup. When you provide a model with singular data, such as
        a list of strings, and an empty \c textRole, this expression retrieves
        the \c modelData.
 
    \section2 Customizing DelayButton
 
        DelayButton consists of two visual items: \l {Control::background}{background}
        and \l {Control::}{contentItem}.
 
        \image qtquickcontrols-delaybutton-custom.png
               {Custom styled delay button}
 
        \snippet qtquickcontrols-delaybutton-custom.qml file
 
 
    \section2 Customizing Dial
 
        Dial consists of two visual items: \l {Control::background}{background}
        and \l {Dial::handle}{handle}.
 
        \image qtquickcontrols-dial-custom.png
               {Custom styled dial}
 
        \snippet qtquickcontrols-dial-custom.qml file
 
 
    \section2 Customizing DoubleSpinBox
 
        DoubleSpinBox can be customized in the same manner as
        \l {Customizing SpinBox}{Button}.
 
 
    \section2 Customizing Drawer
 
        Drawer can have a visual \l {Control::background}{background}
        item.
 
        \code
        background: Rectangle {
            Rectangle {
                x: parent.width - 1
                width: 1
                height: parent.height
                color: "#21be2b"
            }
        }
        \endcode
 
 
    \section2 Customizing Frame
 
        Frame consists of one visual item: \l {Control::background}{background}.
 
        \image qtquickcontrols-frame-custom.png
               {Custom styled frame}
 
        \snippet qtquickcontrols-frame-custom.qml file
 
 
    \section2 Customizing GroupBox
 
        GroupBox consists of two visual items: \l {Control::background}{background}
        and \l {GroupBox::label}{label}.
 
        \image qtquickcontrols-groupbox-custom.png
               {Custom styled group box}
 
        \snippet qtquickcontrols-groupbox-custom.qml file
 
 
    \section2 Customizing ItemDelegate
 
        ItemDelegate consists of two visual items: \l {Control::background}{background}
        and \l {Control::}{contentItem}.
 
        \image qtquickcontrols-itemdelegate-custom.png
               {Custom styled item delegate}
 
        \snippet qtquickcontrols-itemdelegate-custom.qml file
 
 
    \section2 Customizing Label
 
        Label can have a visual \l {Label::background}{background} item.
 
        \image qtquickcontrols-label-custom.png
               {Custom styled label}
 
        \snippet qtquickcontrols-label-custom.qml file
 
 
    \section2 Customizing Menu
 
        \list
            \li \l Menu consists of a visual \l {Popup::background}{background} item.
            \li \l MenuItem consists of four visual items: \l {Control::background}{background},
                \l {Control::}{contentItem}, \l {AbstractButton::}{indicator}, and
                \l {MenuItem::}{arrow}.
            \li \l MenuSeparator consists of a visual \l {Control::background}{background} and
                \l {Control::}{contentItem}.
        \endlist
 
        \image qtquickcontrols-menu-custom.png
               {Custom styled menu}
 
        \quotefromfile qtquickcontrols-menu-custom.qml
        \skipto import QtQuick
        \printuntil import QtQuick.Controls.Basic
        \skipto Menu
        \printto eof
 
 
    \section2 Customizing MenuBar
 
        MenuBar can have a visual \l {Control::background}{background} item,
        and MenuBarItem consists of two visual items: \l {Control::background}
        {background} and \l {Control::}{contentItem}.
 
        \image qtquickcontrols-menubar-custom.png
               {Custom styled menu bar with File and Edit menus}
 
        \quotefromfile qtquickcontrols-menubar-custom.qml
        \skipto import QtQuick
        \printuntil import QtQuick.Controls.Basic
        \skipto MenuBar
        \printto eof
 
 
    \section2 Customizing PageIndicator
 
        PageIndicator consists of a \l {Control::background}{background}, \l {Control::}{contentItem}, and \l {PageIndicator::delegate}{delegate}.
 
        \image qtquickcontrols-pageindicator-custom.png
               {Custom styled page indicator showing multiple pages}
 
        \snippet qtquickcontrols-pageindicator-custom.qml file
 
 
    \section2 Customizing Pane
 
        Pane consists of a \l {Control::background}{background}.
 
        \image qtquickcontrols-pane-custom.png
               {Custom styled pane with decorative background}
 
        \snippet qtquickcontrols-pane-custom.qml file
 
 
    \section2 Customizing Popup
 
        Popup consists of a \l {Popup::background}{background} and
        \l {Popup::contentItem}{contentItem}.
 
        \image qtquickcontrols-popup-custom.png
               {Custom styled popup with border and shadow}
 
        \quotefromfile qtquickcontrols-popup-custom.qml
        \skipto import QtQuick
        \printuntil import QtQuick.Controls.Basic
        \codeline
        \skipto Popup
        \printuntil {
        \printuntil }
        \printuntil }
        \printuntil }
 
 
    \section2 Customizing ProgressBar
 
        ProgressBar consists of two visual items: \l {Control::background}{background}
        and \l {Control::}{contentItem}.
 
        \image qtquickcontrols-progressbar-custom.png
               {Custom styled progress bar showing partial completion}
 
        \snippet qtquickcontrols-progressbar-custom.qml file
 
        Above, the contentItem is also animated to represent an
        \l {ProgressBar::}{indeterminate} progress bar state.
 
 
    \section2 Customizing RadioButton
 
        RadioButton consists of three visual items: \l {Control::background}{background},
        \l {Control::}{contentItem} and \l {AbstractButton::indicator}{indicator}.
 
        \image qtquickcontrols-radiobutton-custom.png
               {Custom styled radio button in selected state}
 
        \snippet qtquickcontrols-radiobutton-custom.qml file
 
 
    \section2 Customizing RadioDelegate
 
        RadioDelegate consists of three visual items: \l {Control::background}{background},
        \l {Control::}{contentItem} and \l {AbstractButton::indicator}{indicator}.
 
        \image qtquickcontrols-radiodelegate-custom.png
               {Custom styled radio delegate in list}
 
        \snippet qtquickcontrols-radiodelegate-custom.qml file
 
 
    \section2 Customizing RangeSlider
 
        RangeSlider consists of three visual items:
        \l {Control::background}{background},
        \l {RangeSlider::first}{first.handle} and
        \l {RangeSlider::second.handle}{second.handle}.
 
        \image qtquickcontrols-rangeslider-custom.png
               {Custom styled range slider}
 
        \snippet qtquickcontrols-rangeslider-custom.qml file
 
 
    \section2 Customizing RoundButton
 
        RoundButton can be customized in the same manner as
        \l {Customizing Button}{Button}.
 
 
    \section2 Customizing ScrollBar
 
        ScrollBar consists of two visual items: \l {Control::background}{background}
        and \l {Control::}{contentItem}.
 
        \image qtquickcontrols-scrollbar-custom.png
               {Custom styled scroll bar}
 
        \snippet qtquickcontrols-scrollbar-custom.qml file
 
 
    \section2 Customizing ScrollIndicator
 
        ScrollIndicator consists of two visual items: \l {Control::background}{background}
        and \l {Control::}{contentItem}.
 
        \image qtquickcontrols-scrollindicator-custom.png
               {Custom styled scroll indicator}
 
        \snippet qtquickcontrols-scrollindicator-custom.qml file
 
 
    \section2 Customizing ScrollView
 
        ScrollView consists of a \l {Control::background}{background} item,
        and horizontal and vertical scroll bars.
 
        \image qtquickcontrols-scrollview-custom.png
               {Custom styled scroll view}
 
        \snippet qtquickcontrols-scrollview-custom.qml file
 
 
    \section2 Customizing Slider
 
        Slider consists of two visual items: \l {Control::background}{background},
        and \l {Slider::handle}{handle}.
 
        \image qtquickcontrols-slider-custom.png
               {Custom styled slider}
 
        \snippet qtquickcontrols-slider-custom.qml file
 
 
    \section2 Customizing SpinBox
 
        SpinBox consists of four visual items: \l {Control::background}{background},
        \l {Control::}{contentItem}, \l {SpinBox::up.indicator}{up indicator},
        and \l {SpinBox::down.indicator}{down indicator}.
 
        \image qtquickcontrols-spinbox-custom.png
               {Custom styled spin box}
 
        \snippet qtquickcontrols-spinbox-custom.qml file
 
 
    \section2 Customizing SplitView
 
        SplitView consists of a visual \l {SplitView::handle}{handle} delegate.
 
        \image qtquickcontrols-splitview-custom.png
               {Custom styled split view}
 
        \snippet qtquickcontrols-splitview-custom.qml 1
 
 
    \section2 Customizing StackView
 
        StackView can have a visual \l {Control::background}{background}
        item, and it allows customizing the transitions that are used for
        push, pop, and replace operations.
 
        \snippet qtquickcontrols-stackview-custom.qml file
 
 
    \section2 Customizing SwipeDelegate
 
        SwipeDelegate consists of six visual items: \l {Control::background}{background},
        \l {Control::}{contentItem}, \l {AbstractButton::indicator}{indicator},
        \c swipe.left, \c swipe.right, and \c swipe.behind.
 
        \image qtquickcontrols-swipedelegate-custom.png
               {Custom styled swipe delegate}
 
        \snippet qtquickcontrols-swipedelegate-custom.qml file
 
 
    \section2 Customizing SwipeView
 
        SwipeView can have a visual \l {Control::background}{background}
        item. The navigation is implemented by the \l {Control::}{contentItem}.
 
        \snippet qtquickcontrols-swipeview-custom.qml file
 
 
    \section2 Customizing Switch
 
        Switch consists of three visual items: \l {Control::background}{background},
        \l {Control::}{contentItem} and \l {AbstractButton::indicator}{indicator}.
 
        \image qtquickcontrols-switch-custom.png
               {Custom styled switch}
 
        \snippet qtquickcontrols-switch-custom.qml file
 
    \section2 Customizing SwitchDelegate
 
        SwitchDelegate consists of three visual items: \l {Control::background}{background},
        \l {Control::}{contentItem} and \l {AbstractButton::indicator}{indicator}.
 
        \image qtquickcontrols-switchdelegate-custom.png
               {Custom styled switch delegate}
 
        \snippet qtquickcontrols-switchdelegate-custom.qml file
 
 
    \section2 Customizing TabBar
 
        TabBar consists of two visual items: \l {Control::background}{background},
        and \l {Control::}{contentItem}.
 
        \image qtquickcontrols-tabbar-custom.png
               {Custom styled tab bar}
 
        \snippet qtquickcontrols-tabbar-custom.qml file
 
 
    \section2 Customizing TabButton
 
        TabButton can be customized in the same manner as
        \l {Customizing Button}{Button}.
 
 
    \section2 Customizing TextArea
 
        TextArea consists of a \l {TextArea::background}{background} item.
 
        \image qtquickcontrols-textarea-custom.png
               {Custom styled text area}
 
        \snippet qtquickcontrols-textarea-custom.qml file
 
 
    \section2 Customizing TextField
 
        TextField consists of a \l {TextField::background}{background} item.
 
        \image qtquickcontrols-textfield-custom.png
               {Custom styled text field}
 
        \snippet qtquickcontrols-textfield-custom.qml file
 
 
    \section2 Customizing ToolBar
 
        ToolBar consists of one visual item: \l {Control::background}{background}.
 
        \image qtquickcontrols-toolbar-custom.png
               {Custom styled tool bar}
 
        \snippet qtquickcontrols-toolbar-custom.qml file
 
 
    \section2 Customizing ToolButton
 
        ToolButton consists of two visual items: \l {Control::background}{background}
        and \l {Control::}{contentItem}.
 
        \image qtquickcontrols-toolbutton-custom.png
               {Custom styled tool button}
 
        \snippet qtquickcontrols-toolbutton-custom.qml file
 
 
    \section2 Customizing ToolSeparator
 
        ToolSeparator consists of two visual items: \l {Control::background}{background}
        and \l {Control::}{contentItem}.
 
        \image qtquickcontrols-toolseparator-custom.png
               {Custom styled tool separator}
 
        \snippet qtquickcontrols-toolseparator-custom.qml file
 
 
    \section2 Customizing ToolTip
 
        ToolTip consists of two visual items: \l {Popup::background}{background}
        and \l {Popup::}{contentItem}.
 
        \quotefromfile qtquickcontrols-tooltip-custom.qml
        \skipto import QtQuick
        \printuntil import QtQuick.Controls.Basic
        \skipto ToolTip
        \printuntil }
        \printuntil }
        \printuntil }
 
        \include qquicktooltip.qdocinc customize-note
 
    \section2 Customizing Tumbler
 
        Tumbler consists of three visual items:
        \l {Control::background}{background},
        \l {Control::}{contentItem}, and
        \l {Tumbler::delegate}{delegate}.
 
        \image qtquickcontrols-tumbler-custom.png
               {Custom styled tumbler}
 
        \snippet qtquickcontrols-tumbler-custom.qml file
 
        If you want to define your own contentItem, use either a \l ListView or
        \l PathView as the root item. For a wrapping Tumbler, use PathView:
 
        \snippet qtquickcontrols-tumbler-pathView.qml contentItem
 
        For a non-wrapping Tumbler, use ListView:
 
        \snippet qtquickcontrols-tumbler-listView.qml contentItem
 
    \section2 Customizing TableViewDelegate
 
        TableViewDelegate inherits \l ItemDelegate, which means that it's composed of two
        visual items:
        \l [QML]{Control::}{background} and
        \l [QML]{Control::}{contentItem}.
 
        You can always assign your own custom edit delegate to
        \l [QML]{TableView::}{editDelegate} if you have needs
        outside what the default edit delegate offers.
 
        \image qtquickcontrols-tableviewdelegate-custom.png
               {Custom styled table view delegate}
 
        \snippet qtquickcontrols-tableviewdelegate-custom.qml delegate
 
    \section2 Customizing HeaderViewDelegate
 
        HeaderViewDelegate inherits \l TableViewDelegate, which means that it's
        composed of two items:
        \l [QML]{Control::}{background} and
        \l [QML]{Control::}{contentItem}.
        You can always customize them with any arbitrary items.
 
        \image qtquickcontrols-headerviewdelegate-custom.png
               {Custom styled header view delegate}
 
        Here is an example of customizing the horizontal header view delegate:
 
        \snippet qtquickcontrols-headerviewdelegate-custom.qml horizontal-delegate
 
        Here is an example of customizing the vertical header view delegate:
 
        \snippet qtquickcontrols-headerviewdelegate-custom.qml vertical-delegate
 
    \section1 Styling Controls using StyleKit
 
    The \l{Qt Labs StyleKit} module provides a set of QML types for styling
    Qt Quick Controls, built on top of \l{Qt Quick Templates}.
    It lets you define a complete visual style for
    all your controls from a single Style object, including support for
    themes, state-based styling, and transitions. StyleKit handles the
    underlying template implementation automatically, letting you focus
    purely on visual aspects such as colors, dimensions, borders, and shadows.
 
    The \l{Qt Labs StyleKit} module is a Technology Preview module in
    Qt 6.11.
 
*/