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

/*!
    \example transitions
    \previouspage creator-tutorials.html
    \nextpage creator-how-tos.html
    \ingroup creator-tutorials

    \keyword {Creating a Qt Quick Application}
    \title Tutorial: Qt Quick application

    \brief How to create a Qt Quick Application in the \uicontrol Edit mode.

    This tutorial illustrates basic concepts of \l{Qt Quick}. For more
    information about the UI choices you have, see \l{User Interfaces}.

    This tutorial describes how to use \QC to implement \l{Qt Quick States}
    {states} and \l{Animation and Transitions in Qt Quick}{transitions}
    when using Qt 6 as the minimum Qt version and CMake as the build system.

    You will use the \l{Editing code}{Edit} mode to create an application
    that moves a Qt logo between three rectangles when you select them.

    \image {qtquick-tutorial.gif} {Transitions example}

    For more examples, see \l{Qt Quick Examples and Tutorials}.

    You can use a visual editor to develop Qt Quick applications in the
    \uicontrol Design mode or in \QDS.

    \include qtquick-tutorial-create-empty-project.qdocinc qtquick empty application

    \QC generates a component file, \c Main.qml, and opens it in the
    \uicontrol Edit mode.

    \section1 Deploy applications

    The main view of the application displays a Qt logo inside a rectangle in
    the top left corner of the view and two empty rectangles.

    For the image to appear when you run the application, you must specify it
    as a resource in the \c RESOURCES section of \c CMakeLists.txt file that
    the wizard created for you:

    \quotefromfile transitions/CMakeLists.txt
    \skipto qt_add_qml_module
    \printuntil )

    \section1 Create a custom QML type

    Because the \l Window QML type requires that you add states into child
    components, use the wizard to create a custom QML type called
    \e Page that you refer to from \c Main.qml.

    To create a custom QML type:

    \list 1
        \li Go to \uicontrol File > \uicontrol {New File}.
        \li Select \uicontrol Qt > \uicontrol {QML File (Qt Quick 2)}.
        \li Select \uicontrol Choose to open the \uicontrol Location dialog.
        \li In \uicontrol {File name}, enter a name for the custom
            QML type: \e Page.
        \li Select \uicontrol Next to open the \uicontrol {Project Management}
            dialog.
        \li Select \uicontrol Finish to create \c Page.qml.
    \endlist

    \QC opens \c Page.qml in the \uicontrol Edit mode. It has a root item
    of the type \l Item. Replace it with a \l Rectangle type. Give the
    type the ID \e page, anchor it to the parent item on all sides, and set
    its color to white:

    \quotefromfile transitions/Page.qml
    \skipto import
    \printuntil color

    When you start typing the QML type name, \QC suggests available types
    and properties to \l{Complete code}{complete the code}.

    Select the light bulb icon
    \inlineimage {icons/refactormarker.png} {Light bulb icon} next to the
    type name to open a \l{Edit rectangles}{toolbar} that you can use to specify
    rectangle properties, such as color, transparency, and gradients.

    \image {qml-toolbar-rectangle.png} {Qt Quick toolbar for rectangles}

    Next, add an \l Image type with \c qt-logo.png as the source. You can also
    use any other image or a component. Position the image in the top-left
    corner of the rectangle:

    \printuntil }

    Use a \l{Preview images}{toolbar for images} to specify image properties,
    such as source file and fill mode.

    \image {qml-toolbar-image.png} {Logo visible in Qt Quick toolbar for images}

    Now, create the rectangles that the image will move between. Their size
    should match the image size and they should be transparent, so that the
    image is visible. Set the border color to light gray to make the
    rectangles visible:

    \printuntil border.color

    Anchor the rectangles to their parent to position them in its
    top-left and bottom-left corners, as well as the vertical center
    of its right edge. The following code snippet anchors a rectangle to
    the top-left corner of its parent:

    \printuntil anchors.topMargin

    Add a \l MouseArea type to make the rectangle clickable by users:

    \printuntil anchors.fill

    To check your code, compare it with the \c {Page.qml} example file.

    Next, make the image move between the rectangles when users click
    them by adding states and by connecting mouse clicks to state changes.

    \section1 Connect mouse clicks to state changes

    To make the image move between the rectangles when users select them, add
    states to the Page component where you change the values of the \c x and
    \c y properties of \e icon to match those of the middle right and top left
    rectangles. To make sure that the image stays within the rectangle
    when the view is scaled on different sizes of screens, \e bind the values
    of the \c x and \c y properties of \e icon to those of the rectangles:

    \dots
    \skipto states:
    \printuntil ]

    Then, connect the \c onClicked signals of the mouse areas to the state
    changes:

    \quotefromfile transitions/Page.qml
    \skipto Connections {
    \printuntil }

    Because you develop with Qt 6, you must specify the connections as functions.

    \section1 Add Page to the main view

    Open \c Main.qml for editing and add an instance of the Page custom
    component to it:

    \quotefromfile transitions/main.qml
    \skipto import
    \printuntil /^\ {0}\}/

    Select \key {Ctrl+R} to run the application, and then select the rectangles to
    move the Qt logo from one rectangle to another.

    \section1 Animate transitions

    Create transitions to apply animation to the image. For example,
    the image bounces back when it moves to \e middleRightRect and eases into
    \e bottomLeftRect.

    Specify transitions for switching from each state to the other two
    states:

    \quotefromfile transitions/Page.qml
    \skipto transitions:
    \printuntil },

    Change the easing curve type for transitions to \e State2 from linear to
    \c Easing.OutBounce to create the bounce effect:

    \printuntil },

    \note Use a \l{Preview animations}{toolbar for animations} to specify the
    easing curve type and animation duration.

    \image {qml-toolbar-animation.png} {Qt Quick Toolbar for animation}

    Then, change the easing curve type for transitions to \e State2 from
    linear to \c Easing.InOutQuad to create the easing effect:

    \printuntil /^\ {0}\}/

    Select \key {Ctrl+R} to run the application, and then select the rectangles to
    view the animated transitions.

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