qt-creator/doc/src/qtquick/qtquick-components.qdoc

/****************************************************************************
**
** Copyright (C) 2016 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.
// **********************************************************************

/*!

    \contentspage {Qt Creator Manual}
    \previouspage qmldesigner-connections.html
    \page quick-components.html
    \nextpage quick-buttons.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
    screens and applications.

    You can use the following QML types to create components:

    \list

        \li \l [QML]{BorderImage}{Border Image} uses an image as a border or background.

        \li \l [QML]{Image}
            adds a bitmap to the scene. You can stretch and tile images.

        \li \l [QML]{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 [QML]{Rectangle}
            adds a rectangle that is painted with a solid fill color and an
            optional border. You can also use the radius property to create
            rounded rectangles.

        \li \l [QML]{Text} adds formatted read-only text.

        \li \l [QML]{TextEdit}{Text Edit}
            adds a single line of editable formatted text that can be validated.

        \li \l [QML]{TextInput}{Text Input}
            adds a single line of editable plain text that can be validated.

        \omit
        \li \l{WebView} adds web content to a canvas.
        \endomit

    \endlist

    \section1 Using Qt Quick Controls

    In Qt 4, ready-made Qt Quick 1 Components were provided for creating
    screens 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 2}{styling architecture} when compared to
    Qt Quick Controls, on which the module is based. \QMLD 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 \QMLD, see
    \l {Qt Quick Controls 2 - Flat Style}.

    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 Qt Quick Designer

    \list 1

        \li Select \uicontrol File > \uicontrol {New File or Project} >
            \uicontrol {Files and Classes} > \uicontrol Qt >
            \uicontrol {QML File (Qt Quick 2)} > \uicontrol Choose to create a new .qml
            file.

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

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

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

        \li Edit its properties in the \uicontrol Properties pane.

            The available properties depend on the QML type.

    \endlist

    The following sections contain examples of how to create some common
    components:

    \list

        \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 on the canvas,
    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"
*/