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

    \section1 QML Imports

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

    \section1 Assets

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

    When you drag and drop assets from the tab to \uicontrol Navigator or
    \uicontrol {Form Editor}, QML components with a suitable type are
    automatically created for you. For example, when using graphical
    assets to create components, the components will be of the Image type.

    \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 Component Types

    The following sections describe the types of components that you can create
    in the Design mode.

    \list
        \li \l Shapes
        \li \l Images
        \li \l {User Interaction Methods}
        \li \l {Lists and Other Data Models}
    \endlist

    \section2 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

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

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

    \include qtquick-mcu-support.qdocinc mcu qtquick components

    \section1 Styling Controls

    Qt Quick Controls provide lightweight QML types for creating performant
    user interfaces for \l{glossary-device}{devices}. The controls can be
    \l {Styling Qt Quick Controls}{styled}. 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.

    \image qtquick-designer-style-list.png "Style menu on the toolbar"

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

    \if defined(qtcreator)
    \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 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.
    \endif

    \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

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

    \section1 Moving Components into Separate Files

    An alternative way of creating reusable components is to move them into
    separate QML files. Right-click a component in the \uicontrol Navigator
    or \uicontrol {Form Editor} view and select
    \uicontrol {Move Component into Separate File} in the context menu.

    \image qtcreator-move-component-into-separate-file.png

    Give the new component a name and select whether properties are set for
    the new component or for the original one.

    For an example of creating a reusable custom component, see
    \if defined(qtcreator)
    \l{Creating a Mobile Application}.
    \else
    \l{Progress Bar}.
    \endif

    \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"

    \section1 Merging Files with Templates

    You can merge the current QML file against an existing second QML file and
    using the second QML file in a way similar to using a CSS stylesheet.

    To use this experimental feature, right-click a component in the
    \uicontrol Navigator or \uicontrol {Form Editor} view and select
    \uicontrol {Merge File with Template} in the context menu.

    \image qmldesigner-merge-with-template.png "Merge with Template dialog"

    In the \uicontrol Template field, select the file to use as a template.
*/