qt-creator/doc/qtcreator/src/qtquick/qtquick-form-editor.qdoc

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

/*!
    \page qtquick-form-editor.html
    \previouspage creator-using-qt-quick-designer.html
    \nextpage studio-3d-editor.html

    \title Form Editor

    You design applications in the \uicontrol {Form Editor} view by placing
    \l{Component Types}{2D components} and \l{Assets}{assets} into it.

    \image qmldesigner-form-editor.png "Form Editor view"

    When you select components in \uicontrol {Form Editor}, markers appear
    around their edges and in their corners. Depending on the shape of the
    cursor, you can apply the following actions on the components by dragging
    them:

    \list
        \li \l{Moving Components}{Move components}
        \li \l{Resizing 2D Components}{Resize components}
        \li \l{Rotating 2D Components}{Rotate components}
    \endlist

    \section1 Summary of Form Editor Buttons

    The \uicontrol {Form Editor} toolbar contains the following buttons and
    fields.

    \table
    \header
        \li Button/Field
        \li Tooltip
        \li Read More
    \row
        \li \inlineimage no_snapping.png
        \li Disables snapping.
        \li \l{Snapping to Parent and Sibling Components}
    \row
        \li \inlineimage snapping_and_anchoring.png
        \li Anchors the component to the components that it is snapped to.
        \li \l{Snapping to Parent and Sibling Components}
    \row
        \li \inlineimage snapping.png
        \li Snaps components to their parent or sibling components when you
            align them.
        \li \l{Snapping to Parent and Sibling Components}
    \row
        \li \inlineimage boundingrect.png
        \li Hides and shows component boundaries.
        \li \l{Hiding Component Boundaries}
    \row
        \li \uicontrol {Override Width}
        \li Shows a preview of the component using the specified width.
        \li \l{Previewing Component Size}
    \row
        \li \uicontrol {Override Height}
        \li Shows a preview of the component using the specified height.
        \li \l{Previewing Component Size}
    \row
        \li \inlineimage icons/canvas-color.png
        \li Sets the color of the \uicontrol {Form Editor} working area.
        \li \l{Setting Canvas Color}
    \row
        \li \inlineimage icons/zoomIn.png
        \li Zooms in.
        \li \l{Zooming}
    \row
        \li \inlineimage icons/zoomOut.png
        \li Zooms out.
        \li \l{Zooming}
    \row
        \li Zoom level
        \li Sets the zoom level that you select from the list.
        \li \l{Zooming}
    \row
        \li \inlineimage icons/zoomAll.png
        \li Zooms to fit all content.
        \li \l{Zooming}
    \row
        \li \inlineimage icons/zoomSelection.png
        \li Zooms to fit the current selection.
        \li \l{Zooming}
    \row
        \li \inlineimage reset.png
        \li Refreshes the contents of \uicontrol {Form Editor}.
        \li \l{Refreshing Form Editor Contents}
    \endtable

    \section1 Moving Components

    When the move cursor is displayed, you can move the selected component to
    any position in \uicontrol {Form Editor}.

    \image qmldesigner-form-editor-move-cursor.png "Move cursor in Form Editor view"

    For more information about alternative ways of positioning components in
    UIs, see \l{Positioning Components}.

    \section1 Resizing 2D Components

    When the resize cursor is displayed, you can drag the markers to resize
    components.

    \image qtquick-designer-scaling-items.png "Form Editor view"

    To have the resizing done from the center of the selected component rather
    than from its edges, press \key Alt (or the option key on \macos).

    To preserve the image aspect ratio while resizing when using the corner
    markers, press \key Shift. This also works on components that are anchored
    using left, right, top, or bottom anchors.

    To both resize from the center of the component and preserve the aspect
    ratio, press \key Alt+Shift (or the option key + \key Shift on \macos).

    For more information about alternative ways to specify the size of a
    component in a UI, see \l{2D Geometry}.

    \section1 Rotating 2D Components

    When the rotation cursor \inlineimage icons/rotation-cursor.png
    is displayed in one of the corners of a component, you can drag
    clockwise or counter-clockwise to freely rotate the component around
    its origin.

    \image qtquick-designer-rotating-items.png "2D rotation tool"

    Additionally, press \key Shift or \key Alt (or the option key on \macos)
    to rotate components in steps of 5 or 45 degrees, respectively.

    You can set the \l{Managing 2D Transformations}{origin} in the
    \uicontrol Origin field in the \uicontrol Advanced tab in the
    \l Properties view. There, you can also enter the value
    of the \uicontrol Rotation property in degrees.

    \section1 Zooming

    You can use the zoom buttons on the toolbar to zoom into and out of
    \uicontrol {Form Editor} or select the zoom level as a percentage
    from a list. More buttons are availabe for zooming to fit all content
    in the view or zooming to fit the currently selected components.

    \image qmldesigner-zooming.gif "Zooming in Form Editor"

    \section1 Snapping to Parent and Sibling Components

    You can use snapping to align components in \uicontrol {Form Editor}.
    Click the \inlineimage snapping.png
    button to have the components snap to their parent or sibling components.
    Snapping lines automatically appear to help you position the components.
    Click the \inlineimage snapping_and_anchoring.png
    button to anchor the component to the components that you snap to.
    Only one snapping button can be selected at the time. Selecting
    one snapping button automatically deselects the others.

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

    \image qtquick-designer-options.png "Qt Quick Designer options"

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

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

    For alternative ways of aligning and distributing components by using the
    \l Properties view, see \l{Aligning and Distributing Components}.

    \section1 Hiding Component Boundaries

    \uicontrol {Form Editor} displays the boundaries of components.
    To hide them, select the \inlineimage boundingrect.png
    button.

    \section1 Previewing Component Size

    The width and height of the root component in a UI file determine the size
    of the component. You can reuse components, such as buttons, in different
    sizes in other UI files and design UIs 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
    \l{Setting Bindings}{property bindings}.

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

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

    To set the initial size of the root component, select \uicontrol Tools >
    \uicontrol Options > \uicontrol {Qt Quick} > \uicontrol {Qt Quick Designer}
    and specify the component width and height in the
    \uicontrol {Root Component Init Size} group.

    \section1 Specifying Canvas Size

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

    \section1 Setting Canvas Color

    If you set the background of the root component transparent, the color of
    the working area can make it difficult to see the component you are working
    on. To make components more visible, you can select the canvas color in
    the \inlineimage icons/canvas-color.png
    list. By default, the color is transparent. Setting the canvas color does
    not affect the background color of your UI or components in any way.

    \image qmldesigner-canvas-color.png "Transparent canvas color for a transparent component"

    \section1 Refreshing Form Editor Contents

    When you open a UI file, the components in the file are drawn in
    \uicontrol {Form Editor}. When you edit component properties in
    \l Properties, the code and its representation in \uicontrol {Form Editor}
    might get out of sync. For example, when you change the position of a
    component within a column or a row, the new position might not be displayed
    correctly in \uicontrol {Form Editor}.

    To refresh the contents of \uicontrol {Form Editor}, press \key R or
    select the \inlineimage reset.png
    (\uicontrol {Reset View}) button.

    \include qtquick-component-context-menu.qdocinc context-menu
*/