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-flow-external-events.html
    \else
    \previouspage creator-using-qt-quick-designer.html
    \endif
    \nextpage quick-shapes.html

    \title Creating Components

    A \e component is a reusable building block for a UI.

    \QDS comes with \e {preset components} that you can use in your project.
    These are similar to \e Symbols in Sketch or \e Prefab in Unity.

    Some of the preset components represent simple shapes, text, or images,
    while others represent complex UI controls with full functionality, such
    as spin boxes or sliders.

    You can modify the \e properties of the preset components and combine them
    to build your own components.

    A component is specified within one file (with the file extension
    \e ui.qml or \e .qml). For example, a Button component may be defined
    in \e Button.ui.qml. Typically, the visual appearance of a component
    is defined in a \e {UI file} (ui.qml).

    The \l {Library} view \uicontrol Components tab lists the components that
    have been added to your project.

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

    \note Use as few components as possible. To minimize the number of
    components, use \l{Adding Property Aliases}{alias properties} and
    \l{Adding States}{states} to create the differences in your component
    instances. We recommend reusing components instead of duplicating them,
    so the components do not need to be processed as completely new component
    types. This reduces the time needed to load and build the application,
    as well as the size of the application package.

    \section1 Adding Components to Designs

    \image qmldesigner-editing-components.png "Editing components in Form Editor"

    \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 Component 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 Components 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 {Connection 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 Creating Your Own Components

    You can either use project wizard templates to create custom components and
    controls or \l{Moving Components into Separate Files}{move subcomponents
    into separate files} to make them reusable in other components.

    \section2 Creating Components from Scratch

    To use wizard templates to create custom components:

    \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 Components}
            tab in the \uicontrol Library view only if the filename begins with
            a capital letter.

        \li Click \uicontrol Design to open the component file (ui.qml] in
            \uicontrol {Form Editor}.

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

        \li Edit component properties in \uicontrol Properties.

            \image qmldesigner-custom-component-properties.png

            The available properties depend on the component type. You can
            \l{Specifying Dynamic Properties}{add properties for
            components} in the \uicontrol Properties tab of the
            \uicontrol {Connection View}.

    \endlist

    The following sections contain more information about how to use
    \uicontrol {Form Editor} to edit 2D content and \uicontrol {3D Editor}
    to edit 3D scenes, as well as examples of how to create UI controls
    using basic components:

    \list

        \li \l{Form Editor}

        \li \l{3D Editor}

        \li \l{Creating Buttons}

        \li \l{Creating Scalable Buttons and Borders}

    \endlist

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

    \section2 Moving Components into Separate Files

    An alternative way of creating reusable components is to move them
    into separate component files (.ui.qml). Right-click a component
    in \uicontrol Navigator or \uicontrol {Form Editor} 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.

    When you select \uicontrol OK, a new component file is created and a
    reference to the component is added to the code in the current component
    file. The way things look in \uicontrol {Form Editor} does not change.

    To open the new component file for editing the properties that you want
    to change for all instances of the component, right-click the component
    and then select \uicontrol {Go into Component} in the context menu. For
    additional ways of opening subcomponents, see \l{Moving Within Components}.

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

    Custom components are listed in the \uicontrol {My Components} section
    of the \uicontrol Components tab in \uicontrol Library and you can use
    them to build more components.

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

    \section1 Merging Files with Templates

    You can merge the current component file against an existing second
    component file and using the second 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.
*/