/****************************************************************************
**
** Copyright (C) 2018 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 index.html
    \page creator-using-qt-quick-designer.html
    \if defined(qtdesignstudio)
    \previouspage studio-prototyping.html
    \else
    \previouspage creator-quick-ui-forms.html
    \endif
    \nextpage quick-components.html

    \title Editing QML Files in Design Mode

    \QC opens \l{Qt Quick UI Forms}{UI forms} (ui.qml files) in the
    \uicontrol {Form Editor} tab in the Design mode. It is
    recommended that you use UI forms for components that you want to
    edit in the Design mode.

    \image qmldesigner-visual-editor.png "Visual editor"

    To manage your project in the Design mode:

    \list

        \li \uicontrol Canvas (1) is the working area where you create QML
            components and design applications. In the \uicontrol {Form Editor}
            tab, you can use a visual editor to design UIs, and in the
            \uicontrol {Text Editor} tab, you can use a code editor to edit the
            QML code generated by the visual editor.

        \li Use the sidebars to select QML types to use in the project, to
            specify properties for them, and to
            view them in a tree structure, as well as to create connections
            and browse projects and files. You can select the content of the
            sidebars in the sidebar menu:

        \list

            \li \uicontrol {Library} (2) displays the building blocks that you
                can use to design applications: predefined QML types, your own
                QML components, or Qt Quick Controls 2 that you import to the
                project, and other resources. For more information, see
                \l {Creating Components}.

            \li \uicontrol {Navigator} (3) displays the items in the current QML
                file as a tree structure. For more information, see
                \l {Managing Item Hierarchy}.

            \li \uicontrol {Properties} (4) organizes the properties of the
                selected item. You can change the properties also in the
                \uicontrol {Text Editor}. For more information, see
                \l {Specifying Item Properties}.

            \li \uicontrol Connections (5) enables you to create connections
                between objects, signals, and object properties. For more
                information, see \l{Adding Connections}.

            \li \uicontrol {File System} shows all files in the currently
                selected directory. For more information, see
                \l{Viewing the File System}.

            \li \uicontrol {Open Documents} shows currently open files.

            \li \uicontrol {Projects} shows a list of projects open in the
                current session. For more information, see
                \l{Viewing Project Files}.

        \endlist

        \li \uicontrol {State} pane (6) displays the different states of the item.
            QML states typically describe user interface configurations, such as
            the UI controls, their properties and behavior and the available
            actions. For more information, see \l{Adding States}.

    \endlist

    \section1 Snapping to Parent and Sibling Items

    You design applications on the canvas by placing items on it.

    When you are working on a design, you can use snapping to align
    items on the canvas. Click the \inlineimage snapping.png
    button to have the items snap to their parent or sibling items. Snapping
    lines automatically appear to help you position the items.
    Click the \inlineimage snapping_and_anchoring.png
    button to anchor the item to the items that you snap to.

    Choose \uicontrol Tools > \uicontrol Options > \uicontrol {Qt Quick} >
    \uicontrol {\QMLD} to specify settings for snapping. In the
    \uicontrol {Parent item padding} field, specify the
    distance in pixels between the parent item and the snapping lines. In the
    \uicontrol {Sibling item spacing} field, specify the distance in pixels between
    sibling items and the snapping lines.

    The following image shows the snapping lines when \uicontrol {Parent item padding}
    is set to 5 pixels.

    \image qmldesigner-snap-margins.png "Snapping lines on canvas"

    \section1 Hiding Item Boundaries

    The Design mode displays the boundaries of items on the canvas. To hide
    the boundaries, click the \inlineimage boundingrect.png
    button.

    \section1 Selecting Items

    When you point the mouse to overlapping items, the frontmost item is
    selected by default. However, items that do not have any content, such as
    the mouse area, are typically located in front of items that do have
    content, such as rectangles or border images. To select items with content
    by default, click the
    \inlineimage qmldesigner-only-select-items-with-content.png
    button.

    \section1 Previewing Component Size

    The width and height of the root item in a QML file determine the size of
    the component. You can reuse components, such as buttons, in different
    sizes in other QML files and design screens for use with different device
    profiles, screen resolution, or screen orientation. The component size
    might also be zero (0,0) if its final size is determined by property
    bindings.

    To experiment with different component sizes, enter values in the
    \uicontrol {Override Width} and \uicontrol {Override Height} fields (1) on
    the canvas toolbar. The changes are
    displayed in the \uicontrol State pane (2) and on the canvas (3), but the property
    values are not changed permanently in the QML file. You can permanently
    change the property values in the \uicontrol Properties pane (4).

    \image qmldesigner-preview-size.png "Canvas width and height"

    \section1 Specifying Canvas Size

    To change the canvas size, select \uicontrol Tools > \uicontrol Options >
    \uicontrol {Qt Quick} > \uicontrol {\QMLD} and
    specify the canvas width and height in the \uicontrol Canvas group.

    \section1 Refreshing the Canvas

    When you open QML files in the Design mode, the items in the file are drawn
    on the canvas. When you edit the item properties, the QML file and
    the image on the canvas might get out of sync. For example, when you change
    the position of an item within a column or a row, the new position might
    not be displayed correctly on the canvas.

    To refresh the image on the canvas, press \key R or select the
    \inlineimage qmldesigner-reset-view.png
    (\uicontrol {Reset View}) button.

*/
