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

    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
    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. There are two
    ways to expose such types to QML:

    \list
    \li 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():

        \code
        qmlRegisterType<ACoolCppItem>("MyApp", 1, 0, "ACoolItem");
        \endcode

        See \l {Using C++ Data From QML} for more information about this.
    \li 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
        \l {Creating C++ Plugins for QML}{QML plugin}.

        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 \c qmldir file must be present in the same directory as the QML
        files.
    \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 {Qt Creator: Project Types}{create a new Qt Quick
    Controls application} in Qt Creator. After that, we
    \l {Qt Creator: Creating 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:

    \code
    // ...
    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
        }
    }
    \endcode

    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

    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

    \section2 Customizing ApplicationWindow

        ApplicationWindow consists of one visual item:
        \l {ApplicationWindow::background}{background}.

        \code
        import QtQuick
        import QtQuick.Controls

        ApplicationWindow {
            visible: true

            background: Rectangle {
                gradient: Gradient {
                    GradientStop { position: 0; color: "#ffffff" }
                    GradientStop { position: 1; color: "#c1bbf9" }
                }
            }
        }
        \endcode


    \section2 Customizing BusyIndicator

        BusyIndicator consists of two visual items: \l {Control::background}{background}
        and \l {Control::contentItem}{contentItem}.

        \image qtquickcontrols-busyindicator-custom.png

        \snippet qtquickcontrols-busyindicator-custom.qml file


    \section2 Customizing Button

        Button consists of two visual items: \l {Control::background}{background}
        and \l {Control::contentItem}{content item}.

        \image qtquickcontrols-button-custom.png

        \snippet qtquickcontrols-button-custom.qml file


    \section2 Customizing CheckBox

        CheckBox consists of three visual items: \l {Control::background}{background},
        \l {Control::contentItem}{contentItem} and \l {AbstractButton::indicator}{indicator}.

        \image qtquickcontrols-checkbox-custom.png

        \snippet qtquickcontrols-checkbox-custom.qml file

    \section2 Customizing CheckDelegate

        CheckDelegate consists of three visual items: \l {Control::background}{background},
        \l {Control::contentItem}{contentItem} and \l {AbstractButton::indicator}{indicator}.

        \image qtquickcontrols-checkdelegate-custom.png

        \snippet qtquickcontrols-checkdelegate-custom.qml file


    \section2 Customizing ComboBox

        ComboBox consists of \l {Control::background}{background},
        \l {Control::contentItem}{content item}, \l {ComboBox::popup}{popup},
        \l {ComboBox::indicator}{indicator}, and \l {ComboBox::delegate}{delegate}.

        \image qtquickcontrols-combobox-custom.png

        \snippet qtquickcontrols-combobox-custom.qml file

        As explained in \l {ComboBox Model Roles}, ComboBox supports multiple
        types of models. If you know that your ComboBox instances will only
        ever use one particular type of model, then it is possible to simplify
        the code above.

        For example, if your models will only ever be derived from
        \l QAbstractItemModel and have more than one role, the following
        binding is sufficient:

        \code
        text: model[control.textRole]
        \endcode

        However, if you want to support all standard models, the more complex
        binding is necessary, and is explained in detail below.

        \quotefromfile qtquickcontrols-combobox-custom.qml
        \skipto control.textRole
        \printto Array.isArray

        The first line checks if the \l {ComboBox::}{textRole} property has
        been set. It is only necessary to set this property if the model
        has more than one role.

        \printline Array.isArray

        If \c textRole has been set, the next step is to check if the model
        is an array.

        If it is an array, the \c modelData context property will be available,
        and so it must be used. Square bracket notation is used to access
        the property of modelData since the property name is not known ahead
        of time.

        If it is not an array, the \c model context property must be used
        instead.

        \printline modelData

        Finally, if \c textRole has not been set, then the model only has one
        role, and so it is sufficient to use the value of \c modelData.

    \section2 Customizing DelayButton

        DelayButton consists of two visual items: \l {Control::background}{background}
        and \l {Control::contentItem}{content item}.

        \image qtquickcontrols-delaybutton-custom.png

        \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

        \snippet qtquickcontrols-dial-custom.qml file


    \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

        \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

        \snippet qtquickcontrols-groupbox-custom.qml file


    \section2 Customizing ItemDelegate

        ItemDelegate consists of two visual items: \l {Control::background}{background}
        and \l {Control::contentItem}{content item}.

        \image qtquickcontrols-itemdelegate-custom.png

        \snippet qtquickcontrols-itemdelegate-custom.qml file


    \section2 Customizing Label

        Label can have a visual \l {Label::background}{background} item.

        \image qtquickcontrols-label-custom.png

        \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}{content item}, \l {AbstractButton::}{indicator}, and
                \l {MenuItem::}{arrow}.
            \li \l MenuSeparator consists of a visual \l {Control::background}{background} and
                \l {Control::contentItem}{content item}.
        \endlist

        \image qtquickcontrols-menu-custom.png

        \quotefromfile qtquickcontrols-menu-custom.qml
        \skipto import QtQuick
        \printuntil import QtQuick.Controls
        \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}{content item}.

        \image qtquickcontrols-menubar-custom.png

        \quotefromfile qtquickcontrols-menubar-custom.qml
        \skipto import QtQuick
        \printuntil import QtQuick.Controls
        \skipto MenuBar
        \printto eof


    \section2 Customizing PageIndicator

        PageIndicator consists of a \l {Control::background}{background}, \l {Control::contentItem}{content item}, and \l {PageIndicator::delegate}{delegate}.

        \image qtquickcontrols-pageindicator-custom.png

        \snippet qtquickcontrols-pageindicator-custom.qml file


    \section2 Customizing Pane

        Pane consists of a \l {Control::background}{background}.

        \image qtquickcontrols-pane-custom.png

        \snippet qtquickcontrols-pane-custom.qml file


    \section2 Customizing Popup

        Popup consists of a \l {Popup::background}{background} and
        \l {Popup::contentItem}{content item}.

        \image qtquickcontrols-popup-custom.png

        \quotefromfile qtquickcontrols-popup-custom.qml
        \skipto import QtQuick
        \printuntil import QtQuick.Controls
        \codeline
        \skipto Popup
        \printuntil {
        \printuntil }
        \printuntil }
        \printuntil }


    \section2 Customizing ProgressBar

        ProgressBar consists of two visual items: \l {Control::background}{background}
        and \l {Control::contentItem}{content item}.

        \image qtquickcontrols-progressbar-custom.png

        \snippet qtquickcontrols-progressbar-custom.qml file


    \section2 Customizing RadioButton

        RadioButton consists of three visual items: \l {Control::background}{background},
        \l {Control::contentItem}{content item} and \l {AbstractButton::indicator}{indicator}.

        \image qtquickcontrols-radiobutton-custom.png

        \snippet qtquickcontrols-radiobutton-custom.qml file


    \section2 Customizing RadioDelegate

        RadioDelegate consists of three visual items: \l {Control::background}{background},
        \l {Control::contentItem}{contentItem} and \l {AbstractButton::indicator}{indicator}.

        \image qtquickcontrols-radiodelegate-custom.png

        \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

        \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}{content item}.

        \image qtquickcontrols-scrollbar-custom.png

        \snippet qtquickcontrols-scrollbar-custom.qml file


    \section2 Customizing ScrollIndicator

        ScrollIndicator consists of two visual items: \l {Control::background}{background}
        and \l {Control::contentItem}{content item}.

        \image qtquickcontrols-scrollindicator-custom.png

        \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

        \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

        \snippet qtquickcontrols-slider-custom.qml file


    \section2 Customizing SpinBox

        SpinBox consists of four visual items: \l {Control::background}{background},
        \l {Control::contentItem}{contentItem}, \l {SpinBox::up.indicator}{up indicator},
        and \l {SpinBox::down.indicator}{down indicator}.

        \image qtquickcontrols-spinbox-custom.png

        \snippet qtquickcontrols-spinbox-custom.qml file


    \section2 Customizing SplitView

        SplitView consists of a visual \l {SplitView::handle}{handle} delegate.

        \image qtquickcontrols-splitview-custom.png

        \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}{content item}, \l {AbstractButton::indicator}{indicator},
        \c swipe.left, \c swipe.right, and \c swipe.behind.

        \image qtquickcontrols-swipedelegate-custom.png

        \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}
        {content item}.

        \snippet qtquickcontrols-swipeview-custom.qml file


    \section2 Customizing Switch

        Switch consists of three visual items: \l {Control::background}{background},
        \l {Control::contentItem}{content item} and \l {AbstractButton::indicator}{indicator}.

        \image qtquickcontrols-switch-custom.png

        \snippet qtquickcontrols-switch-custom.qml file

    \section2 Customizing SwitchDelegate

        SwitchDelegate consists of three visual items: \l {Control::background}{background},
        \l {Control::contentItem}{contentItem} and \l {AbstractButton::indicator}{indicator}.

        \image qtquickcontrols-switchdelegate-custom.png

        \snippet qtquickcontrols-switchdelegate-custom.qml file


    \section2 Customizing TabBar

        TabBar consists of two visual items: \l {Control::background}{background},
        and \l {Control::contentItem}{contentItem}.

        \image qtquickcontrols-tabbar-custom.png

        \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

        \snippet qtquickcontrols-textarea-custom.qml file


    \section2 Customizing TextField

        TextField consists of a \l {TextField::background}{background} item.

        \image qtquickcontrols-textfield-custom.png

        \snippet qtquickcontrols-textfield-custom.qml file


    \section2 Customizing ToolBar

        ToolBar consists of one visual item: \l {Control::background}{background}.

        \image qtquickcontrols-toolbar-custom.png

        \snippet qtquickcontrols-toolbar-custom.qml file


    \section2 Customizing ToolButton

        ToolButton consists of two visual items: \l {Control::background}{background}
        and \l {Control::contentItem}{content item}.

        \image qtquickcontrols-toolbutton-custom.png

        \snippet qtquickcontrols-toolbutton-custom.qml file


    \section2 Customizing ToolSeparator

        ToolSeparator consists of two visual items: \l {Control::background}{background}
        and \l {Control::contentItem}{content item}.

        \image qtquickcontrols-toolseparator-custom.png

        \snippet qtquickcontrols-toolseparator-custom.qml file


    \section2 Customizing ToolTip

        ToolTip consists of two visual items: \l {Popup::background}{background}
        and \l {Popup::contentItem}{content item}.

        \quotefromfile qtquickcontrols-tooltip-custom.qml
        \skipto import QtQuick
        \printuntil import QtQuick.Controls
        \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}{contentItem}, and
        \l {Tumbler::delegate}{delegate}.

        \image qtquickcontrols-tumbler-custom.png

        \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
*/
