// 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.

*/
