// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page qtquick-form-editor.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-design-qtquick

    \title Design 2D UIs

    To design applications in the \uicontrol {2D} view, open component files and
    place instances of \l{Component types}{2D components}
    and \l{Add assets}{assets} into them.

    \image {qmldesigner-form-editor.webp} {The 2D view.}

    When you select component instances in the \uicontrol {2D} view, markers
    appear around their edges and in their corners. Depending on the shape of
    the cursor, you can apply the following actions to the component instances
    by dragging them:

    \list
        \li Move
        \li Resize
        \li Rotate
    \endlist

    \section1 Move components

    When the move cursor is displayed, you can move the selected component
    instance to any position in the \uicontrol {2D} view.

    \image {qmldesigner-form-editor-move-cursor.webp} {Move cursor in the 2D view.}

    For more information about alternative ways of positioning component
    instances in UIs, see \l{Make layouts scalable}.

    \section1 Resize components

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

    \image {qtquick-designer-scaling-items.webp} {The 2D view.}

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

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

    To both resize from the center of the component instance and preserve the
    aspect ratio, select \key Alt+Shift (or \key {Opt+Shift} on \macos).

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

    \section1 Rotate components

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

    \image {qtquick-designer-rotating-items.webp} {2D rotation tool.}

    Additionally, select \key Shift or \key Alt (or \key Opt on \macos)
    to rotate component instances in steps of 5 or 45 degrees, respectively.

    You can set the \l{Manage 2D transformations}{origin} in \uicontrol {Properties} >
    \uicontrol {Geometry - 2D} > \uicontrol Origin. There, you can also enter
    the value of the \uicontrol Rotation property in degrees.

    \section1 Zoom in and out

    You can use the zoom buttons on the toolbar to zoom into and out of
    the \uicontrol {2D} view 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 component instances.

    \image {qmldesigner-zooming.gif} {Zooming in the 2D view.}

    \section1 Snap to parent and sibling components

    You can use snapping to align component instances in
    the \uicontrol {2D} view. With snapping turned on, all component instances
    snap to their parent and siblings. If you use snapping with anchors, anchors are created
    when you snap a component to another.

    To turn on snapping, right-click in the \uicontrol 2D view and select
    \uicontrol Snapping > \uicontrol {Snap with Anchors} or
    \uicontrol {Snap without Anchors}.

    Snapping lines automatically appear to help you position the component
    instances.

    Choose \uicontrol Edit > \uicontrol Preferences > \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 and the snapping lines. In the
    \uicontrol {Sibling component spacing} field, specify the
    distance in pixels between siblings and the snapping lines.

    \image {qtquick-designer-preferences.webp} {Qt Quick Designer preferences.}

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

    \image {qmldesigner-snap-margins.webp} {Snapping lines on canvas.}

    For alternative ways of aligning and distributing component instances by
    using the \uicontrol {Properties} view, see \l{Align and distribute components}.

    \section1 Hide component boundaries

    The \uicontrol {2D} view displays the boundaries of component instances.
    To hide them, right-click in the \uicontrol 2D view and select
    \uicontrol {Show Bounds} from the context menu.

    \section1 Preview 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{Set 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 {2D}
    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.webp} {Overriding component width and height.}

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

    \section1 Specify canvas size

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

    \section1 Set 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 instance you
    are working on. To make component instances more visible, you can select
    the canvas color in the \imagecanvascolor
    list. By default, the color is transparent. Setting the canvas color does
    not affect the background color of your root component or component
    instances in any way.

    \image {qmldesigner-canvas-color.webp} {Transparent canvas color for a transparent component instance.}

    \section1 Refresh the 2D view contents

    When you open a UI file, the component defined in the file and the component
    instances it contains are drawn in the \uicontrol {2D} view. When you
    edit component instance properties in \uicontrol {Properties}, the code and its
    representation in the \uicontrol {2D} view might get out of sync. For
    example, when you change the position of a component instance within a
    column or a row, the new position might not be displayed correctly in
    the \uicontrol {2D} view.

    To refresh the contents of the \uicontrol {2D} view, select the \key R key or
    the \imagereset (\uicontrol {Reset View}) button.

    \sa {Design Qt Quick UIs}{How to: Design Qt Quick UIs}, {Qt Quick UI design},
    {Designing Qt Quick UIs}
*/
