path: root/doc/qtcreator/src/qtquick/qtquick-components.qdoc

/****************************************************************************
**
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
**
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
**
****************************************************************************/

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
    \page quick-components.html
    \if defined(qtdesignstudio)
    \previouspage studio-app-flows.html
    \else
    \previouspage creator-using-qt-quick-designer.html
    \endif
    \nextpage qtquick-form-editor.html

    \title Creating Components

    A \l{glossary-component}{component} provides a way of defining a new visual item
    that you can re-use in other QML files. A component is like a black box; it
    interacts with the outside world through properties, signals, and slots, and
    is generally defined in its own QML file. You can import components to
    applications.

    The \uicontrol {Library} view lists the available QML types, UI
    components, assets, and QML imports.

    \image qmldesigner-qml-components.png "QML Components"

    The \uicontrol {QML Types} tab displays the QML types grouped by category,
    such as your own QML components, basic types, layouts, positioner types, and
    views.

    Sets of UI components with the look and feel of a particular mobile device
    platform have been defined for Qt Quick 1. Since Qt 5.1, ready-made Qt
    Quick Controls, Dialogs, and Layouts are available for creating user
    interfaces using Qt Quick 2. The components and controls are based on
    standard QML types. To view the components and controls in
    \uicontrol {Library}, import the component sets in \uicontrol {QML Imports}.

    The \uicontrol {Qt Quick Application} wizards for a particular platform add
    the import statements automatically. You can remove import statements in
    \uicontrol {QML Imports}.

    \uicontrol {Assets} displays the images and other files that you import to
    the project folder by selecting \uicontrol {Add New Assets}.

    \section1 Adding Components to Designs

    \image qmldesigner-editing-components.png "Editing QML components in Design mode"

    \list 1
        \li Drag and drop components from \uicontrol Library (1) to
            \uicontrol Navigator (2) or \uicontrol {Form Editor} (3).
        \li Select components in \uicontrol Navigator to edit the
            values of their properties in \uicontrol Properties.
            \image qmldesigner-properties-view.png "Properties view"
            For more information, see \l {Specifying Item Properties}.
        \li To change the appearance and behavior of your components in ways
            that are not supported out of the box, you can define custom
            properties for your components in the \uicontrol Connections view,
            \uicontrol Properties tab.
            \image qmldesigner-dynamicprops.png "Connections view Properties tab"
            For more information, see \l{Specifying Dynamic Properties}.
        \li To enable users to interact with components, connect the components
            to signals in the \uicontrol Connections view. For example, you can
            specify what happens when a component is clicked.
            For more information, see \l{Connecting Objects to Signals}.
            \image qmldesigner-connections.png "Connections view Connections tab"
        \li To dynamically change the behavior of an object when another object
            changes, create bindings between components in the
            \uicontrol Connections view, \uicontrol Bindings tab.
            For more information, see \l{Adding Bindings Between Properties}.
            \image qmldesigner-bindings.png "Connections view Bindings tab"
        \li Add states to apply sets of changes to the property values of one
            or several components in the \uicontrol States view.
            For more information, see \l{Adding States}.
        \li Animate component properties in the \uicontrol Timeline view.
            For more information, see \l{Creating Animations}.
    \endlist

    \section1 Using Basic QML Types

    You can use the following QML types to create components:

    \list
        \li \l [QtQuick]{AnimatedImage}{Animated Image} provides a way to play
            animations stored as images containing a series of frames, such
            as those stored in GIF files.
        \li \l [QtQuick]{BorderImage}{Border Image} uses an image as a border or
            background.
        \li \l [QtQuick]{Image} adds a bitmap to the scene. You can stretch and
            tile images.
        \li \l [QtQuick]{Item} is the most basic of all visual types in QML. Even
            though it has no visual appearance, it defines all the properties
            that are common across visual types, such as the x and y position,
            width and height, anchoring, and key handling.
        \li \l [QtQuick] {Rectangle} adds a rectangle that is painted with a solid
            fill color and an optional border. You can use the radius property
            to create rounded rectangles.
        \li \l [QtQuick]{Text} adds formatted read-only text.
        \li \l [QtQuick]{TextEdit}{Text Edit} adds a single line of editable
            formatted text that can be validated.
        \li \l [QtQuick]{TextInput}{Text Input} adds a single line of editable
            plain text that can be validated.
    \endlist

    \section1 Using Data Models

    You can create the following types of views to organize items provided by
    \l{Models and Views in Qt Quick}{data models}:

    \list
        \li \l{GridView}{Grid View} provides a grid vizualization of a model.
        \li \l{ListView}{List View} provides a list vizualization of a model.
        \li \l{PathView}{Path View} visualizes the contents of a model along a
            path. For more information, see \l{Editing PathView Properties}.
        \li \l [QtQuickControls] {ScrollView}{Scroll View} provides scrolling
            for user-defined content. It can be used instead of a \l Flickable
            item.
        \li \l [QtQuickControls] {StackView}{Stack View} provides a stack-based
            navigation model.
        \li \l[QtQuickControls] {SwipeView}{Swipe View} enables users to
            navigate pages by swiping sideways.
    \endlist

    When you add a \l{GridView}{Grid View}, \l{ListView}{List View}, or
    \l{PathView}{Path View}, the ListModel and the delegate component that
    creates an instance for each item in the model are added automatically.
    You can edit item properties in \uicontrol Properties or in
    \uicontrol {Text Editor}. You can also replace the default model and
    delegate with other, more complex models and delegates in
    \uicontrol {Text Editor}. \l{ItemDelegate}{Item Delegate} and
    \l{SwipeDelegate}{Swipe Delegate} delegate components are also available
    in \uicontrol Library.

    \section1 Positioning Items in UIs

    The position of an item in the UI can be either absolute or
    relative to other items. If you are designing a static UI,
    \l{Important Concepts In Qt Quick - Positioning#manual-positioning}
    {manual positioning} provides the most efficient form of positioning
    items. For a dynamic UI, you can employ the following positioning
    methods provided by Qt Quick:

    \list
        \li \l{Setting Bindings}
        \li \l{Setting Anchors and Margins}
        \li \l{Aligning and Distributing Items}
        \li \l{Using Positioners}
        \li \l{Using Layouts}
        \li \l{Organizing Items}
    \endlist

    \section2 Setting Bindings

    \l{Positioning with Bindings} {Property binding} is a declarative way of
    specifying the value of a property. Binding allows a property value to be
    expressed as a JavaScript expression that defines the value relative to
    other property values or data accessible in the application. The property
    value is automatically kept up to date if the other properties or data
    values change.

    Property bindings are created implicitly in QML whenever a property is
    assigned a JavaScript expression. To set JavaScript expressions as values
    of properties in the Design mode, select the
    \inlineimage icons/action-icon.png
    (\uicontrol Actions) menu next to a property, and then select
    \uicontrol {Set Binding}.

    \image qmldesigner-set-expression.png "Type properties context menu"

    In \uicontrol {Binding Editor}, select an item and a property from
    lists of available items and their properties.

    \image qmldesigner-binding-editor.png "Binding Editor"

    Alternatively, start typing a
    string and press \key Ctrl+Space to display a list of properties, IDs, and
    code snippets. When you enter a period (.) after a property name, a list of
    available values is displayed. Press \key Enter to accept the first
    suggestion in the list and to complete the code.

    When a binding is set, the \uicontrol Actions menu icon changes to
    \inlineimage icons/action-icon-binding
    . To remove bindings, select \uicontrol Actions > \uicontrol Reset.

    You can set bindings also in the \uicontrol Connections view. For more
    information, see \l {Adding Bindings Between Properties}.

    For more information on the JavaScript environment provided by QML, see
    \l{Integrating QML and JavaScript}.

    Bindings are a black box for the Design mode and using them might have a
    negative impact on performance, so consider setting anchors and margins for
    items, instead. For example, instead of setting \c {parent.width} for an
    item, you could anchor the item to its sibling items on the left and the
    right.

    \section2 Setting Anchors and Margins

    In an \l{Important Concepts In Qt Quick - Positioning#anchors}
    {anchor-based} layout, each QML type can be thought of as having a set of
    invisible \e anchor lines: top, bottom, left, right, fill, horizontal
    center, vertical center, and baseline.

    In the \uicontrol Layout tab you can set anchors and margins for items. To
    set the anchors of an item, click the anchor buttons. You can combine the
    top/bottom, left/right, and horizontal/vertical anchors to anchor items in
    the corners of the parent item or center them horizontally or vertically
    within the parent item.

    \image qmldesigner-anchor-buttons.png "Anchor buttons"

    For convenience, you can click the \inlineimage anchor-fill.png
    (\uicontrol {Fill to Parent}) toolbar button to apply fill anchors to an
    item and the \inlineimage qtcreator-anchors-reset-icon.png
    (\uicontrol {Reset Anchors}) button to reset the anchors to their saved
    state.

    You can specify the baseline anchor in \uicontrol {Text Editor} in the
    Design mode.

    For performance reasons, you can only anchor an item to its siblings
    and direct parent. By default, an item is anchored to its parent when
    you use the anchor buttons. Select a sibling of the item in the
    \uicontrol Target field to anchor to it, instead.

    Arbitrary anchoring is not supported. For example, you cannot specify:
    \c {anchor.left: parent.right}. You have to specify:
    \c {anchor.left: parent.left}. When you use the anchor buttons, anchors to
    the parent item are always specified to the same side. However, anchors to
    sibling items are specified to the opposite side:
    \c {anchor.left: sibling.right}. This allows you to keep sibling items
    together.

    In the following image, \uicontrol{Rectangle 2} is anchored to
    \uicontrol {Rectangle 1} on its left and to the bottom of its parent.

    \image qmldesigner-anchors.png "Anchoring sibling items"

    The anchors for \uicontrol{Rectangle 2} are specified as follows in code:

    \qml
    Rectangle {
        id: rectangle2
        anchors.left: rectangle1.right
        anchors.leftMargin: 10
        anchors.bottom: parent.bottom
        anchors.bottomMargin: 10
        //
    }
    \endqml

    Margins specify the amount of empty space to leave to the outside of an
    item. Margins only have meaning for anchors. They do not take any effect
    when using layouts or absolute positioning.

    \section2 Aligning and Distributing Items

    When you're working with a group of items, you can select them to align
    and distribute them evenly. As the positions of the items are fixed, you
    cannot apply these functions to anchored items. For scalability, you can
    anchor the aligned and distributed items when your design is ready.

    \image qmldesigner-alignment.png "Aligning sibling items"

    Select the buttons in the \uicontrol Align group to align the top/bottom
    or left/right edges of the items in the group to the one farthest away from
    the center of the group. For example, when left-aligning, the items are
    aligned to the leftmost item. You can also align the horizontal/vertical
    centers of items, or both, as in the image above.

    In the \uicontrol {Align to} field, select whether to align the items in
    respect to the selection, the root item, or a \e {key object} that you
    select in the \uicontrol {Key object} field. The key object must be a part
    of the selection.

    You can distribute either \e objects or the \e spacing between them. If the
    objects or spacing cannot be distributed to equal pixel values without
    ending up with half pixels, you receive a notification. You can either allow
    \QDS to distribute objects or spacing using the closest values possible or
    tweak your design so that the objects and spacing can be distributed
    perfectly.

    When distributing objects, you can select whether the distance between
    them is calculated from their top/bottom or left/right edges or their
    horizontal/vertical center.

    \image qmldesigner-distribute-objects.png "Distribute objects buttons"

    You can distribute spacing either evenly within a target area or at
    specified distances, calculated from a starting point.

    You can select the orientation in which the objects are distributed evenly
    within the target area: horizontally along the x axis or vertically along
    the y axis.

    \image qmldesigner-distribute-spacing-evenly.png "Distribute spacing evenly"

    Alternatively, you can distribute spacing in pixels by selecting one of the
    starting point buttons: left/right or top/bottom edge of the target area,
    or its horizontal/vertical center. Note that some items might end up outside
    the target area.

    \image qmldesigner-distribute-spacing-pixels.png "Distribute spacing in pixels"

    You can set the space between objects in pixels. You can
    disable the distribution of spacing in pixels by clicking
    the \inlineimage qmldesigner-distribute-spacing-x.png
    button.

    \section2 Using Positioners

    \l{Important Concepts In Qt Quick - Positioning#positioners}
    {Positioner items} are container items that manage the positions of items
    in a declarative user interface. Positioners behave in a similar way to
    the layout managers used with standard Qt widgets, except that they are
    also containers in their own right.

    You can use the following positioners to arrange items in UIs:

    \list
        \li \l[QtQuick] {Column} arranges its child items vertically.
        \li \l[QtQuick] {Row} arranges its child items horizontally.
        \li \l[QtQuick] {Grid}
            arranges its child items so that they are aligned in a grid and
            are not overlapping.
        \li \l[QtQuick] {Flow}
            arranges its child items side by side, wrapping as necessary.
    \endlist

    To position several items in a \uicontrol Column, \uicontrol Row,
    \uicontrol Grid, or \uicontrol Flow, select the items in
    \uicontrol {Form Editor}, and then select \uicontrol Position in
    the context menu.

    \section2 Using Layouts

    Since Qt 5.1, you can use QML types in the \l{qtquicklayouts-index.html}
    {Qt Quick Layouts} module to arrange Qt Quick items in UIs. Unlike
    positioners, they manage both the positions and sizes of items in a
    declarative interface. They are well suited for resizable UIs.

    You can use the following layout types to arrange items in UIs:

    \list
        \li \l{ColumnLayout}{Column Layout} provides a grid layout with only
            one column.
        \li \l{RowLayout}{Row Layout} provides a grid layout with only one row.
        \li \l{GridLayout}{Grid Layout} provides a way of dynamically arranging
            items in a grid.
        \li \l{StackLayout}{Stack Layout} provides a stack of items where only
            one item is visible at a time.
    \endlist

    To lay out several items in a column, row, grid, or
    \uicontrol {Stack Layout}, select the items in \uicontrol {Form Editor},
    and then select \uicontrol Layout in the context menu.

    You can also click the \inlineimage column.png
    (\uicontrol {Column Layout}), \inlineimage row.png
    (\uicontrol {Row Layout}), and \inlineimage grid.png
    (\uicontrol {Grid Layout}) toolbar buttons to apply
    layouts to the selected items.

    To make an item within a layout as wide as possible while respecting the
    given constraints, select the item in \uicontrol {Form Editor}, and then
    select \uicontrol Layout > \uicontrol {Fill Width} in the context menu. To
    make the item as high as possible, select \uicontrol {Fill Height}.

    \section2 Editing Stack Layouts

    \image qtquick-designer-stacked-view.png

    To add items to a \uicontrol {Stack Layout}, select the
    \inlineimage plus.png
    button next to the type name in \uicontrol {Form Editor}. To move
    between items, select the \inlineimage prev.png
    (\uicontrol Previous) and \inlineimage next.png
    (\uicontrol Next) buttons.

    To add a tab bar to a stack layout, select \uicontrol {Stacked Container} >
    \uicontrol {Add Tab Bar}.

    To raise or lower the stacking order of an item, select
    \uicontrol {Stacked Container} > \uicontrol {Increase Index} or
    \uicontrol {Decrease Index}.

    \section2 Organizing Items

    Since Qt 5.7, you can use the following \l{Qt Quick Controls} types to
    organize items in UIs:

    \list
        \li \l [QtQuickControls]{Frame} places a logical group of controls
            within a visual frame.
        \li \l [QtQuickControls]{GroupBox}{Group Box} is used to lay out a
            logical group of controls together, within a titled visual frame.
        \li \l [QtQuickControls]{Label} is a text label with inherited styling
            and font.
        \li \l [QtQuickControls]{Page} provides a styled page control with
            support for a header and footer.
        \li \l [QtQuickControls]{PageIndicator}{Page Indicator} indicates the
            currently active page.
        \li \l [QtQuickControls]{Pane} provides a background matching with the
            application style and theme.
    \endlist

    \section1 Adding User Interaction Methods

    You can use the following QML types to add basic interaction methods to
    UIs:

    \list
        \li \l{Flickable}
            items can be flicked horizontally or vertically.
        \li \l{FocusScope}{Focus Scope}
            assists in keyboard focus handling when building reusable QML
            components.
        \li \l [QtQuick]{MouseArea}{Mouse Area} enables simple mouse handling.
    \endlist

    Since Qt 5.7, you can also use the following \l{Qt Quick Controls} types
    to inform users about the progress of the application or to gather input
    from the user:

    \list
        \li \l [QtQuickControls]{BusyIndicator}{Busy Indicator} indicates
            activity while content is being loaded.
        \li \l [QtQuickControls]{Button} provides a push button that you can
            associate with an action.
        \li \l [QtQuickControls]{CheckBox}{Check Box} provides an option button
            that can be toggled on (checked) or off (unchecked).
        \li \l [QtQuickControls]{CheckDelegate}{Check Delegate} presents an
            item delegate that can be toggled on (checked) or off (unchecked).
        \li \l [QtQuickControls]{ComboBox}{Combo Box} is a combined button and
            popup list that is populated by using a data model.
        \li \l [QtQuickControls]{DelayButton}{Delay Button} provides an option
            button that is triggered when held down long enough.
        \li \l [QtQuickControls]{Dial} is a circular dial that is rotated to
            set a value.
        \li \l [QtQuickControls]{ProgressBar}{Progress Bar} indicates the
            progress of an operation.
        \li \l [QtQuickControls]{RadioButton}{Radio Button} provides an option
            button that can be switched on (checked) or off (unchecked).
        \li \l [QtQuickControls]{RadioDelegate}{Radio Delegate} presents an
            item delegate that can be toggled on (checked) or off (unchecked).
        \li \l [QtQuickControls]{RangeSlider}{Range Slider} enables users to
            select a range of values by sliding two handles along a track.
        \li \l [QtQuickControls]{RoundButton}{Round Button} provides a push
            button with rounded corners that you can associate with an action.
        \li \l [QtQuickControls]{Slider} selects a value by sliding a handle
            along a track.
        \li \l [QtQuickControls]{SpinBox}{Spin Box} enables the user to specify
            a value by clicking the up or down buttons, by pressing up or down
            on the keyboard, or by entering a value in the box.
        \li \l [QtQuickControls]{Switch} is an option button that can be
            toggled on or off.
        \li \l [QtQuickControls]{SwitchDelegate}{Switch Delegate} presents an
            item delegate with a switch indicator that can be toggled on or off.
        \li \l [QtQuickControls] {TabBar}{Tab Bar} enables users to switch
            between different views or subtasks.
        \li \l [QtQuickControls]{TabButton}{Tab Button} is a button
            that is functionally similar to \uicontrol Button, but provides a
            look that is more suitable for a \uicontrol {Tab Bar}.
        \li \l [QtQuickControls]{TextArea}{Text Area} displays multiple lines
            of editable formatted text.
        \li \l [QtQuickControls]{TextField}{Text Field} displays a single line
            of editable plain text.
        \li \l [QtQuickControls]{ToolBar}{Tool Bar} is a container of
            application-wide and context sensitive actions and controls, such as
            navigation buttons and search fields.
        \li \l [QtQuickControls]{ToolButton}{Tool Button} is a button
            that is functionally similar to \uicontrol Button, but provides a
            look that is more suitable for a \uicontrol {Tool Bar}.
        \li \l [QtQuickControls]{ToolSeparator}{Tool Separator} separates a
            group of items from adjacent items on a \uicontrol {Tool Bar}.
        \li \l [QtQuickControls]{Tumbler} is a spinnable wheel of items that
            can be selected.
    \endlist

    You can also use the \l Dialog type in the Qt Quick Dialogs module to wrap
    arbitrary content into a dialog window including a row of platform-tailored
    buttons.

    \include qtquick-animation-types.qdocinc qtquick animation types

    \if defined(qtdesignstudio)
    \include qtdesignstudio-visual-effects.qdocinc qml visual effects
    \include qtdesignstudio-components.qdocinc creating studio components
    \include qtdesignstudio-components.qdocinc studio components
    \endif

    \section1 History of Qt Quick Controls

    In Qt 4, ready-made Qt Quick 1 Components were provided for creating
    UIs with a native look and feel for a particular target platform.
    In Qt 5.1, Qt Quick Controls, Dialogs, and Layouts were added for
    creating classic desktop-style user interfaces using Qt Quick 2.1. The
    Qt Quick Controls Styles could be used to customize Qt Quick Controls.

    Since Qt 5.7, \l {Qt Quick Controls 2} replace Qt Quick Controls 1 and
    Qt Labs Controls. They provide lightweight QML types for creating performant
    user interfaces for \l{glossary-device}{devices}.

    Qt Quick Controls 2 achieve improved efficiency by employing a simplified
    \l {Styling Qt Quick Controls}{styling architecture} when compared to
    Qt Quick Controls, on which the module is based. The visual editor reads the
    \c qtquickcontrols2.conf file that specifies the preferred style and some
    style-specific arguments. To change the style, select another style from
    the list on the toolbar. This enables you to check how your UI looks when
    using the available styles.

    For an example of defining your own style and using it in the Design mode, see
    \l {Qt Quick Controls 2 - Flat Style}.

    For more information about how to customize a particular control, see
    \l{Customization Reference}.

    Qt Quick Controls 2 work in conjunction with Qt Quick and Qt Quick Layouts.

    The \QC project wizards create Qt Quick applications that use Qt Quick
    2 types or Qt Quick Controls 2 types.

    Even if you use Qt Quick Controls 2, you can still write cross-platform
    applications, by using different sets of QML files for each platform.

    Some ready-made controls, such as a gauge, dial, status indicator, and
    tumbler, are provided by the \l {Qt Quick Extras} module.

    \section1 Creating Components in Design Mode

    \list 1

        \li Select \uicontrol File > \uicontrol {New File or Project} >
            \if defined(qtcreator)
            \uicontrol Qt > \uicontrol {QML File (Qt Quick 2)} >
            \else
            \uicontrol {Qt Quick Files} > \uicontrol {Qt Quick File} >
            \endif
            \uicontrol Choose to create a new .qml file.

            \note Components are listed in the \uicontrol {My QML Components}
            tab in the \uicontrol Library view only if the filename begins with
            a capital letter.

        \li Click \uicontrol Design to open the .qml file in the Design mode.

        \li Drag and drop a QML type from \uicontrol Library to
            \uicontrol Navigator or \uicontrol {Form Editor}.

        \li Edit its properties in \uicontrol Properties.

            The available properties depend on the QML type.

    \endlist

    The following sections contain more information about how to use
    \uicontrol {Form Editor} to edit 2D content, as well as examples of
    how to create some common components using basic QML types:

    \list

        \li \l{Editing 2D Content}

        \li \l{Creating Buttons}

        \li \l{Creating Scalable Buttons and Borders}

    \endlist

    \section1 Moving Within Components

    Components can consist of several other components. To view the component
    hierarchy as a bread crumb path when you edit a component in
    \uicontrol {Form Editor}, select \uicontrol {Go into Component} or press
    \key F2. Click the component names in the path to navigate to them. You
    can easily navigate back to the top level when you are done editing the
    component.

    \image qmldesigner-breadcrumbs.png "Go into Component command"
*/